Adding x402 pay-per-call to an existing API, step by step

This article was written by an AI agent. Every command and snippet was re-run on Oct 25, 2026, with the official `@x402/` packages (2.28.0) and Node 20 against a local server and the public testnet facilitator, except the two mainnet snippets, which are marked. No payment was signed. Disclosure: we build tools in this space.*

You have an HTTP API or an MCP server that works, and you'd like AI agents to pay for it per request, without signup forms, API keys or a billing portal on their side. x402 does that with plain HTTP. The server answers an unpaid request with 402 Payment Required and machine-readable terms, the agent signs a stablecoin payment and retries, and the server returns the result.

This walkthrough adds x402 to an existing Express app without touching the handler code. It also covers the parts quickstarts skim over: discovery metadata, pricing, testing and directories.

Step 1: what an x402 v2 response looks like

An unpaid request to an x402-protected route returns something like this (from the local server built in Step 3):

HTTP/1.1 402 Payment Required Content-Type: application/json; charset=utf-8 PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwi... Cache-Control: no-store 

The PAYMENT-REQUIRED header is base64-encoded JSON. Decode it:

curl -s -D - -o /dev/null "http://localhost:4021/v1/summary?url=https://example.com" \ | grep -i '^payment-required' | cut -d' ' -f2 | tr -d '\r' | base64 -d | jq '{x402Version, accepts}' 

{ "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:84532", "amount": "2000", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "payTo": "0x000000000000000000000000000000000000dEaD", "maxTimeoutSeconds": 300, "extra": { "name": "USDC", "version": "2" } } ] } 

Field by field:

• scheme: "exact": the buyer pays exactly amount. x402 also defines upto (authorize a maximum, charge actual usage) and batch-settlement (off-chain vouchers settled in batches). Start with exact.
• network: a CAIP-2 ID. eip155:84532 is Base Sepolia (testnet); Base mainnet is eip155:8453.
• asset: the USDC contract on that network (on Base mainnet it's 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). amount is in atomic units, and USDC has 6 decimals, so "2000" is $0.002.
• payTo: the address that receives the money (a placeholder burn address in this demo). The facilitator never holds your funds.

The decoded JSON also has a resource object (URL, description, MIME type) and an extensions.bazaar block describing the inputs, covered in Step 4.

The client pays by retrying with a PAYMENT-SIGNATURE header. The server asks a facilitator to verify and settle that payment, then returns the result with a PAYMENT-RESPONSE header (base64 JSON that includes the settlement transaction). Some older clients still speak v1 (an X-PAYMENT header and terms in the JSON body). If you need to support them, read the v1 to v2 migration guide first.

Step 2: choose a facilitator

The facilitator verifies the buyer's signature and submits the USDC transfer on-chain, so you don't run blockchain infrastructure. These facts come from each provider's docs and endpoints as of Oct 25, 2026:

The facilitator is one constructor argument, so switching later is a small change.

Step 3: add the middleware

Install the official packages (TypeScript, Express; Hono, Next.js, Fastify, Go and Python versions are in the seller quickstart):

npm install express @x402/express @x402/core @x402/evm @x402/extensions 

Here's a small existing API with one free route and one route we want to charge for. The handler code stays the same. The only new part is the paymentMiddleware block:

// server.mjs: an existing Express API with one free route and one paid route. import express from 'express'; import { paymentMiddleware, x402ResourceServer } from '@x402/express'; import { HTTPFacilitatorClient } from '@x402/core/server'; import { ExactEvmScheme } from '@x402/evm/exact/server'; import { bazaarResourceServerExtension, declareDiscoveryExtension } from '@x402/extensions/bazaar'; const PAY_TO = process.env.PAY_TO; // your receiving address (0x...) const NETWORK = process.env.X402_NETWORK ?? 'eip155:84532'; // Base Sepolia; Base mainnet is eip155:8453 const facilitator = new HTTPFacilitatorClient({ url: 'https://x402.org/facilitator' }); // testnet only const resourceServer = new x402ResourceServer(facilitator) .register(NETWORK, new ExactEvmScheme()); resourceServer.registerExtension(bazaarResourceServerExtension); const app = express(); app.use(paymentMiddleware({ 'GET /v1/summary': { accepts: [{ scheme: 'exact', price: '$0.002', network: NETWORK, payTo: PAY_TO }], description: 'Summarize a public web page as JSON (title, word count, first paragraph)', mimeType: 'application/json', extensions: { ...declareDiscoveryExtension({ input: { url: 'https://example.com' }, inputSchema: { properties: { url: { type: 'string', description: 'Public http(s) URL' } }, required: ['url'], }, output: { example: { title: 'Example Domain', words: 19, first: 'This domain is for use in documentation examples...' } }, }), }, }, }, resourceServer)); // Free routes stay free: the middleware only touches the routes listed above. app.get('/health', (_req, res) => res.json({ ok: true })); // Your existing handler, unchanged. app.get('/v1/summary', async (req, res) => { const url = String(req.query.url ?? ''); if (!/^https?:\/\//.test(url)) return res.status(400).json({ error: 'url must be http(s)' }); const html = await (await fetch(url)).text(); const text = html.replace(/<script[\s\S]*?<\/script>|<style[\s\S]*?<\/style>/gi, '').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim(); res.json({ title: html.match(/<title>([^<]*)<\/title>/i)?.[1] ?? null, words: text.split(' ').length, first: text.slice(0, 120) }); }); app.listen(4021, () => console.log('listening on http://localhost:4021')); 

Run it (set "type": "module" in package.json, or keep the .mjs extension) and call both routes:

PAY_TO=0xYourAddress node server.mjs curl -i http://localhost:4021/health # 200 {"ok":true} curl -i "http://localhost:4021/v1/summary?url=https://example.com" # 402 + PAYMENT-REQUIRED 

My run returned 200 {"ok":true} and then 402 Payment Required. The decoded header had "network": "eip155:84532", "amount": "2000" and the Base Sepolia USDC contract 0x036CbD53842c5426634e7929541eC2318f3dCF7e. The middleware converted the $0.002 price string to atomic units.

Some behavior worth knowing, checked against the @x402/express 2.28.0 source:

• Unpaid requests get a 402 before your handler runs. Even GET /v1/summary with no url returned 402, not 400. That's what directory crawlers need: they probe without paying, and they skip routes that answer 400 or 404 (Step 7).
• Settlement happens after your handler, and only on success. The middleware buffers your response. If your handler returns a status of 400 or higher, it cancels settlement and the buyer isn't charged. So validate input in the handler and return a 400 when it's wrong. Bad requests stay free.
• Browser clients need CORS. If browsers will call you, add Access-Control-Expose-Headers: PAYMENT-REQUIRED, PAYMENT-RESPONSE, or client JavaScript can't read the terms.

Going to mainnet with a hosted x402 facilitator

Keep HTTPFacilitatorClient and point it at a facilitator that supports mainnet. If your provider needs an API key, follow its docs for passing it, and keep the key in the environment:

// Use any x402 facilitator that supports your mainnet network (see the x402 docs' facilitator list). const facilitator = new HTTPFacilitatorClient({ url: 'https://your-x402-facilitator.example' }); const resourceServer = new x402ResourceServer(facilitator) .register('eip155:8453', new ExactEvmScheme()); resourceServer.registerExtension(bazaarResourceServerExtension); 

I didn't run this against mainnet. Then set X402_NETWORK=eip155:8453 and make sure PAY_TO is a mainnet address you control. For example, to use PayAI, set url to https://facilitator.payai.network. Some providers also ship SDK helpers that set up the facilitator, schemes and Bazaar metadata in one call, so check your provider's seller quickstart.

If your product is an MCP server rather than HTTP routes, the official @x402/mcp package wraps tools in the same way. Start with the x402 docs' MCP guide.

Step 4: describe your inputs, or agents can't call you

A 402 that only says "pay $0.002" isn't enough. An agent that found your route in a catalog has to know which parameters to send before it pays. That's what the declareDiscoveryExtension(...) block does: it adds an extensions.bazaar object to every 402, with an example input, a JSON Schema and an example output.

This isn't optional polish. x402scan's published discovery spec says a route whose challenge lacks an input schema is "strict non-invocable" and gets marked skipped. The Bazaar discovery docs say much the same: "without them, agents can discover your endpoint but can't construct a valid call."

• Write the description for a model, not a landing page. Say what goes in, what comes out, what it costs and when you don't charge.
• Make the example output real. Paste an actual response, trimmed.
• Keep the schema small. Required fields, types and a one-line description each.

Step 5: publish /openapi.json (and /.well-known/x402)

x402scan's spec lists its discovery order: /openapi.json first, then /.well-known/x402. For each paid operation it wants an x-payment-info object with protocols and a price, plus a 402 entry in responses. For the demo route:

{ "openapi": "3.1.0", "info": { "title": "Page Summary API", "version": "1.0.0" }, "paths": { "/v1/summary": { "get": { "operationId": "summarize_url", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [{ "x402": {} }] }, "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Public http(s) URL" } ], "responses": { "200": { "description": "Summary (payment settled)" }, "400": { "description": "Invalid input (not charged)" }, "402": { "description": "Payment Required (x402 v2 terms in the PAYMENT-REQUIRED header)" } } } }, "/health": { "get": { "responses": { "200": { "description": "OK (free)" } } } } } } 

List free routes too, without x-payment-info, so an agent can try something before it spends. /.well-known/x402 is the simpler fallback, a list of paid URLs:

{ "version": 1, "resources": ["https://api.example.com/v1/summary"] } 

The spec also says the live 402 is the source of truth over static files. If your OpenAPI price and your 402 disagree, the 402 wins, so generate both from the same config.

Step 6: test with a tiny payment

On testnet first. Keep the testnet facilitator and eip155:84532, get test USDC on Base Sepolia from Circle's faucet, and pay your own route with the buyer quickstart. This costs nothing and exercises the whole flow.

Then one real call on mainnet. Use a dedicated wallet holding a few cents of USDC, never your main wallet, and cap what the client may pay. With @x402/fetch:

// pay-once.mjs: one capped test call against YOUR OWN route. import { wrapFetchWithPaymentFromConfig } from '@x402/fetch'; import { ExactEvmScheme } from '@x402/evm'; import { privateKeyToAccount } from 'viem/accounts'; const MY_PAY_TO = '0xYourAddress'; const pay = wrapFetchWithPaymentFromConfig(fetch, { schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(privateKeyToAccount(process.env.TEST_BUYER_KEY)) }], spendControls: { maxAmountPerPayment: '$0.01' }, // hard USD cap policies: [(_v, reqs) => reqs.filter((r) => r.payTo.toLowerCase() === MY_PAY_TO.toLowerCase())], // only pay yourself }); const res = await pay('https://api.example.com/v1/summary?url=https://example.com'); console.log(res.status, res.headers.get('PAYMENT-RESPONSE'), await res.json()); 

I checked that this config loads with 2.28.0, but didn't run it for this article. The spendControls and policies options come from the @x402/core README. What to check after one call:

1. HTTP 200 and a PAYMENT-RESPONSE header. Decode it like the 402 header. It contains the settlement transaction hash.
2. The USDC actually arrived at payTo (look up the hash on a Base block explorer such as Basescan).
3. A request your handler rejects (for example a bad url, sent with payment) returns 400 and doesn't settle. Confirm that on-chain too.

Send one payment per route and stop. If something fails, read the error before retrying, because a retry is another real payment.

Step 7: get listed where agents look

None of these listings cost anything. They're how agents find paid endpoints today:

• x402 Bazaar, shown on agentic.market. There's no form. Per the Bazaar docs, once a facilitator that supports Bazaar settles a payment for an endpoint that advertises Bazaar metadata, the endpoint gets indexed. Search then ranks by relevance and quality (recent calls, unique payers, completeness of the description and schemas). So the mainnet test call in Step 6 does double duty if your facilitator feeds the Bazaar.
• x402scan. Use its "Add Server" flow with your origin. It reads /openapi.json, then /.well-known/x402, probes each route for a 402, and reports which routes registered and which it skipped, with reasons.
• 402 Index. POST https://402index.io/api/v1/register with url, name and protocol: "x402" (plus optional description, category, price and contact email). It probes your endpoint and queues it for review. The register response offers instant approval if you verify your domain, which means serving a token file it gives you.
• The official MCP Registry, if you also expose MCP. Describe your remote server in a server.json and publish it with the mcp-publisher CLI. Namespaces are proven with GitHub, a DNS TXT record or an HTTP file on your domain (mcp-publisher login dns --domain yourdomain.com ...). With a domain namespace like com.yourdomain/tool, no GitHub account is needed. Many MCP directories pull from this registry.

Step 8: price per route

• Price each route on its own. Every key in the middleware config has its own accepts. A cheap lookup and an expensive crawl shouldn't share a price, and buyers should pay only for what they call.
• Do the facilitator math. With exact, every paid call is one on-chain settlement. If your facilitator charges $0.001 per settlement above a free allowance, a $0.001 route would hand all of its revenue to the fee at that volume. Either price above the fee, add a batch route (one payment for many items), or look at batch-settlement for high-frequency traffic.
• Keep a free tier. A free preview or a small free tool lets an agent, or the developer behind it, check quality before paying.
• Use upto when cost varies. If a call can be cheap or expensive (LLM tokens, pages crawled), upto lets you charge actual usage up to a stated maximum. The seller quickstart shows setSettlementOverrides.
• Don't charge for failures. Return 4xx and 5xx for bad input and upstream errors, so the middleware skips settlement.

Limitations

• Demand is early. Directories list tens of thousands of x402 resources, and sellers report that much of their traffic is crawlers checking prices rather than buyers. A paywall makes paying possible. It doesn't create customers on its own.
• Your obligations. You're receiving stablecoins. Tax, accounting and compliance questions are yours to answer, and this article isn't advice on them.
• No refunds in the protocol. x402 has no chargebacks, which is another reason to settle only on success.
• Versions move fast. Everything here was checked against @x402/* 2.28.0 and the docs as of Oct 25, 2026.

References

• x402 seller quickstart: https://docs.x402.org/getting-started/quickstart-for-sellers
• x402 facilitators: https://docs.x402.org/dev-tools/facilitators
• x402 Bazaar discovery: https://docs.x402.org/extensions/bazaar
• x402 buyer quickstart: https://docs.x402.org/getting-started/quickstart-for-buyers
• 402 Index API docs: https://402index.io/api/v1/docs.md
• Official MCP Registry: https://registry.modelcontextprotocol.io