How HTTP 402 works in the x402 protocol
HTTP 402 Payment Required was reserved in the original HTTP spec but left undefined for decades. The x402 protocol finally gives it a concrete, interoperable meaning: a server can charge for a request inline, using nothing but standard HTTP and a stablecoin transfer — no API keys, no accounts, no checkout redirect.
The flow has four steps:
- Request. A client (an app, a script, or an autonomous AI agent) requests a paid resource, e.g.
GET /premium. - Challenge. The server replies
402 Payment Requiredwith a JSON body. That body holds anacceptsarray — each entry is one way you'll accept payment (amount, token, network, destination address). - Pay. The client picks an entry, signs an on-chain payment (typically USDC on Base) and encodes the proof.
- Retry. The client repeats the same request with an
X-PAYMENTheader carrying that proof. The server verifies it — directly or through a facilitator — and returns the resource with anX-PAYMENT-RESPONSEheader confirming settlement.
Because the whole handshake rides on ordinary status codes and headers, any HTTP client can implement it. That is what makes 402 attractive for the machine-to-machine payment economy: an agent that can fetch() can also pay, with no human in the loop.
x402 payment-requirement field reference
Each object inside the accepts array is a "payment requirement". These are the fields this builder emits, what they mean, and the gotchas:
| Field | Type | Meaning & gotchas |
|---|---|---|
scheme | string | Payment scheme. exact means "pay this precise amount". It's the only widely-supported scheme today. |
network | string | Chain id, e.g. base, base-sepolia. The client must support it and the asset must live on it. Mismatched network is the #1 integration bug. |
maxAmountRequired | string | Price in the token's base units as a decimal string — not a float. For USDC (6 decimals) $0.01 is "10000". Use our unit converter to get this right. |
resource | string | The canonical URL being paid for. Should match the request so proofs can't be replayed against a different endpoint. |
description | string | Human-readable label shown in wallets/agents. Optional but strongly recommended for trust. |
mimeType | string | The media type the client gets after paying, e.g. application/json. |
payTo | string | The address that receives funds — your wallet. Double-check it; payments are irreversible. |
maxTimeoutSeconds | number | How long the client has to pay and retry before the challenge is considered stale. |
asset | string | The ERC-20 token contract address on that network. USDC on Base is 0x8335…2913. Native ETH is not used; pick a stablecoin contract. |
Worked examples
Charge $0.001 per API call (micropayment)
Per-request metering is the canonical x402 use case — an agent pays a tenth of a cent each time it hits your endpoint. Set Price to 0.001; the builder emits maxAmountRequired: "1000" for USDC. There's no minimum-charge floor like card processors impose, which is exactly why 402 unlocks sub-cent pricing that Stripe can't.
Sell a one-off file or report
Set a higher price (say 2.50 → "2500000"), point resource at the download URL, and set mimeType to the file type. After payment, return a short-lived signed URL instead of the bytes directly.
Testnet first
Pick Base Sepolia while developing. The asset auto-switches to testnet USDC (0x036C…CF7e). You can get free testnet USDC from a faucet, so you never risk real funds while wiring up the handshake.
Common 402 mistakes (and how to avoid them)
- Sending a float for the amount.
maxAmountRequired: 0.01is wrong; it must be the integer base-unit string"10000". Floats lose precision and many clients reject them. - Asset/network mismatch. Putting a Base USDC address on the
ethereumnetwork. The token contract address is chain-specific. - Forgetting the
X-PAYMENTre-request. 402 is a two-trip protocol. The client must repeat the original request with the proof header — not call a different endpoint. - No server-side verification. Never trust the presence of the header alone. Verify the payment (yourself or via a facilitator) before serving the resource.
- Wrong
payTo. Funds go where you say. Test on Sepolia first and confirm receipt.
Do I need a facilitator?
A facilitator is an optional service that verifies and settles payments for you, so your server doesn't have to talk to the chain directly. You can run x402 without one (verify on-chain yourself), but a facilitator removes RPC plumbing and handles settlement edge-cases. Coinbase operates a public facilitator for Base; several projects in our x402 directory offer facilitator or middleware roles. Either way, the 402 body this tool builds is identical — the facilitator only changes how you verify the eventual X-PAYMENT header.
Frequently asked questions
Is HTTP 402 officially part of the HTTP standard?
Yes — 402 Payment Required is a reserved status code in the HTTP specification. It was historically unused; x402 defines a concrete, vendor-neutral body and header convention so different clients and servers can interoperate.
Does this tool send any payment or store my data?
No. Everything runs in your browser. It only formats a JSON template and example code from the values you type. Nothing is transmitted, logged, or stored.
Which networks and tokens are supported?
The builder ships presets for Base, Base Sepolia, Ethereum and Polygon with their USDC contracts, and you can paste any custom network id and token address. In practice most x402 traffic today is USDC on Base.
How is the amount encoded?
In the token's base unit as a decimal string. USDC has 6 decimals, so $1.00 is "1000000". Use the base-unit converter for other tokens and decimals.
Can AI agents pay a 402 automatically?
Yes — that's the point. Because the challenge is plain JSON over HTTP, an agent with a funded wallet can read accepts, pay, and retry without human interaction. This is why 402 is central to agentic commerce.
Next steps: convert amounts with the USDC base-unit converter, browse x402 implementations & SDKs, compare payment protocols, or read guides on the blog.