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.
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
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_.
| Order | Where | Use it for |
|---|---|---|
| 1 | BUYER_PRIVATE_KEY=ed25519:… | a secret in the environment, e.g. from a secrets manager on a server |
| 2 | --key-file <path>, or BUYER_KEY_PATH | a near CLI credentials JSON elsewhere: an agent key, or a key kept outside the default folder |
| 3 | ~/.near-credentials/testnet/<account>.json | the 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.
- 01
Check your API
The gateway calls it over the internet, so it needs a publichttpsURL with no user name or password in it. A2xxanswer 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 - 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 a0.12 NEARdeposit for the service’s storage and prints the service id, its public endpoint, its dashboard page and theregister_servicetransaction. Nameneargate-app-gateway.testnetas 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 - 03
Check the invoice
An unpaid call to the public endpoint answers402with the x402 invoice: your price plus the 0.002 NEAR storage fee, paid to the registryneargate-app-registry.testnet.curl -i https://neargate-gateway-production.up.railway.app/svc/<id> - 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 - 05
Watch it
statusprints the record, the score and the latest attestations; the dashboard shows the same athttps://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
| Option | What 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, --description | At most 64 and 280 bytes. Both are fixed once registered. |
Change it later
| To | Run | Notes |
|---|---|---|
| point the service at another URL | neargate map <id> <new url> --account <you>.testnet | A request to the gateway signed by your key; no transaction. |
| stop or restart sales | neargate pause <id> / neargate resume <id>, with --account | A set_active transaction. A paused service answers 403 and takes no payment. |
| change the name, description, price or gateway | pause it and wrap a new service | The 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.
| Rail | Flag | What pays | Key that signs |
|---|---|---|---|
| Deposit (default) | — | your account: price + 0.002 NEAR attached to pay | your full-access key |
| Escrow | --from-escrow | a balance you prepaid in the registry | a restricted agent key (or your full-access key) |
| Gasless | --gasless | the escrow; the gateway pays the gas | a restricted agent key, as a signed delegate |
One call from your own account
- 01
Find a service
The catalog and one service in full, from the registry, with no key.neargate list neargate status <id> - 02
Buy one call
The response goes to stdout; the receipt (amount, thepaytransaction and its explorer link, the HTTP status) to stderr. Always pass--max: an invoice above it is refused withBUDGET_EXCEEDEDbefore anything is paid.neargate buy <id> --account <you>.testnet --max 0.05 - 03
If it was paid but not served
PAID_NOT_SERVEDnames 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.
- 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 - 02
Add an agent key (your full-access key)
Adds a function-call key that may call onlypay_from_escrow, with--allowanceNEAR 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 - 03
The agent buys with that key
From the escrow, or gasless: the hosted gateway relays the signedpay_from_escrowand 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 - 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
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.
keep reading