USE NEARGATE
CLI & MCP
The neargate CLI publishes services, buys one paid call to any of them (from a deposit or from a prepaid escrow), inspects the on-chain catalog, toggles a service you own, funds an escrow and mints restricted agent keys that can spend only that escrow, mints demo accounts on the offline devnet, and serves NearGate to agent frameworks as an MCP server.
Invocation
The CLI is on npm as @neargate/cli. Install it once and it is the neargate binary, which runs from any folder; every example on this page uses it:
$ npm install -g @neargate/cli
$ neargate <command> [args] [options]
To run one command without installing, use npx -y @neargate/cli <command>. In a clone of the repository, the root script runs the same CLI from source, from the repository root only (anywhere else npm answers Missing script: "neargate"); everything after the -- is forwarded, so neargate status 1 becomes:
$ npm run neargate -- status 1
To pay from your own code instead, @neargate/sdk (npm install @neargate/sdk) bundles the paying client with its types: createNearGateChain() reads and pays on the live deployment, and createAgentGateClient(…).fetchPaid(url) pays one call.
The entry point is packages/cli/src/bin.ts (a commander program named neargate). npm run build -w @neargate/cli bundles it to packages/cli/dist/bin.js, which you can run with node directly — the form the Claude Desktop config uses from a clone. neargate --version prints the version. There are eleven commands: wrap, map, list, buy, status, pause, resume, demo-accounts, escrow, agent-key and mcp. Every command exits 0 on success and 1 on error; failures print one line to stderr, error: <CODE>: <message> (see Error codes). Two kinds of failure carry no code: a usage mistake, reported by the argument parser, and a raw network failure outside the stable codes (for example error: fetch failed when buy cannot reach the gateway). One partial failure exits 0: a wrap whose registration landed but whose gateway mapping failed (see wrap).
Environment & flags
Each setting can be a flag or an environment variable; precedence is flag > env var > built-in default. The CLI defaults to live mode on the deployed registry, so list and status read NEAR testnet with no key; pass --mode mock (or set AGENTGATE_MODE=mock) to use the offline devnet from npm run dev. Every command loads the whole configuration first, so a malformed environment variable it does not even use (say TRUST_PROXY=yes) stops it with CONFIG_INVALID.
Config flags
Accepted by every command:
--mode <mock|live>AGENTGATE_MODEoptionaldefault live- The chain backend: the offline devnet or NEAR.
--rpc <url>NEAR_RPC_URLoptional- The NEAR RPC. Default: the RPC of NEAR_NETWORK (testnet: FastNEAR, https://test.rpc.fastnear.com).
--registry <contract id>REGISTRY_CONTRACT_IDoptionaldefault neargate-app-registry.testnet- The registry contract account. Default: the shared registry the hosted gateway and dashboard use; the badge at the top of each docs page shows it.
wrap also takes --admin-token (AGENTGATE_ADMIN_TOKEN, default dev-admin-token), read in mock mode only; no other command accepts the flag. A flag lands in shell history and ps, so prefer the environment variable.
Signer flags and key resolution
Commands that write to the chain take the account to act as. The same two flags mean the seller on wrap, map, pause and resume, and the buyer on buy, escrow, agent-key and mcp.
| Flag | Seller env | Buyer env |
|---|---|---|
--account <id> | SELLER_ACCOUNT_ID | BUYER_ACCOUNT_ID |
--key-file <path> | SELLER_KEY_PATH | BUYER_KEY_PATH |
| no flag (a secret) | SELLER_PRIVATE_KEY | BUYER_PRIVATE_KEY |
In mock mode the account is --account, else MOCK_SELLER_ACCOUNT / MOCK_BUYER_ACCOUNT (default seller.mock / buyer.mock; print a funded pair with demo-accounts); mock signers carry no key and --key-file is ignored with a note. In live mode the CLI resolves the key before any chain call, first match wins:
| Source, in order | Notes |
|---|---|
1 · SELLER_PRIVATE_KEY / BUYER_PRIVATE_KEY | An ed25519:… secret key. It wins over --key-file, and the CLI says so when both are set. |
2 · --key-file, else SELLER_KEY_PATH / BUYER_KEY_PATH | A near-cli credentials JSON (account_id, public_key, private_key) whose account_id must match the account. |
3 · ~/.near-credentials/<network>/<account>.json | Where the near CLI keeps keys; npm run near:bootstrap writes it here. With no secret, no key file and no file here, the command stops with SIGNER_MISSING. |
The CLI warns when a key file is readable by group or others (chmod 600 it) and never prints key material.
Other variables
NEAR_NETWORK'testnet' | 'mainnet'optionaldefault testnet- Picks the default RPC and explorer and the
~/.near-credentials/<network>folder. The published defaults and every example target testnet. NEAR_EXPLORER_URLstring (url)optionaldefault https://testnet.nearblocks.io- Base of every explorer link the CLI prints in live mode:
buy’s payment and its gaslesswaiting:line,escrow deposit/withdraw,agent-key add, and theTX_TIMEOUTandGASLESS_NOT_SERVEDmessages. UPSTREAM_TIMEOUT_MSnumber (ms)optionaldefault 30000- How long
wrapandmapwait for the gateway’s mapping answer, anddemo-accountsfor the devnet faucet. MIDDLEWARE_PORTnumberoptionaldefault 4021- Mock mode only: the default
wrap --gatewayishttp://localhost:<MIDDLEWARE_PORT>. In live mode it is the sharedhttps://neargate-gateway-production.up.railway.app. DASHBOARD_PORTnumberoptionaldefault 3000- Mock mode only: the dashboard link
wrapprints ishttp://localhost:<DASHBOARD_PORT>/services/<id>. In live mode it points at the sharedhttps://neargate-dashboard-production.up.railway.app. DEVNET_URLstring (url)optionaldefault http://localhost:4030- The offline devnet that mock mode reads and
demo-accountsfunds from (derived fromDEVNET_PORT).
wrap
Registers a service on-chain and puts the 402 paywall in front of your API. The upstream URL is kept private: it is only ever sent to the gateway.
$ neargate wrap <upstreamUrl> --price <near> --name <name> [options]
<upstreamUrl>urlrequired- The http(s) API to wrap.
--price <near>NEAR decimalrequired- Price per call, at least
0.000001NEAR (the registry minimum, elseINVALID_PRICE). Buyers attach this plus the flat0.002 NEARstorage fee. --name <name>stringrequired- Service name, at most 64 bytes (UTF-8), no control characters.
--description <d>stringoptional- At most 280 bytes (UTF-8).
--gateway <url>urloptional- Gateway base URL, stored on-chain (at most 200 bytes, no query string or fragment); readers derive the endpoint
<gateway>/svc/<id>. Live mode needshttps://unless the host is localhost (INSECURE_URL). Without the flag, live mode uses the hosted gatewayhttps://neargate-gateway-production.up.railway.app. Mock mode defaults to the local gateway,http://localhost:<MIDDLEWARE_PORT>. --payment-target <account>NEAR account idoptionaldefault the seller account- The account that receives each price. Live mode checks it exists first (ACCOUNT_NOT_FOUND), because the registry forwards every price there.
--attestor <account>NEAR account idoptionaldefault the seller account- The account allowed to record attestations besides the owner. A live gateway attests as its own account (
GATEWAY_ACCOUNT_ID), so set this to the account of the gateway that serves the service: with the default, every attestation that gateway sends is rejected (ERR_NOT_AUTHORIZED) and paid calls never reach the score. The hosted gateway attests asneargate-app-gateway.testnet.
Plus the signer flags (seller) and --admin-token. The command validates everything and, in live mode, loads your key and checks the payment target before anything is sent; then it calls register_service (attaching the 0.12 NEAR registration deposit) and maps the upstream on the gateway. In live mode the mapping is a request signed with your key — no shared admin token (see the self-map signature); in mock mode it goes through the gateway’s admin route with the admin token.
Example
neargate wrap http://localhost:4010/feed --price 0.5 --name "RWA FX & Gold Oracle" --mode mock
service id: 1 public endpoint: http://localhost:4021/svc/1 dashboard: http://localhost:3000/services/1 register tx: <tx hash>
On testnet, behind the hosted gateway (no --gateway needed), with the gateway as attestor so its attestations count:
$ neargate wrap https://<your api> --price 0.01 --name "<name>" --attestor neargate-app-gateway.testnet --account <seller>.testnet
IF THE MAPPING FAILS, DO NOT RE-RUN WRAP
503 until it is mapped. wrap prints the exact retry to stderr (a warning: line) and notes the failure on stdout, then exits 0, because the registration succeeded. Re-running wrap would register a duplicate; use map instead.map
Re-sends only the signed mapping request of wrap for a service you already own; it never registers. Live mode only: in mock mode it refuses with LIVE_ONLY and prints the admin-route curl to use instead.
$ neargate map <id> <upstreamUrl> --account <owner>
It reads the service on-chain, checks that your key’s account is its owner (NOT_SERVICE_OWNER) and maps at the gateway the registry records for it, printing service id, gateway, public endpoint and mapping: ok.
list
The on-chain catalog with scores and trust tiers. No key. The table goes to stdout (header included, so scripts can parse it); the empty-catalog hint goes to stderr.
$ neargate list
output
id name price(NEAR) calls tier active 1 RWA FX & Gold Oracle 0.5 1/1 new yes
price(NEAR) is the service price (each call also attaches the 0.002 NEAR storage fee); calls is successful/total attested calls; tier is new, reliable or trusted.
buy
Buys one call: fetches the 402 invoice, pays it with a registry pay call (price + the storage fee attached), retries with the transaction as proof and prints the result. The response body goes to stdout (pipeable); the receipt goes to stderr.
$ neargate buy <id> --account <buyer> --max <near> [--from-escrow | --gasless]
<id>positive integerrequired- The service id (see list).
--max <near>NEAR decimaloptional- Budget cap on the total attached — price +
0.002 NEAR— checked before anything is paid (BUDGET_EXCEEDED). Without it there is no cap. --from-escrowflagoptional- Pay out of your prepaid escrow with
pay_from_escrowinstead of attaching a deposit topay: nothing is attached and the escrow is debited the same total, price +0.002 NEAR. If the escrow holds less,buyfails withERR_ESCROW_INSUFFICIENTbefore sending anything.--maxstill caps the total. This is the call a restricted agent key can sign. --gaslessflagoptional- Pays gasless; it implies --from-escrow, and the account pays no gas either:
buysigns thepay_from_escrowas a NEP-366 delegate and sends it as the proof, and the gateway relays it and pays the gas (the gasless rail). The escrow pays price +0.002 NEAR; nothing is sent from the account. The gateway’s 402 must offer a relayer, elseRELAYER_UNAVAILABLEbefore anything is signed; the escrow checks of--from-escrowrun next. An agent key can sign it. While the gateway answerssettlement_pending(its relay is settling),buypresents the same signed delegate again, waiting the gateway’s Retry-After (1–10 s), until the gateway answers definitively, for at most 150 s; it prints onewaiting:line on stderr meanwhile. --method <method>stringoptionaldefault GET- HTTP method of the paid request.
--body <json>stringoptional- JSON request body to send with the paid request. It must parse as JSON (INVALID_INPUT otherwise, before anything is paid): the gateway refuses other bodies.
--gateway <url>urloptionaldefault the service’s on-chain endpoint- Gateway base URL; the request goes to <gateway>/svc/<id>.
Example receipt
stderr
waiting: the gateway's relay (tx <tx hash>, <explorer>/txns/<tx hash>) is settling; presenting the same signed delegate again for up to 150 s (with --gasless, only while its relay settles; the explorer link in live mode only) service: #1 RWA FX & Gold Oracle url: http://localhost:4021/svc/1 paid: 0.5 NEAR + 0.002 NEAR storage from: escrow (nothing attached; the escrow was debited) (with --from-escrow or --gasless) relayed: gasless — <relayer> relayed the signed pay_from_escrow and paid the gas (with --gasless only) payment: <tx hash> explorer: <NEAR_EXPLORER_URL>/txns/<tx hash> (live mode only) settled: ok (payer buyer-1abba006.mock) status: 200
Never pay twice for one call. If the payment went through but the gateway did not serve the call, buy fails with PAID_NOT_SERVED naming the transaction and nonce (with --gasless, GASLESS_NOT_SERVED naming the nonce, whether the escrow paid and, when the gateway gave it, the relay transaction); see Error codes before buying again.
status
One service in full: record, price (with the storage fee), payment target, owner, attestor, trust tier with the score, and its 10 latest attestations. No key.
$ neargate status <id>
pause
Owner only: calls set_active(false). A paused service takes no new payments (the registry’s pay panics ERR_SERVICE_INACTIVE) and its gateway answers 403 service_inactive. Prints the service, its new state and the transaction.
$ neargate pause <id> --account <owner>
resume
Owner only: calls set_active(true); calls flow again.
$ neargate resume <id> --account <owner>
Signing as anyone but the owner is rejected by the registry with ERR_NOT_AUTHORIZED, which the CLI rewords into an owner-only message.
escrow
A prepaid balance held in the registry under your account. buy --from-escrow and the MCP tool pay each call out of it, attaching nothing, which is what lets a restricted agent key pay: the escrow is the agent’s spending limit. Three subcommands, all taking the config flags; deposit and withdraw take the buyer signer flags.
escrow deposit
$ neargate escrow deposit <near> --account <buyer>
Calls deposit_escrow with the amount attached. The first deposit of an account must be more than 0.002 NEAR: the registry keeps that as the escrow entry’s storage fee and credits the rest (otherwise ERR_DEPOSIT_TOO_LOW); later deposits are credited in full. The amount must be above zero.
output
account: buyer.testnet deposited: 1 NEAR escrow: 0.998 NEAR tx: <tx hash> explorer: <NEAR_EXPLORER_URL>/txns/<tx hash> (live mode only) note: the first deposit keeps 0.002 NEAR as the escrow's storage fee (first deposit only)
escrow withdraw
$ neargate escrow withdraw <near> --account <buyer>
Calls withdraw_escrow, which sends the amount back to your account. It attaches exactly 1 yocto, so only the account’s full-access key can sign it: from an agent key NEAR rejects the call (TX_FAILED, “Deposit is not allowed with function call”). An amount above the escrow is refused with ERR_ESCROW_INSUFFICIENT before anything is sent. Prints account, withdrawn, escrow (what is left), tx and, in live mode, explorer.
escrow balance
$ neargate escrow balance [account]
Reads an account’s escrow; no key. Without the argument (or --account) it reads the buyer account. An account that never deposited holds 0 NEAR.
output
account: buyer.testnet escrow: 0.498 NEAR
agent-key
Live mode only (LIVE_ONLY otherwise: an agent key is a NEAR access key, which the offline devnet does not model). Gives an AI agent a key that can spend your escrow and nothing else.
$ neargate agent-key add --allowance <near> --account <owner> --key-file <owner key>
--allowance <near>NEAR decimalrequired- The gas the key may spend, above zero (for example
0.25). The gas is drawn from the account balance, not the escrow, so a leaked key can burn gas from the account balance up to its allowance: set it low. It is not the spending limit; the escrow is.
It takes the buyer signer flags for the account’s full-access key, which signs the AddKey. It then generates a fresh ed25519 key, writes {account_id, public_key, private_key} to ~/.near-credentials/<network>/<account>.neargate-agent.json (mode 0600; it refuses to overwrite an existing file, AGENT_KEY_EXISTS) and adds the public key to the account as a function-call key whose receiver is the registry and whose only method is pay_from_escrow. It prints the public key, the path and the agent’s next command, never the secret. If NEAR rejects the AddKey the file is removed again; if the outcome is unknown (TX_TIMEOUT) the file is kept, because the key may still be added: the error names the file and the public key, so check the transaction and delete the file before retrying if it failed.
output
account: buyer.testnet public key: ed25519:… key file: /home/<you>/.near-credentials/testnet/buyer.testnet.neargate-agent.json allowance: 0.25 NEAR (the key's gas; it can call pay_from_escrow on the registry and nothing else) add_key tx: <tx hash> explorer: <NEAR_EXPLORER_URL>/txns/<tx hash> the agent spends the escrow with: neargate buy <id> --from-escrow --account buyer.testnet --key-file <key file>
WHAT THE KEY CAN DO
demo-accounts
Mock mode only (MOCK_ONLY otherwise): creates a buyer and a seller on the offline devnet, funds each with 1000 NEAR from its faucet and prints their balances with ready-to-paste export lines. The devnet must be running (npm run dev).
$ neargate demo-accounts --mode mock
output (abbreviated)
buyer: buyer-1abba006.mock (1000 NEAR) seller: seller-1155b100.mock (1000 NEAR) # paste into your shell (used by the buyer agent and `neargate wrap`): export MOCK_BUYER_ACCOUNT=buyer-1abba006.mock export MOCK_SELLER_ACCOUNT=seller-1155b100.mock # buyer public key: ed25519:… # seller public key: ed25519:…
mcp
Serves NearGate as a Model Context Protocol stdio server, so any MCP-capable agent (Claude Desktop, a custom client, an MCP-aware framework) gets NearGate discovery and payment as native tools. stdout is the JSON-RPC channel, so the server prints nothing else there; a readiness hint goes to stderr. It takes the config flags and the buyer signer flags.
$ neargate mcp --account <buyer>
Tools
| Tool | Does | Spends NEAR |
|---|---|---|
neargate_list_servicesno input | The live catalog: id, name, description, price (with storage fee), tier, score, active flag, endpoint. | no |
neargate_get_service{ id } | One service in full: price, payment target, owner, attestor, tier and score. | no |
neargate_get_invoice{ id } | Fetches the 402 invoice without paying: price, storage fee, total to attach, payTo, network, nonce, expiry — so an agent can decide first. | no |
neargate_buy{ id, maxNear?, fromEscrow?, gasless?, method?, body? } | Pays the invoice with a registry pay call and returns the response body. maxNear caps the total. With fromEscrow it calls pay_from_escrow instead, debiting the prepaid escrow (ERR_ESCROW_INSUFFICIENT, before sending, if it holds less). gasless implies fromEscrow and signs that call as a delegate the gateway relays, paying the gas (RELAYER_UNAVAILABLE when the gateway offers no relayer); the result then says gasless and names the relayer. While the relay settles the tool waits, for at most 150 s; a GASLESS_NOT_SERVED it returns points at the relay tx and neargate_escrow_balance. | yes |
neargate_escrow_balance{ account? } | The NEAR still prepaid in an escrow (default: the buyer account), so an agent can see its remaining budget before buying. Read-only. | no |
The buyer key is resolved only when neargate_buy runs (and by neargate_escrow_balance when it is given no account), so the three catalog tools work with no key configured. Point an agent at a restricted agent key (--key-file) and it can call neargate_buy with fromEscrow: true (or gasless: true) and nothing more. A failing tool returns an error result that leads with the stable code (BUDGET_EXCEEDED, SERVICE_INACTIVE, PAID_NOT_SERVED…), so an agent can branch on it; the codes are the ones in Error codes. A raw network failure carries no code: for example a neargate_get_invoice whose gateway is unreachable or does not answer within 30 s returns the bare message.
Claude Desktop
With the CLI installed globally (npm install -g @neargate/cli), add the server to claude_desktop_config.json:
claude_desktop_config.json
{
"mcpServers": {
"neargate": {
"command": "neargate",
"args": [
"mcp",
"--account",
"buyer.testnet"
]
}
}
}From a clone, build the bundle once with npm run build -w @neargate/cli and use "command": "node" with the absolute path /path/to/repo/packages/cli/dist/bin.js as the first argument, before mcp.
To try the read tools without a client, scripts/mcp.sh drives the server over stdio: scripts/mcp.sh tools, list, service <id>, invoice <id>.
Error codes
Failures reach you as error: <CODE>: <message> from the CLI, as an error result from an MCP tool, and as an AgentGateError with a code from the packages. A rejection by the registry keeps the contract’s own ERR_* code and starts its message with it; those are listed on the contract page. The gateway’s HTTP answers (402 reasons, 403, 503) are on How it works.
Arguments, config and keys
| Code | Meaning |
|---|---|
INVALID_INPUT | A text flag is blank, has control characters or is over its byte limit (name 64, description 280); buy --body is not valid JSON; escrow balance names two different accounts (the argument and --account). |
INVALID_URL | A URL is not http(s), has a query string or fragment, or the gateway URL is over 200 bytes. map: the on-chain endpoint does not end in <gateway>/svc/<id>. |
GATEWAY_REQUIRED | Live wrap with no --gateway in a build whose hosted gateway default (DEFAULT_GATEWAY_URL) is empty; a build with the hosted gateway never raises it. Nothing is sent: pass --gateway <your gateway’s base URL>. |
INSECURE_URL | Live wrap with a plain http:// gateway that is not localhost, or map of a service whose registered gateway is one: the mapping request would travel in cleartext. |
INVALID_SERVICE_ID | The <id> argument is not a positive integer. |
INVALID_ACCOUNT_ID | An account flag is not a NEAR account id. |
INVALID_AMOUNT | A NEAR amount (--price, --max, maxNear, an escrow amount, --allowance) is not a plain non-negative decimal of at most 24 places, or is above the u128 maximum; an escrow amount or an agent key allowance of zero is refused too. |
INVALID_PRICE | --price is below the registry minimum of 0.000001 NEAR. |
CONFIG_INVALID | A flag or environment variable is invalid — for example a malformed REGISTRY_CONTRACT_ID or an unknown NEAR_NETWORK. |
SIGNER_MISSING | Live mode: no account for the command’s role (pass --account or set the role’s *_ACCOUNT_ID), or no key for it: no secret, no key file and no ~/.near-credentials file. Mock mode falls back to MOCK_*_ACCOUNT, which defaults to seller.mock / buyer.mock. |
SIGNER_KEY_INVALID | A secret key or key file is not a valid ed25519 NEAR key. The message names the source, never the key. |
SIGNER_KEY_UNREADABLE | The key file cannot be read. |
SIGNER_KEY_MISMATCH | The key file is for a different account than the one you are signing as. |
ACCOUNT_NOT_FOUND | wrap: the payment target does not exist on the network. Create it or pass --payment-target <existing account>; a missing one would strand every payment. |
LIVE_ONLY | map or agent-key in mock mode. The mock gateway maps through its admin route, which wrap does for you; agent keys are NEAR access keys, which the devnet does not model. |
MOCK_ONLY | demo-accounts outside mock mode. |
NOT_SERVICE_OWNER | map: your key’s account is not the service owner. |
MAPPING_FAILED | map: the gateway did not map the upstream (non-2xx, a redirect, a network error or a timeout); retry it. wrap raises no code for this: it warns, prints the retry and exits 0, because the registration stands. |
SERVICE_NOT_FOUND | No service with that id on this registry. |
SERVICE_INACTIVE | buy / neargate_get_invoice: the owner paused the service. Nothing is paid. |
FAUCET_UNREACHABLE | demo-accounts cannot reach the devnet faucet. Start it with npm run dev. FAUCET_FAILED means the faucet answered an error; GATEWAY_TIMEOUT that it did not answer in time. |
Escrow and agent keys
The three ERR_* codes below are the registry’s own (see the contract page); the CLI and the client raise ERR_ESCROW_INSUFFICIENT themselves, before sending, when they can see it coming.
| Code | Meaning, and what to do |
|---|---|
ERR_ESCROW_INSUFFICIENT | buy --from-escrow / neargate_buy with fromEscrow: the escrow holds less than price + 0.002 NEAR. escrow withdraw: the amount is above the escrow. The message states the balance, and ends “nothing was sent” when the CLI or client refused before sending.Top up with escrow deposit, or ask for less. |
ERR_ONE_YOCTO_REQUIRED | withdraw_escrow without exactly 1 yocto attached. The CLI always attaches it; you only meet this calling the contract by hand. |
ERR_DEPOSIT_NOT_ALLOWED | pay_from_escrow with a deposit attached. The CLI and the client attach none; you only meet this calling the contract by hand. |
AGENT_KEY_EXISTS | agent-key add: the key file for this account and network already exists, and is never overwritten.Delete it first if you mean to replace that key. |
AGENT_KEY_UNWRITABLE | agent-key add cannot create the key file (permissions, disk). Nothing was added to the account. |
Buying: invoice and payment
Raised by buy, neargate_buy and fetchPaid in @neargate/sdk. Every refusal below happens before a payment is sent, except PAID_NOT_SERVED and GASLESS_NOT_SERVED.
| Code | Meaning, and what to do |
|---|---|
BUDGET_EXCEEDED | The invoice total (price + the 0.002 NEAR storage fee) is above your cap (--max, maxNear, or the buyer agent’s budget). Nothing was paid.Raise the cap or pick a cheaper service. |
BAD_URL | The endpoint read from the registry is not an http(s) URL.The seller registered a bad endpoint; do not use the service. |
FORBIDDEN_HOST | Live mode: the endpoint host is private, loopback or link-local, or resolves to one.The seller’s gateway URL is unusable from the public network. |
BAD_INVOICE | The 402 body is not a valid NearGate invoice: not JSON, wrong x402 version, an expired invoice, or a price, fee or total that does not add up.Retry for a fresh invoice; if it persists the gateway is faulty. |
NETWORK_MISMATCH | The invoice offers no payment on this client’s network (for example a testnet client and a mock gateway).Point the client and the gateway at the same network. |
PRICE_MISMATCH | --from-escrow only: the invoice’s total is not the service’s on-chain price + 0.002 NEAR. pay_from_escrow carries no amount and debits the on-chain price, so the client checks the registry before paying and refuses an invoice that differs. Nothing was sent.Do not pay this service from the escrow; the gateway’s invoice is wrong. |
REGISTRY_MISMATCH | The invoice’s payTo is not the registry this client settles on.Check --registry / REGISTRY_CONTRACT_ID. |
SERVICE_MISMATCH | The invoice is for a different service id than the one you asked for.Do not pay; the gateway answered for another service. |
REDIRECT_REFUSED | A gateway answered with an HTTP 3xx. NearGate never follows a redirect, because it would carry the request past the URL guard.Use the final URL directly, if you trust it. |
UPSTREAM_TIMEOUT | The invoice request got no answer within 30 s. Nothing was paid.Safe to retry. |
PAID_NOT_SERVED | The registry pay went through — the deposit is spent — but the gateway did not serve the call. The error names the transaction, the nonce, the service, the amount and a reason: refused, settlement_pending, redirect or transport.Do not pay a fresh invoice for it. Re-present the same proof (an X-PAYMENT for that transaction and nonce) once the gateway is reachable or the payment has settled. |
RELAYER_UNAVAILABLE | --gasless only: the gateway’s 402 offers no relayer of pay_from_escrow (no extra.relayer; the gateway runs without RELAYER_ENABLED). Nothing was read or signed.Buy with --from-escrow, which pays the gas from your account. |
GASLESS_NOT_SERVED | --gasless only: the gateway did not serve the call. The account sent nothing; the escrow paid only if the gateway’s relay landed. buy already presented the same signed delegate again for as long as the gateway answered settlement_pending, up to 150 s. The message says whether the escrow paid (the error’s escrowPaid: no or unknown) and names the nonce, the service, the relay transaction when the gateway named it (with its explorer link in live mode) and a reason: refused (the gateway’s 402 error, and after relay_failed its code: the registry’s, e.g. ERR_ESCROW_INSUFFICIENT, DELEGATE_REJECTED or RELAYER_ERROR), settlement_pending (the relay was still settling after 150 s), redirect or transport (the gateway may have relayed it).When the escrow did not pay (no), fix the cause and buy again. When it may have (unknown), check the relay transaction on the explorer and neargate escrow balance before buying again: buying again signs a NEW payment. After invoice_used, always check the escrow balance before buying again: it can mean the gateway’s relay landed before the gateway restarted. |
Chain and RPC
Live mode, except the devnet codes in the last row.
| Code | Meaning, and whether to retry |
|---|---|
RPC_TIMEOUT | The NEAR RPC did not answer in time and nothing was sent: a read, or a call that failed before its transaction was signed.Safe to retry. |
RPC_ERROR | The RPC is unreachable, answered an HTTP error (the message says rate-limited for a 429) or failed on the node side. Nothing was sent.Safe to retry. |
RPC_BAD_RESPONSE | The RPC, or the registry behind it, answered in a shape this client cannot use.Retry once, then check NEAR_RPC_URL. |
NOT_DEPLOYED | The registry account holds no neargate-registry contract (or one with a different ABI).Not retryable: fix REGISTRY_CONTRACT_ID. |
TX_TIMEOUT | The transaction was sent, but its outcome is unknown: the RPC timed out or failed after the transaction went out. When the client knows the hash, the message names it and its explorer page, <explorer>/txns/<hash>; when the RPC stopped waiting before returning one, it says only that the transaction may still land.Do not retry blindly: the transaction may still land. Check it on the explorer first, or a retry can register or pay twice. |
TX_FAILED | NEAR rejected the transaction, or an action in it failed, outside a contract panic. The message carries NEAR’s reason and the transaction hash when there is one.Not as is: read the reason. |
CONTRACT_ERROR | The registry failed without one of its ERR_* codes (gas exhaustion, a wasm trap, a panic with no code).Not as is. |
SIGNER_KEY_NOT_FOUND | The key you sign with is not an access key of the signer account on this network.Use the right key or network. |
SIGNER_ACCOUNT_NOT_FOUND | The signer account does not exist on this network.Create or fund it first. |
ERR_INSUFFICIENT_BALANCE | The signer cannot cover the deposit plus gas, or would be left short of its own storage stake after the transaction.Fund the account. |
devnet_unreachable | Mock mode: the offline devnet is not running (devnet_timeout: it did not answer). The devnet can also answer devnet_bad_response (a reply in the wrong shape), devnet_error or its own error code, and a bad DEVNET_URL gives invalid_devnet_url.Start it with npm run dev; check DEVNET_URL. |
keep reading