Skip to content
NearGate

USE NEARGATE

Sell & buy

Step by step on the live deployment on NEAR testnet: put your API behind the hosted gateway and get paid per call, or pay for calls yourself, from an agent with a restricted key, from Claude Desktop or from your own code. Every command uses the npm CLI.

CLI v0.2.1SDK v0.1.0registry neargate-app-registry.testnetnear-testnet

Before you start: an account and its key

Both roles need the CLI and a funded NEAR testnet account whose key is on your machine:

$ npm install -g @neargate/cli

Your key never leaves your machine

The CLI and the SDK sign every transaction locally and send it to a NEAR RPC. NearGate never receives a key: the gateway sees the hash of the buyer’s pay transaction, the owner’s signature on a mapping request, or a signed gasless delegate. The dashboard only reads the chain; it has no wallet to connect.

A new account

The near CLI creates one through the testnet faucet and saves its key where NearGate looks for it, ~/.near-credentials/testnet/<you>.testnet.json:

$ near account create-account sponsor-by-faucet-service <you>.testnet autogenerate-new-keypair --signature-scheme ed25519 save-to-legacy-keychain network-config testnet create

An account you already have

Import it into the same place. Run the command and answer its prompts, so no secret lands in your shell history:

$ near account import-account

Choose using-web-wallet to sign in through your wallet in the browser (it adds a new key for the CLI, so you copy no secret), or using-private-key / using-seed-phrase; then the network testnet and save-to-legacy-keychain.

Where the key goes

The CLI takes the account from --account and looks for its key in this order; the first one found wins. On buy, escrow, agent-key and mcp the variables start with BUYER_; on wrap, map, pause and resume, with SELLER_.

OrderWhereUse it for
1BUYER_PRIVATE_KEY=ed25519:…a secret in the environment, e.g. from a secrets manager on a server
2--key-file <path>, or BUYER_KEY_PATHa near CLI credentials JSON elsewhere: an agent key, or a key kept outside the default folder
3~/.near-credentials/testnet/<account>.jsonthe default: where the near CLI saved it above

A key file is the near CLI’s JSON, { "account_id", "public_key", "private_key" }. Keep it chmod 600 (the CLI warns otherwise), never commit it, and never paste it into a chat or a form. Every flag and variable: CLI → signer flags.

Sell: put your API behind the gateway

You keep running your API. The hosted gateway answers callers with an invoice, checks each payment on chain, forwards the paid call to your API and records the result in the registry; the price goes straight to your account at payment time.

  1. 01

    Check your API

    The gateway calls it over the internet, so it needs a public https URL with no user name or password in it. A 2xx answer is a successful call; any other status is recorded as a failed one. The gateway does not follow redirects, forwards at most 1 MiB each way and waits up to 30 s. On the hosted gateway the API also needs an IPv6 address: the two IPv4-only APIs tried from it could not be reached. Check for an AAAA record:
    dig +short AAAA api.example.com
  2. 02

    Wrap it

    One command registers the service on the registry and hands your API’s URL to the gateway in a request signed by your account’s full-access key; the URL never goes on chain. It attaches a 0.12 NEAR deposit for the service’s storage and prints the service id, its public endpoint, its dashboard page and the register_service transaction. Name neargate-app-gateway.testnet as the attestor: the gateway records each call’s result as that account, and the registry refuses its attestations for a service that names another attestor, so those calls are never scored.
    neargate wrap https://api.example.com/v1/rates --price 0.01 --name "My rates API" --description "What a caller gets" --account <you>.testnet --attestor neargate-app-gateway.testnet --gateway https://neargate-gateway-production.up.railway.app
  3. 03

    Check the invoice

    An unpaid call to the public endpoint answers 402 with the x402 invoice: your price plus the 0.002 NEAR storage fee, paid to the registry neargate-app-registry.testnet.
    curl -i https://neargate-gateway-production.up.railway.app/svc/<id>
  4. 04

    Test it from another account

    Buy one call with a different account. A call paid by the owner or the payment target is served but never counted (ERR_SELF_PAYMENT), so a self-test leaves the score at 0/0.
    neargate buy <id> --account <tester>.testnet --max 0.05
  5. 05

    Watch it

    status prints the record, the score and the latest attestations; the dashboard shows the same at https://neargate-dashboard-production.up.railway.app/services/<id>. The score is the count of successful calls over all counted calls.
    neargate status <id>

Options worth knowing

OptionWhat it does
--price <near>The price per call in NEAR. Buyers attach it plus 0.002 NEAR for the payment record.
--payment-target <account>Where the price goes; by default the account that wraps.
--name, --descriptionAt most 64 and 280 bytes. Both are fixed once registered.

Change it later

ToRunNotes
point the service at another URLneargate map <id> <new url> --account <you>.testnetA request to the gateway signed by your key; no transaction.
stop or restart salesneargate pause <id> / neargate resume <id>, with --accountA set_active transaction. A paused service answers 403 and takes no payment.
change the name, description, price or gatewaypause it and wrap a new serviceThe registry has no method to edit them.

Buy: pay for a call

Every rail ends the same way: the payment is recorded in the registry, the gateway serves the call and records whether it succeeded. They differ in what pays and which key signs.

RailFlagWhat paysKey that signs
Deposit (default)—your account: price + 0.002 NEAR attached to payyour full-access key
Escrow--from-escrowa balance you prepaid in the registrya restricted agent key (or your full-access key)
Gasless--gaslessthe escrow; the gateway pays the gasa restricted agent key, as a signed delegate

One call from your own account

  1. 01

    Find a service

    The catalog and one service in full, from the registry, with no key.
    neargate list neargate status <id>
  2. 02

    Buy one call

    The response goes to stdout; the receipt (amount, the pay transaction and its explorer link, the HTTP status) to stderr. Always pass --max: an invoice above it is refused with BUDGET_EXCEEDED before anything is paid.
    neargate buy <id> --account <you>.testnet --max 0.05
  3. 03

    If it was paid but not served

    PAID_NOT_SERVED names the transaction and the nonce. Do not buy again (that pays twice): present the same proof again once the gateway answers. See the error codes.

An agent that pays with a restricted key

Give an agent a key that NEAR itself limits to pay_from_escrow on the registry, and keep your full-access key to yourself. The escrow is the agent’s spending limit.

  1. 01

    Fund an escrow (your full-access key)

    The first deposit keeps 0.002 NEAR for the escrow’s storage.
    neargate escrow deposit 0.5 --account <you>.testnet
  2. 02

    Add an agent key (your full-access key)

    Adds a function-call key that may call only pay_from_escrow, with --allowance NEAR of gas. The secret is written to ~/.near-credentials/testnet/<you>.testnet.neargate-agent.json (mode 0600); only its public key and path are printed.
    neargate agent-key add --allowance 0.25 --account <you>.testnet
  3. 03

    The agent buys with that key

    From the escrow, or gasless: the hosted gateway relays the signed pay_from_escrow and pays the gas, so the account’s balance does not move.
    neargate buy <id> --from-escrow --account <you>.testnet --key-file ~/.near-credentials/testnet/<you>.testnet.neargate-agent.json --max 0.05 neargate buy <id> --gasless --account <you>.testnet --key-file ~/.near-credentials/testnet/<you>.testnet.neargate-agent.json --max 0.05
  4. 04

    Top up or take it back

    Withdrawing needs the full-access key: an agent key cannot.
    neargate escrow balance <you>.testnet neargate escrow withdraw 0.2 --account <you>.testnet

If an agent key leaks

It can spend the escrow, on any active service, and burn gas up to its allowance; nothing else. Keep both small. Revoke it by deleting the key with your full-access key (near account delete-keys). More in the security model.

From Claude Desktop (MCP)

The CLI’s MCP server gives an agent five tools: list, inspect, get an invoice, read the escrow balance and buy (capped by maxNear). Point it at the agent key:

claude_desktop_config.json

{
  "mcpServers": {
    "neargate": {
      "command": "neargate",
      "args": [
        "mcp",
        "--account",
        "<you>.testnet",
        "--key-file",
        "~/.near-credentials/testnet/<you>.testnet.neargate-agent.json"
      ]
    }
  }
}

The tools and their parameters: CLI → mcp.

From your own code (@neargate/sdk)

@neargate/sdk is the paying client the CLI runs, as one ES module with types (Node 22.22.2 or later). fetchPaid requests the URL, checks the invoice against the registry and your cap, pays, retries with the proof and returns the response.

$ npm install @neargate/sdk

pay for one call

import { createAgentGateClient, createNearGateChain, nearToYocto } from '@neargate/sdk';

// Live mode on NEAR testnet and the deployed registry, by default.
const chain = createNearGateChain();
const client = createAgentGateClient({
  chain,
  // Reads ~/.near-credentials/testnet/you.testnet.json; or pass keyPath or secretKey.
  signer: { kind: 'near', accountId: 'you.testnet' },
  maxYocto: nearToYocto('0.02'), // refuse any invoice above 0.02 NEAR in total
  expectedServiceId: 1,
});

const res = await client.fetchPaid('https://neargate-gateway-production.up.railway.app/svc/1');
console.log(res.status, res.txHash, res.body);

escrow and gasless

// Pay out of a prepaid escrow, or gasless (the gateway relays and pays the gas).
const signer = { kind: 'near', accountId: 'you.testnet', keyPath: '~/.near-credentials/testnet/<you>.testnet.neargate-agent.json' } as const;
const escrowClient = createAgentGateClient({ chain, signer, maxYocto: nearToYocto('0.02'), payFrom: 'escrow' });
const gaslessClient = createAgentGateClient({ chain, signer, maxYocto: nearToYocto('0.02'), payFrom: 'escrow', gasless: true });

A refusal before paying throws an AgentGateError with a stable code; a call that was paid but not served throws PaidNotServedError with the proof to present again. To build a client from scratch instead, follow How it works.