Skip to content
NearGate

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.

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

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.

FlagSeller envBuyer env
--account <id>SELLER_ACCOUNT_IDBUYER_ACCOUNT_ID
--key-file <path>SELLER_KEY_PATHBUYER_KEY_PATH
no flag (a secret)SELLER_PRIVATE_KEYBUYER_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 orderNotes
1 · SELLER_PRIVATE_KEY / BUYER_PRIVATE_KEYAn 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_PATHA near-cli credentials JSON (account_id, public_key, private_key) whose account_id must match the account.
3 · ~/.near-credentials/<network>/<account>.jsonWhere 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 gasless waiting: line, escrow deposit / withdraw, agent-key add, and the TX_TIMEOUT and GASLESS_NOT_SERVED messages.
UPSTREAM_TIMEOUT_MSnumber (ms)optionaldefault 30000
How long wrap and map wait for the gateway’s mapping answer, and demo-accounts for the devnet faucet.
MIDDLEWARE_PORTnumberoptionaldefault 4021
Mock mode only: the default wrap --gateway is http://localhost:<MIDDLEWARE_PORT>. In live mode it is the shared https://neargate-gateway-production.up.railway.app.
DASHBOARD_PORTnumberoptionaldefault 3000
Mock mode only: the dashboard link wrap prints is http://localhost:<DASHBOARD_PORT>/services/<id>. In live mode it points at the shared https://neargate-dashboard-production.up.railway.app.
DEVNET_URLstring (url)optionaldefault http://localhost:4030
The offline devnet that mock mode reads and demo-accounts funds from (derived from DEVNET_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.000001 NEAR (the registry minimum, else INVALID_PRICE). Buyers attach this plus the flat 0.002 NEAR storage 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 needs https:// unless the host is localhost (INSECURE_URL). Without the flag, live mode uses the hosted gateway https://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 as neargate-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

The registration is not rolled back when the gateway mapping fails: the service exists on-chain and its endpoint answers 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_escrow instead of attaching a deposit to pay: nothing is attached and the escrow is debited the same total, price + 0.002 NEAR. If the escrow holds less, buy fails with ERR_ESCROW_INSUFFICIENT before sending anything. --max still 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: buy signs the pay_from_escrow as 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, else RELAYER_UNAVAILABLE before anything is signed; the escrow checks of --from-escrow run next. An agent key can sign it. While the gateway answers settlement_pending (its relay is settling), buy presents 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 one waiting: 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

It can spend the escrow and nothing else: it cannot withdraw, deposit, register, pause or move any other balance, and NEAR rejects any other call from it. A leaked agent key can spend all of the escrow on any active service, and no more NEAR than that. It can also burn gas from the account balance up to its allowance, because its gas is paid by the account, not the escrow: keep the allowance low. Keep in the escrow only what the agent may spend; see the security model.

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

ToolDoesSpends NEAR
neargate_list_servicesno inputThe 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

CodeMeaning
INVALID_INPUTA 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_URLA 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_REQUIREDLive 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_URLLive 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_IDThe <id> argument is not a positive integer.
INVALID_ACCOUNT_IDAn account flag is not a NEAR account id.
INVALID_AMOUNTA 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_INVALIDA flag or environment variable is invalid — for example a malformed REGISTRY_CONTRACT_ID or an unknown NEAR_NETWORK.
SIGNER_MISSINGLive 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_INVALIDA secret key or key file is not a valid ed25519 NEAR key. The message names the source, never the key.
SIGNER_KEY_UNREADABLEThe key file cannot be read.
SIGNER_KEY_MISMATCHThe key file is for a different account than the one you are signing as.
ACCOUNT_NOT_FOUNDwrap: 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_ONLYmap 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_ONLYdemo-accounts outside mock mode.
NOT_SERVICE_OWNERmap: your key’s account is not the service owner.
MAPPING_FAILEDmap: 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_FOUNDNo service with that id on this registry.
SERVICE_INACTIVEbuy / neargate_get_invoice: the owner paused the service. Nothing is paid.
FAUCET_UNREACHABLEdemo-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.

CodeMeaning, and what to do
ERR_ESCROW_INSUFFICIENTbuy --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_REQUIREDwithdraw_escrow without exactly 1 yocto attached. The CLI always attaches it; you only meet this calling the contract by hand.
ERR_DEPOSIT_NOT_ALLOWEDpay_from_escrow with a deposit attached. The CLI and the client attach none; you only meet this calling the contract by hand.
AGENT_KEY_EXISTSagent-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_UNWRITABLEagent-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.

CodeMeaning, and what to do
BUDGET_EXCEEDEDThe 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_URLThe endpoint read from the registry is not an http(s) URL.The seller registered a bad endpoint; do not use the service.
FORBIDDEN_HOSTLive 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_INVOICEThe 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_MISMATCHThe 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_MISMATCHThe invoice’s payTo is not the registry this client settles on.Check --registry / REGISTRY_CONTRACT_ID.
SERVICE_MISMATCHThe invoice is for a different service id than the one you asked for.Do not pay; the gateway answered for another service.
REDIRECT_REFUSEDA 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_TIMEOUTThe invoice request got no answer within 30 s. Nothing was paid.Safe to retry.
PAID_NOT_SERVEDThe 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.

CodeMeaning, and whether to retry
RPC_TIMEOUTThe 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_ERRORThe 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_RESPONSEThe RPC, or the registry behind it, answered in a shape this client cannot use.Retry once, then check NEAR_RPC_URL.
NOT_DEPLOYEDThe registry account holds no neargate-registry contract (or one with a different ABI).Not retryable: fix REGISTRY_CONTRACT_ID.
TX_TIMEOUTThe 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_FAILEDNEAR 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_ERRORThe registry failed without one of its ERR_* codes (gas exhaustion, a wasm trap, a panic with no code).Not as is.
SIGNER_KEY_NOT_FOUNDThe 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_FOUNDThe signer account does not exist on this network.Create or fund it first.
ERR_INSUFFICIENT_BALANCEThe signer cannot cover the deposit plus gas, or would be left short of its own storage stake after the transaction.Fund the account.
devnet_unreachableMock 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.