Skip to content
NearGate

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.

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

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.

RequirementVersionNotes
Node.js≥ 22.22.2Declared 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_KEYoptionalNot 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-neartestnet scripts onlynpm 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.

  1. 01

    Install the workspace

    From the repository root, one install resolves every package and the dashboard.
    npm install
  2. 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 like neargate buy does, 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

The payment and the attestation are the loop’s two transactions: the buyer’s registry 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.

  1. 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). Plain npm run dev does 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=1 always serves the sample).
    npm run dev:seed
  2. 02

    Terminal 2 — start the dashboard

    Launches the Next.js dashboard against the running stack.
    npm run dev:dashboard
  3. 03

    Open the URL it prints

    Usually http://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 read DASHBOARD_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

Buy again with a different buyer and refresh the dashboard — each served call adds an attestation and bumps the score (2/2, 3/3, …). A payment made by the service’s own owner or payment target is served but never attested, so it cannot raise the score.

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.

ScriptWhat it does
npm run near:bootstrapCreates 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:deployBuilds 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:liveStarts 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:seedOne 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:liveA 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