I Built an API That AI Agents Pay in USDC — Full x402 Walkthrough (27 Endpoints, Real Transactions)

A developer built an Express API that allows AI agents to pay per call in USDC via the x402 protocol, with 27 paid endpoints live on Base mainnet. The implementation uses the dormant HTTP 402 status code for a payment handshake, eliminating the need for signups or API keys, and has processed real settled transactions.

I built an Express API that AI agents or humans, or anything with fetch can pay per call, in USDC, with no signup and no API key. It's live on Base mainnet with 27 paid endpoints, and I've run real settled transactions against it. This is the technical walkthrough — the code, the protocol, and the things that actually broke — not an "agentic economy" pitch. x402 resurrects the dormant HTTP 402 Payment Required status code as a real payment handshake. A client calls a paid route → the server replies 402 with payment requirements amount, asset, network instead of the resource → the client signs a USDC transfer on Base and replays the request with a PAYMENT header → a facilitator a third party, or Coinbase's CDP service in production verifies and settles the transfer on-chain → the server serves the response. No account creation, no API key issuance, no OAuth dance — the wallet address is the identity, and payment is the auth. The server is plain Express. Each endpoint is a file in endpoints/ exporting { path, method, price, handler } ; server.js loads them all, builds the x402 route table, and mounts one middleware: js import { paymentMiddleware, x402ResourceServer } from "@x402/express"; import { ExactEvmScheme } from "@x402/evm/exact/server"; import { HTTPFacilitatorClient } from "@x402/core/server"; import { createFacilitatorConfig } from "@coinbase/x402"; const facilitatorConfig = config.isMainnet ? createFacilitatorConfig config.cdpApiKeyId, config.cdpApiKeySecret : { url: config.testnetFacilitatorUrl }; // https://x402.org/facilitator, no key const facilitatorClient = new HTTPFacilitatorClient facilitatorConfig ; const resourceServer = new x402ResourceServer facilitatorClient .register config.caip2Network, // "eip155:8453" on mainnet new ExactEvmScheme ; const paidRoutes = {}; for const ep of endpoints { if ep.price == null continue; paidRoutes ${ep.method} ${ep.path} = { accepts: { scheme: "exact", price: ep.price, network: config.caip2Network, payTo: config.payToAddress }, resource: ${config.baseUrl}${ep.path} , description: ep.description, mimeType: "application/json", }; } app.use paymentMiddleware paidRoutes, resourceServer ; That's the entire payment layer. @x402/express handles the 402 response and calls the facilitator's verify / settle — the endpoint handler never sees a wallet address or a signature, only a normal req / res . Here's a full endpoint, GET /api/gas/base versions in use: @x402/express , @x402/core , @x402/evm , @x402/extensions , @x402/fetch all 2.24.0 , @coinbase/x402 2.1.0 — the scoped @x402/ line is current v2; the older unscoped x402-express / x402-fetch are deprecated, don't mix them : js import { declareDiscoveryExtension } from "@x402/extensions/bazaar"; import { getGasPrice } from "../lib/chains.js"; import { cached } from "../lib/cache.js"; export const path = "/api/gas/base"; export const method = "GET"; export const price = "$0.005"; export const description = "Current gas price on Base Ethereum L2 , read live via a public RPC endpoint — no API key, no aggregator."; export const discovery = declareDiscoveryExtension { input: {}, inputSchema: { properties: {}, required: }, output: { example: { chain: "base", gas price wei: "6000000", gas price gwei: 0.006 } }, } ; export async function handler req, res { const gasPriceWei = await cached "gas-base", 60 000, = getGasPrice "base" ; res.json { chain: "base", gas price wei: gasPriceWei.toString , gas price gwei: Number gasPriceWei / 1e9, fetched at: new Date .toISOString , } ; } No blockchain code in the handler — viem reads gas price from a public RPC. price / discovery are just metadata consumed elsewhere the middleware, and the discovery documents below . @x402/fetch wraps fetch so it transparently handles the 402 → sign → replay cycle. A minimal buyer: js import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from "@x402/fetch"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; const account = privateKeyToAccount BUYER PRIVATE KEY ; const fetchWithPayment = wrapFetchWithPaymentFromConfig fetch, { schemes: { network: "eip155: ", client: new ExactEvmScheme account } , } ; const response = await fetchWithPayment "https://x402-seller-0ay3.onrender.com/api/gas/base" ; const data = await response.json ; const receipt = decodePaymentResponseHeader response.headers.get "PAYMENT-RESPONSE" ; console.log receipt.transaction ; // the on-chain settlement hash Under the hood: first call gets 402 + payment requirements, ExactEvmScheme signs a USDC transfer authorization for the exact price, the wrapper replays the request with a PAYMENT header, the facilitator settles it, and the response carries a PAYMENT-RESPONSE header with the receipt. This isn't a simulation — here's an actual settled transaction from a real run against the production server: GET /api/gas/base — $0.005 USDC tx: 0x4c3c38d0a7732244caf895d32a46e5e1fa780abdf4216b3c3fa28bb496062646 https://basescan.org/tx/0x4c3c38d0a7732244caf895d32a46e5e1fa780abdf4216b3c3fa28bb496062646 Every settled payment is logged server-side endpoint, payer address, amount, tx hash — nothing that isn't already public on-chain , which is where that hash comes from. Payment infra is useless if nothing finds your endpoints. Five discovery surfaces, in the order I wired them up: GET /.well-known/x402.json payTo , and input/output schema. There's no single official schema for this exact path; I followed the envelope from the IETF draft x402Version , kind , resources and enriched each resource with the same Bazaar metadata used elsewhere. GET /openapi.json npm run bazaar that pages through facilitatorClient.extensions.bazaar.listResources and filters for our payTo address to confirm we're actually indexed. POST /api/x402/registry/register-origin {origin} call makes it crawl our /openapi.json and register everything in one shot. POST core.x402arena.gg/register against our /api/gas/base endpoint. No facilitator involvement, no on-chain proof required at registration time — it shows up verified:true in their public agent list GET core.x402arena.gg/agents after a health check against the live endpoint. User-Agent → silent 403 from Cloudflare. rdap.org and a couple of other upstream sources return a flat 403 to anonymous-looking requests. Fix was a one-line default: every outbound fetch in this project now sends a descriptive UA x402-seller/1.0 +https://... . Confirmed by testing: 403 with no UA, 200 with one, same request otherwise. GITHUB TOKEN no scopes needed — it's all public repo data raises that to 5000/hour. .jsonl files on disk for simplicity — which is fine until a redeploy wipes the disk and takes the logs with it. Not fixed yet would mean a real datastore ; flagged here as a known limitation, not something I'm going to gloss over. POST /api/web/read fetches an arbitrary URL and returns readable Markdown — an obvious target for hitting 169.254.169.254 or localhost:6379 . It's guarded on both the initial hostname ipaddr.js , refuse anything that isn't unicast public , reject literal localhost /loopback/link-local hostnames outright, and cap the download at 2 MB inside a 10 s timeout regardless. x402.gitbook.io still reference some v1, unscoped package names in places; what's actually current and maintained is the scoped @x402/ line 2.24.0 as of this writing . When something in the docs didn't match node modules , I trusted the installed package and its own type definitions over the prose.The x402 ecosystem is small right now. Traffic on this server is basically me testing it, plus whatever probes discovery crawlers send. This post is a "here's how the plumbing works and here's the code," not a revenue story — I have no evidence yet that agents are out there autonomously discovering and paying for API calls at any real scale. If that changes, that's a different post. Base URL: https://x402-seller-0ay3.onrender.com . All 27 endpoints below are real and callable; each costs a fraction of a cent, so poking at a few won't cost you anything meaningful. GET /health , GET /stats , and the two discovery documents are free. | Method | Path | Price | |---|---|---| | GET | /api/price/eth-usd | $0.005 | | GET | /api/price/btc-usd | $0.005 | | GET | /api/price/sol-usd | $0.005 | | GET | /api/price/usdc-supply | $0.005 | | GET | /api/gas/base | $0.005 | | GET | /api/gas/ethereum | $0.005 | | GET | /api/chain/gas | $0.005 | | GET | /api/chain/block | $0.005 | | GET | /api/defi/price | $0.005 | | GET | /api/defi/tvl | $0.005 | | GET | /api/defi/tvl-chain | $0.005 | | GET | /api/defi/protocols | $0.005 | | GET | /api/defi/yields | $0.005 | | GET | /api/defi/stablecoins | $0.005 | | GET | /api/fx/rates | $0.005 | | GET | /api/github/repo | $0.005 | | GET | /api/npm/package | $0.005 | | GET | /api/hn/top | $0.005 | | GET | /api/wiki/summary | $0.005 | | GET | /api/dns/lookup | $0.005 | | GET | /api/rdap/domain | $0.005 | | POST | /api/web/read | $0.005 | | POST | /api/web/extract | $0.02 | | POST | /api/ai/summarize | $0.01 | | POST | /api/ai/classify | $0.01 | | POST | /api/ai/translate | $0.01 | | POST | /api/ai/extract | $0.02 | Two full examples with @x402/fetch swap in your own funded Base wallet : GET, no body ENDPOINT PATH="/api/gas/base" \ TARGET URL="https://x402-seller-0ay3.onrender.com" \ node scripts/buyer-test.js POST, with a JSON body ENDPOINT PATH="/api/web/read" METHOD=POST \ BODY='{"url":"https://en.wikipedia.org/wiki/HTTP 402"}' \ TARGET URL="https://x402-seller-0ay3.onrender.com" \ node scripts/buyer-test.js Both print the response JSON and the settlement receipt, hash included. GET /.well-known/x402.json and GET /openapi.json list every route with full input/output schemas if you want to build a client instead of copy-pasting curl.