agentgate / tree / service/README.md · raw (this view has old GitHub links rewritten for the mirror; raw is byte-exact)

AgentGate paid API (x402)

Live: https://agentgate.agentgate.workers.dev (paid route https://agentgate.agentgate.workers.dev/v1/check-agent, plus free /health and /lax-offer.json). Bazaar: listed on PayAI (listing status).

check_agent as a pay-per-call HTTP API: $0.005 USDC per call on Base mainnet, paid over x402 v2, paid to 0x3c1A1E01e790Cd326495631B3b38Bd7068F08d6F.

Official packages: @x402/hono, @x402/core, @x402/evm (exact scheme, EIP-3009, gasless for the buyer) and @x402/extensions (Bazaar discovery).
Facilitator: PayAI. It supports Base mainnet with no API key and gives each receiving wallet 1,000 free credits.
The CDP facilitator also works, but it needs CDP API keys, i.e. a Coinbase Developer Platform account.
x402.org/facilitator is testnet-only.
Registry lookups: made with the same real Concordium provider as the library (../src/registry.js).
Runtimes: runs on Cloudflare Workers (src/worker.js) or Node (src/node.js).

Route	Price	What
`GET /v1/check-agent?id=<badge or account>&network=mainnet\\|testnet\\|devnet`	0.005 USDC	Concordium Agent Registry verdict (`verified`, `found`, `active`, `cardHashMatches`, owner, issues)
`GET /v1/check-agent/preview?id=<badge or account>&network=…`	free (20/min per IP)	The verdict only: `verified`, `found`, `active`, `cardHashMatches`, issues. Try it without a wallet.
`POST /mcp`	free (20/min per IP)	Remote MCP server (Streamable HTTP, stateless JSON) with the `check_agent` tool (free-tier verdict)
`GET /v1/stats`	free	Public usage counters (402 challenges, paid calls, free calls) for the last 30 days
`GET /`	free	Service info
`GET /health`	free	Liveness
`GET /lax-offer.json`	free	LAX offer for this endpoint (Five Laws in `constitutional_constraints`)

How charges work:

An unpaid call gets a 402 with PAYMENT-REQUIRED, which contains the x402 v2 terms and a Bazaar extensions.bazaar declaration.
A paid call is verified, served, then settled. The response carries PAYMENT-RESPONSE.
Invalid input (400) and registry outages (502) are never settled, so the buyer isn't charged.

Run

npm install
npm test                       # offline: fake facilitator + the official @x402/fetch client with a throwaway key
PORT=8787 npm start            # Node
npx wrangler dev               # Workers runtime, locally

Pay for a call from any x402 v2 client, for example:

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';
import { privateKeyToAccount } from 'viem/accounts';
const pay = wrapFetchWithPaymentFromConfig(fetch, { schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(privateKeyToAccount(process.env.KEY)) }] });
const r = await pay('https://<host>/v1/check-agent?id=Mf22soLh1NuZYFgBK8iSs');

Deploy (Cloudflare Workers, free plan)

Deployed with the deploy-worker workflow on every push to service/. The repo secrets are set.

Create a Cloudflare account and an API token with the "Edit Cloudflare Workers" template.
Add the repo secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, then run the deploy-worker workflow. Alternatively, deploy locally with CLOUDFLARE_API_TOKEN=... npx wrangler deploy.
Set PUBLIC_URL in wrangler.toml to the deployed origin, so the 402's resource.url is stable (no query string).

Bazaar listing (PayAI)

PayAI catalogs a resource from a payment payload that echoes the bazaar declaration. It catalogs on /verify as well as /settle, and for a GET resource that answers 402 unpaid, a verify-only payment is enough. The verify does have to pass, though, so the paying wallet must hold at least 0.005 USDC on Base.

PAYER_PRIVATE_KEY=... node scripts/bazaar-index.js https://<host>/v1/check-agent           # verify-only, moves no funds
PAYER_PRIVATE_KEY=... node scripts/bazaar-index.js https://<host>/v1/check-agent --settle  # one real 0.005 USDC call

Then check https://facilitator.payai.network/discovery/listing-status?resource=https://<host>/v1/check-agent.

Notes

On Workers, @x402/hono logs a one-time "Error compiling schema" at startup. That's its optional Bazaar route self-check, which uses Ajv code generation and is blocked by the Workers runtime. It's harmless: the 402 and its declaration are unaffected. The same declaration is validated with the official validator in npm test (Node).

agentgate-source: code mirror on Cloudflare Pages. All repos