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
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
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
}]
}
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));
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)