GET STARTED
Quickstart
Try the live deployment on NEAR testnet, or go from a clone to a working payment loop in about a minute. Everything from the offline demo up to the testnet section runs in mock mode against an in-process devnet — no keys and no NEAR account needed.
Try the live deployment
NearGate runs on NEAR testnet: the registry neargate-app-registry.testnet, the gateway at https://neargate-gateway-production.up.railway.app and this dashboard at https://neargate-dashboard-production.up.railway.app, with gasless relaying on. Service #1, USD exchange rates at 0.01 NEAR, is live: see it in the catalog or on /services/1. Its unpaid call answers the x402 invoice, with no install:
$ curl -i https://neargate-gateway-production.up.railway.app/svc/1
The CLI is on npm and targets this deployment by default; list and status need no key. Install it once, then run it from any folder:
$ npm install -g @neargate/cli
$ neargate list
$ neargate status 1
Without installing, npx -y @neargate/cli status 1 runs the same command. In a clone of the repository, run it from the repository root as npm run neargate -- status 1: that script exists only there, so in any other folder npm answers Missing script: "neargate".
To buy a call you need a funded testnet account whose key is in ~/.near-credentials/testnet/; the near CLI’s faucet sponsor creates one:
$ near account create-account sponsor-by-faucet-service <you>.testnet autogenerate-new-keypair --signature-scheme ed25519 save-to-legacy-keychain network-config testnet create
$ neargate buy 1 --max 0.02 --account <you>.testnet
It pays 0.01 NEAR + 0.002 NEAR storage to the registry, prints the rates on stdout and a receipt with the explorer link on stderr; the gateway then attests the call and the score on /services/1 grows. To put your own API behind this gateway, wrap it with --attestor neargate-app-gateway.testnet so the gateway’s attestations count. Both roles step by step, an existing wallet and an agent key included: Sell & buy.
Prerequisites
The offline path needs a recent Node.js and nothing else: the demo boots its own in-memory devnet, sample oracle and gateway inside one process.
| Requirement | Version | Notes |
|---|---|---|
Node.js | ≥ 22.22.2 | Declared in the root package.json engines field. The repository is an npm workspace, so one npm install at the root covers every package and the dashboard. |
ANTHROPIC_API_KEY | optional | Not needed for any step before the testnet section. Set it only if you want the buyer agent to use Claude instead of the deterministic MockLlm. |
| near CLI, cargo-near | testnet scripts only | npm run near:bootstrap uses the near CLI to create accounts; npm run near:deploy also builds the contract with cargo near. See Testnet scripts. |
Two modes, one code path
AGENTGATE_MODE selects the chain backend: mock (the in-process devnet, no NEAR at all; the local stack and the demo use it) or live (NEAR testnet; the hosted gateway and dashboard use it). The neargate CLI defaults to live, so the manual CLI commands below pass --mode mock. Everything above the chain seam is identical. See Mock vs live modes.60-second offline demo
The fastest proof the whole system works end to end. Install once, then run the one-shot demo. It exits 0 after printing the loop’s two transaction hashes — the payment and the attestation — recorded on the in-process mock chain.
- 01
Install the workspace
From the repository root, one install resolves every package and the dashboard.npm install - 02
Run the loop
Boots devnet + oracle (static fixture) + gateway in-process, creates faucet-funded buyer and seller accounts, wraps the oracle as service #1 at 0.5 NEAR, buys one call exactly likeneargate buydoes, lets the gateway record the attestation and prints six lines.npm run demo
npm run demo
registered service #1 402 invoice: 0.5 NEAR + 0.002 NEAR storage paid: tx <payment tx hash> served: 200 attested: tx <attestation tx hash> score: 1/1 (new)
The proof is in two hashes
pay call and the gateway’s record_attestation call. 1/1 is the score that results (success/total); the tier stays new until a service has at least five attested calls.The demo is ephemeral
npm run demo boots its own in-memory chain, runs the loop and exits — its data is gone before you could open a browser, so it will not appear in the dashboard. To view a populated, running stack use npm run dev:seed below.See it live in the dashboard
Where demo is a one-shot, dev:seed brings up the same stack and keeps it running until Ctrl+C, pre-populated with one wrapped service and one real paid call, so the dashboard shows data the moment you open it. Use two terminals.
- 01
Terminal 1 — boot and seed the stack
Boots devnet + oracle + gateway, then wraps the oracle at 0.5 NEAR and runs one paid call (score 1/1). Plainnpm run devdoes the same without the seeding step. Unlike the demo, this oracle fetches live FX and gold rates when it can reach its public sources and falls back to its fixed sample when offline (ORACLE_STATIC=1always serves the sample).npm run dev:seed - 02
Terminal 2 — start the dashboard
Launches the Next.js dashboard against the running stack.npm run dev:dashboard - 03
Open the URL it prints
Usuallyhttp://localhost:3000. If that port is taken Next.js moves to the next free one and prints it — open the URL terminal 2 shows (Next.js does not readDASHBOARD_PORT).
Terminal 1 ends with a summary like this:
npm run dev:seed (abbreviated)
NearGate dev stack is up (mock mode) — SEEDED and ready to view. service #1 http://localhost:4021/svc/1 paid call 0.502 NEAR spent (price + storage) · tx <payment tx hash>… attestation <attestation tx hash>… score 1/1 (success/total) ▶ Open the dashboard: npm run dev:dashboard → http://localhost:3000
The dashboard polls the running stack: the catalog (id, name, price in NEAR, trust tier, score, active flag), the activity feed (registrations, payments, attestations) and per-service pages such as /services/1. On the mock chain transaction hashes are plain text; against NEAR testnet they link to nearblocks.
Your first manual wrap and buy
Stop the seeded stack (Ctrl+C) first — both stacks bind the same ports — then start an empty one, export the demo accounts it prints, wrap an API as a seller, and buy a call as a buyer.
Start an empty stack and export accounts
$ npm run dev
This boots devnet, oracle and gateway and stays up, then prints two ready-to-paste export lines for a faucet-funded buyer and seller (1000 NEAR each). Paste them into the shell you run the next commands from:
export MOCK_BUYER_ACCOUNT=buyer-<8 hex>.mock export MOCK_SELLER_ACCOUNT=seller-<8 hex>.mock
You can mint a fresh pair any time with npm run neargate -- demo-accounts --mode mock.
Wrap an API (seller side)
$ npm run neargate -- wrap http://localhost:4010/feed --price 0.5 --name "RWA FX & Gold Oracle" --mode mock
This registers the service on-chain and maps the upstream on the gateway (in mock mode with the admin token). It prints the service id, the public /svc/<id> endpoint, a dashboard link and the register tx hash. Every flag is in CLI → wrap.
Buy a call (buyer side)
$ npm run neargate -- buy 1 --max 1 --mode mock
Pays the service’s 402 invoice with a registry pay call — price plus the 0.002 NEAR storage fee, capped at --max 1 NEAR in total — and prints the response body on stdout and a receipt on stderr. Or let the buyer agent choose a service itself:
$ npm run agent -- --task "Get today's USD/IDR rate and gold price, summarize for a treasury report" --budget 1
With no ANTHROPIC_API_KEY the agent uses the deterministic MockLlm; with one it asks Claude to choose, but the budget check and the payment are the same code either way.
Watch the score climb
Testnet scripts
These root scripts take the same loop to NEAR testnet: the operator path, the one that set up the hosted deployment. Run them from a clone (they are not part of the npm packages). The TypeScript scripts (dev:live, near:seed, smoke:live) read the root .env. Copy .env.example, then change what it ships for mock mode:
.env (live)
AGENTGATE_MODE=live # empty = the deployed default registry; set it to the one near:deploy printed REGISTRY_CONTRACT_ID=<prefix>-registry.testnet GATEWAY_ACCOUNT_ID=<prefix>-gateway.testnet SELLER_ACCOUNT_ID=<prefix>-seller.testnet BUYER_ACCOUNT_ID=<prefix>-buyer.testnet # a long random token: live mode refuses dev-admin-token AGENTGATE_ADMIN_TOKEN=<random> # near:seed: the public https URL of the gateway (stored on-chain for good) GATEWAY_PUBLIC_URL=https://<gateway host>
The two shell scripts (near:bootstrap, near:deploy) do not read .env: set NEARGATE_PREFIX, FORCE_REDEPLOY and DRY_RUN in the shell. The prefix defaults to neargate-<MMDD>, today’s date, so set it if you run them on different days.
| Script | What it does |
|---|---|
npm run near:bootstrap | Creates the four accounts <prefix>-registry.testnet, -seller, -gateway and -buyer through the near CLI faucet sponsor, each with a fresh key saved to ~/.near-credentials/testnet/. Idempotent: an existing account is skipped. NEARGATE_PREFIX sets the prefix. |
npm run near:deploy | Builds neargate-registry with cargo near, deploys it onto the registry account with new (no arguments, no admin) and reads services_count back. The account must hold at least 3 NEAR first (MIN_REGISTRY_BALANCE_NEAR). It refuses an account that already holds a contract unless FORCE_REDEPLOY=1, which upgrades the code only: it skips new and keeps the existing state. |
npm run dev:live | Starts the gateway in live mode against the deployed registry; it prints the registry, the attestor account and the next steps. It needs the live .env above and the gateway account’s key (GATEWAY_PRIVATE_KEY, GATEWAY_KEY_PATH or ~/.near-credentials). |
npm run near:seed | One real register → pay → attest triple: the seller wraps a public upstream at 0.01 NEAR, the buyer buys one call, then the script polls the gateway’s receipt until the attestation is recorded. It needs a running gateway reachable at GATEWAY_PUBLIC_URL, because the registry stores that URL for good, and registers GATEWAY_ACCOUNT_ID as the service’s attestor, so that must be the account the gateway at that URL signs with. Each run registers a new service. |
npm run smoke:live | A read-only check of the live deployment: lists the services, shows one (SMOKE_SERVICE_ID, default 1), and requests an unpaid invoice from its gateway, which must answer a valid 402. Nothing is paid or signed. It needs only AGENTGATE_MODE=live. |
DRY_RUN=1
near:bootstrap and near:deploy accept DRY_RUN=1: they print every command instead of running it, send nothing and never contact the network. Use it to see exactly what a run would do.see what a bootstrap would do
DRY_RUN=1 npm run near:bootstrap
keep reading