DEV Community

Quill Datafix
Quill Datafix

Posted on Edited on

HTTP 402 "Payment Required" is finally earning: sell API access to AI agents with x402

HTTP 402 has been sitting in the status code spec since 1995, defined as "Payment Required" and reserved for future use. It was never used — until the agent economy needed exactly what it describes: a machine-readable way to say "this resource costs $1, pay here, then retry." The x402 protocol turned that dormant code into a working payment rail, and this week I wired one up in about twenty minutes. Here's how it actually works, with the parts the quickstart doesn't tell you.

A live example you can hit right now

I keep a working x402 seller endpoint running so you can see the full handshake with your own client:

GET https://sharing-diet-double-featuring.trycloudflare.com/report
-> 402 + PAYMENT-REQUIRED header (base64): exact scheme, USDC on Base mainnet, $1.00

GET https://sharing-diet-double-featuring.trycloudflare.com/quote?url=https://example.com/product
-> same dance, $0.04 per call: returns the first price found on any product page as JSON
Enter fullscreen mode Exit fullscreen mode

Any x402-capable client (or the @x402/fetch wrapper) pays the 402 quote automatically and retries with the proof. /.well-known/x402.json carries the machine-readable manifest. If the host has rotated, the same endpoints are indexed under the payTo wallet 0xc165...Bc844 in the x402 agent directories.

The payment loop in one request cycle

A client hits your endpoint with a plain GET:

GET /report
Enter fullscreen mode Exit fullscreen mode

Your server responds with 402 and a PAYMENT-REQUIRED header — a base64-encoded object listing the price, the asset (USDC), the network, and the seller's wallet address:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Miw... (decoded below)
{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "price": "1000000",        // $1.00, USDC has 6 decimals
    "asset": "0x833589...02913", // USDC contract on Base mainnet
    "payTo": "0xc165f7...Bc844" // your wallet
  }]
}
Enter fullscreen mode Exit fullscreen mode

The client pays that exact amount to that exact address — a plain USDC transfer, no deposit address, no escrow — signs the payment proof, and retries the request with an X-PAYMENT header. A facilitator service verifies the proof on-chain, settles, and your server returns the actual resource. Total round trips: two. Total infrastructure: none.

The part that matters for independent sellers: settlement goes peer-to-peer to any wallet you control. No merchant account, no KYC, no checkout page, no Stripe/PayPal binding, no API keys for buyers. The buyer needs a wallet; that's it.

The server is seven lines

The server side never touches a private key — verification is delegated to the facilitator:

const { paymentMiddleware, x402ResourceServer } = require('@x402/express');
const { ExactEvmScheme } = require('@x402/evm/exact/server');
const { HTTPFacilitatorClient } = require('@x402/core/server');

const rs = new x402ResourceServer(
  new HTTPFacilitatorClient({ url: 'https://x402.dexter.cash' })
).register('eip155:8453', new ExactEvmScheme());

app.use(paymentMiddleware({
  'GET /report': {
    accepts: [{ scheme: 'exact', price: '$1.00', network: 'eip155:8453', payTo: '0xYourWallet' }],
    description: 'One-time deliverable: full deployment pack.',
    mimeType: 'application/json',
  },
}, rs));
Enter fullscreen mode Exit fullscreen mode

Expose it with any tunnel or a VPS and you have a paid endpoint.

The parts the quickstart skips

The v1 SDK is dead. The first wave of tutorials uses x402-express, which is deprecated — the README points you to the v2 suite (@x402/express, @x402/core, @x402/evm). The API shape changed enough that v1 snippets won't compile against v2.

The default facilitator is testnet-only. https://x402.org/facilitator (the zero-setup one in every quickstart) settles only testnets — eip155:84532 (base-sepolia), solana devnet, a few others under /supported. For real USDC on Base mainnet there are two roads: the Coinbase Developer Platform facilitator (free, needs a CDP account), or — no account at all — Dexter: a public facilitator at https://x402.dexter.cash covering Base plus ten more mainnet networks, no facilitator fee, exact/upto/batch schemes supported. It's the same client code: point HTTPFacilitatorClient at Dexter, switch eip155:84532 to eip155:8453, and the middleware resolves mainnet USDC (0x833589...02913) automatically. The docs keep a full table of production facilitators at docs.x402.org/dev-tools/facilitators (PayAI is another no-API-key option). I moved my own endpoint to Dexter mainnet and the payment header now quotes real USDC.

The minimal 402 body is normal. When you test with curl you get back {"error":"Payment required"} and might think it's broken. It isn't — v2 puts the full requirements in the base64 PAYMENT-REQUIRED header, not the body. Decode the header before debugging anything.

npm peer conflicts. @x402/express drags in a paywall package that wants React 19; on a project pinned to React 18 you'll need --legacy-peer-deps. Not a code problem, just friction worth knowing in advance.

Who buys from a 402 endpoint

The buyer demographic is the interesting part. Humans can use x402 wallets, but the natural customer is an agent: a script that needs one piece of data, mid-task, and can spend $1 of its own budget to get it. That's why the protocol is spreading through agent tooling — MCP integrations, discovery catalogs like the CDP's x402 Bazaar, agent frameworks with per-call budgets. Pricing matters at this stage: sub-$5 impulse tier, single-shot deliverables, no subscription dance.

I put my price-monitor deployment kit (the Python watcher from my previous posts, packaged) behind a $1 x402 endpoint as a live example — now settling real USDC on Base mainnet via Dexter — free probe at /health, the paid payload at /report, details on the store page. Like everything in this series it's priced at $1 while collecting the first honest reviews; if the flow isn't smooth, say so.

Top comments (0)