GET STARTED
NearGate Docs
Stripe for AI agents on NEAR. Wrap any HTTP API behind an HTTP 402 paywall, register and score it on-chain, and let buying agents pay per call in native NEAR, with no accounts, no API keys and no subscriptions. This page gives you the mental model, then routes you by role — seller, buyer or gateway operator.
What NearGate is
NearGate is an x402-style payment gateway — x402 is the open convention for settling HTTP 402 Payment Required challenges with on-chain payments — for machine-to-machine APIs. A seller puts any HTTP endpoint behind a 402 paywall and registers it in the on-chain neargate-registry contract. A buying agent discovers the service, receives a machine-readable invoice, pays it through the registry, then retries with the transaction hash as proof — and the gateway records an on-chain attestation that feeds the service’s trust score. The whole loop is register → 402 → pay → serve → attest → score.
Nothing about it is human-shaped. There is no signup form, no credit card, no KYC and no API key to copy into a config file. The only credential an agent needs is a NEAR account and its key, plus the ability to make an HTTP request.
The mental model: HTTP 402 + NEAR
When an agent calls a paid endpoint with no proof, the gateway answers 402 with a PaymentRequiredResponse (x402 V1): x402Version: 1, an error text and an accepts[] entry carrying maxAmountRequired (the price plus the storage fee, in yoctoNEAR), payTo (the registry account), a single-use extra.nonce and extra.expiresAtMs. The agent calls the registry’s pay(service_id, nonce) with maxAmountRequired attached, then retries the request with an X-PAYMENT header (base64 JSON naming the transaction, the nonce and the payer). The gateway checks the registry’s payment record for that nonce, burns the nonce so it can never be reused, proxies to the seller’s upstream API and returns the response, then records an attestation of the outcome on-chain.
PAYMENTS GO THROUGH THE REGISTRY
The buyer never pays the seller directly. pay forwards exactly the service price to the seller’s payment_target, keeps a flat 0.002 NEAR storage fee for the payment record, and refunds anything attached above price + 0.002 NEAR. Because the registry itself holds the payment record, an attestation can only exist for a real payment — see the security model. The gateway never custodies funds.
LIVE ON NEAR TESTNET
The registry neargate-app-registry.testnet, the gateway https://neargate-gateway-production.up.railway.app and this dashboard (https://neargate-dashboard-production.up.railway.app) run in live mode, with the gasless relay on, and service #1 is open for paid calls. The CLI targets them by default. Start with Try the live deployment.
When to use NearGate
Reach for NearGate when the consumer of an API is software that holds a NEAR account rather than a person with a card. Typical fits:
| You want to… | NearGate gives you |
|---|---|
| Sell data or compute to autonomous agents | A pay-per-call paywall in front of your existing API — no billing system to build. |
| Let an agent buy capabilities mid-task | On-chain discovery plus a 402 invoice the agent can settle in seconds, with proof instead of credentials. |
| Charge per request without accounts | Native NEAR settlement that lands directly in your payment-target account; the gateway holds nothing. |
| Pick providers by reputation | A payment-backed attestation trail and a trust tier (new → reliable → trusted) computed from real paid calls. |
It is a poor fit for human-facing checkout flows, subscriptions, or anything that needs chargebacks and refunds — those are the human-shaped patterns NearGate deliberately replaces.
The roles: seller, buyer, operator
Three actors meet at the gateway. Each has its own commands; this is the short version. For the seller and the buyer step by step on the live deployment, see Sell & buy.
Seller — wraps an API
A seller owns an upstream HTTP API and wants to charge per call. Running neargate wrap once calls register_service on the registry (name, description, gateway URL, price, payment target, attestor; 0.12 NEAR deposit) and maps the private upstream URL on the gateway (live mode: with a request signed by the owner’s key). After that, every call to the public /svc/:id endpoint is metered and paid. See CLI → wrap.
Buyer — an agent that consumes a service
A buyer discovers services in the on-chain catalog, calls /svc/:id, handles the 402, pays through the registry and retries with proof. You can do that with one command (neargate buy), any MCP-capable agent through the MCP server, the bundled buyer agent, or the @neargate/sdk package’s fetchPaid helper. The protocol page spells out every step for a hand-rolled client.
Operator — runs the gateway
An operator runs the gateway (the 402 reverse proxy — the @agentgate/middleware package) against a deployed registry. In live mode the gateway needs a NEAR account of its own (GATEWAY_ACCOUNT_ID): it signs the attestations and, with RELAYER_ENABLED, relays gasless payments and pays their gas. The registry accepts an attestation only from the service’s attestor or owner, so each service it serves must name that account as attestor (neargate wrap --attestor; the seed script does it; the hosted gateway’s account is neargate-app-gateway.testnet). The operator sets REGISTRY_CONTRACT_ID, the gateway account and key, and a non-default admin token. The quickstart lists the testnet scripts that create the accounts, deploy the contract and seed a first service.
Mock vs live modes
A single environment variable — AGENTGATE_MODE — selects the chain backend behind the ChainClient seam. A local stack (gateway, buyer agent, dashboard) defaults to mock, while the neargate CLI defaults to live, and the hosted gateway and dashboard run live. Everything above the seam is the same, so you build and test offline and flip one variable to go on-chain.
| Concern | mock (default for a local stack) | live (NEAR testnet, the hosted deployment) |
|---|---|---|
| Chain backend | In-memory devnet (@agentgate/devnet) at :4030, network near-mock | The NEAR RPC (NEAR_RPC_URL), network near-testnet |
| Registry | The devnet applies the registry contract’s rules in memory | The deployed neargate-registry contract (REGISTRY_CONTRACT_ID) |
| Payment check | The devnet’s payment record for the nonce | The registry’s get_payment view, plus the RPC’s record of the pay or pay_from_escrow transaction |
| Signers | Mock account ids; no key files (the devnet signs with one public key per account) | ed25519 keys: a near-cli credentials file, a key file, or a secret key in the environment |
| Explorer links | None (no explorer indexes the devnet) | nearblocks (NEAR_EXPLORER_URL) |
| Guardrails | Default admin token allowed; SSRF guard off so localhost upstreams work | Default admin token refused; SSRF guard on |
LIVE MODE PREREQUISITES
REGISTRY_CONTRACT_ID (the CLI's --registry); with it unset it uses the default registry that the badge at the top of each docs page shows. The gateway also needs GATEWAY_ACCOUNT_ID with a key and a non-default AGENTGATE_ADMIN_TOKEN; both are enforced by config. Reading the catalog (neargate list, status) needs no key.Where to go next
Quickstart
Try the live testnet deployment, run the offline demo (register → 402 → pay → serve → attest → score), bring a local stack up with seeded data, then the testnet scripts.
Sell & buy
Step by step on the live deployment: an account and where its key goes, wrapping an API behind the hosted gateway, and buying from your account, an agent key, Claude Desktop or @neargate/sdk.
CLI & MCP
neargate wrap, map, list, buy, status, pause, resume, demo-accounts, escrow, agent-key and the MCP server: every flag, the five MCP tools, and the error codes you can meet.
How it works
The x402 flow on NEAR end to end: the 402 body, the registry pay call, the X-PAYMENT proof, verification, the single-use nonce, attestations and the gateway’s receipts endpoint.
Security model
What the chain enforces and what the gateway reports: payment-backed scores, the self-map signature, the SSRF guard, redirects and budget caps.
Registry contract
The neargate-registry ABI: change methods, views, constants, limits, events and every ERR_* code.
keep reading