作者用 x402 在 Cloudflare Pages 免費方案上實現 AI Agent 呼叫 API 按次以 USDC 付款

Disclosure: this post was written with AI assistance and reviewed before publishing. I sell a starter kit based on this code (link at the end); everything below works without buying it.

HTTP has had a status code for this since 1997: 402 Payment Required. With the x402 protocol it finally does something. An AI agent calls your endpoint, gets a 402 with machine-readable payment terms, signs a USDC authorization and retries. Then it gets the data. There's no signup, no API key and no Stripe account.

I wanted to know how little it takes, so I shipped a real one: freetier-agent-api.pages.dev. It's one _worker.js on Cloudflare Pages (free plan) with no npm dependencies.

The flow

1. GET /api/apis/search?q=weather with no payment returns 402. The response carries a base64 PAYMENT-REQUIRED header (x402 v2) and a JSON body (x402 v1, for older clients). Both say: pay 5000 atomic units of USDC (= $0.005) on Base to this address.
2. The client signs an EIP-3009 transferWithAuthorization and retries with a PAYMENT-SIGNATURE header.
3. The worker POSTs that payload to a facilitator /verify, runs the handler, then calls /settle. The facilitator broadcasts the transfer and pays the gas, and the USDC lands in my wallet.

The part that surprised me: you don't need API keys

Coinbase's facilitator needs CDP keys on mainnet. Several public facilitators don't: PayAI (facilitator.payai.network) and xpay (facilitator.xpay.sh) both settle Base mainnet USDC without auth. I use PayAI and fall back to xpay:

const FACILITATORS = ['https://facilitator.payai.network', 'https://facilitator.xpay.sh'];
async function fac(op, body) {
  for (const f of FACILITATORS) {
    try {
      const r = await fetch(`${f}/${op}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
      const j = await r.json();
      if ('isValid' in j || 'success' in j) return j;
    } catch {}
  }
  return { error: 'no facilitator' };
}

Charge only after you succeed

Verify, run, settle, in that order. If the handler fails (bad URL, missing parameter), return 400 and never call settle, so the agent pays nothing. This matters, because agents retry a lot.

Testing without spending money

I generated a brand-new empty wallet with viem, signed a correct authorization and sent it to the live API. The facilitator answered invalid_exact_evm_insufficient_balance. So the signature, EIP-712 domain (USD Coin, version 2, chain 8453), amount and recipient were all accepted, and the only thing missing was money. That's a nice zero-cost end-to-end check.

Getting found by agents

A paid API nobody can find earns nothing. What worked:

• Bazaar metadata in the 402 (extensions.bazaar with input/output JSON schemas)
• /openapi.json with x-payment-info on each paid operation, plus /.well-known/x402
• x402dash: one POST https://api.x402dash.com/v1/register {"url": ...} per endpoint. It probes the 402 live
• x402scan: registration needs a Sign-In-With-X signature from any wallet, which @x402/extensions handles

What the API sells

• /api/apis/search ($0.001): 2,230 link-checked public and free-tier APIs, with filters like auth=none&alive=yes
• /api/free-tiers ($0.001): current free-tier limits for dev services and LLM APIs
• /api/robots-check ($0.001): may user-agent X crawl this URL?
• /api/page-meta ($0.001): title/OG/headings of a public page (respects robots.txt)

Free: /api/apis/sample, /openapi.json, /health.

Takeaways

• x402 runs fine on a free edge runtime. You don't need a server, a database or any keys.
• Return both v1 and v2 challenge formats for now; clients in the wild use both.
• Discovery is the real work. List everywhere.

If you want the cleaned-up code with tests and the listing steps, it's in the x402 Pay-Per-Call Starter. Or just read the 402 response from the live API and build your own.