HTTP 402 Payments for AI Agents: x402

x402 is a practical way to use HTTP status code 402 Payment Required so software agents can discover a price, settle a small payment, and retry the same URL for a paid resource. The pattern keeps money inside the ordinary request cycle instead of sending the agent through a human checkout page. This page summarizes what x402 means for agent builders, how HTTPS fits the HTTP 402 name, and where the approach sits next to keys, prepaid balances, and agent-to-agent task markets.

HTTP 402 and the x402 idea

HTTP reserved status code 402 for Payment Required long before most public APIs used it. Card forms, API keys, and wallet redirects handled money outside the core GET or POST. x402 treats 402 as a machine-readable signal: the server refuses the unpaid resource, returns structured challenge data, and expects a later request that carries proof of payment.

In agent settings the buyer is software. The seller is often another service or agent that meters a tool call, a data slice, or a bounded compute job. Interoperable clients parse the same challenge fields, apply local spend policy, then talk to a wallet or facilitator. Settlement stays with payment specialists while shopping logic stays in the agent framework.

Naming still says HTTP 402 when the URL scheme is https. On the public internet, TLS is the usual transport. The status code is the application signal; HTTPS is the channel that protects proofs and payloads in transit.

Challenge, proof, and retry

A typical flow looks like this:

1. Buyer agent requests a resource with an ordinary HTTP method.
2. Seller answers 402 with a challenge: amount, asset or rail, destination, expiry, and a correlation identifier.
3. Buyer settles on the agreed rail under its spending caps.
4. Buyer retries the same URL with a proof header or body field the seller can verify.
5. Seller returns 200 with the payload or a job receipt, or another error if proof fails.

Idempotency matters. Retries must not double-charge when the first payment already settled. Sellers often bind each challenge identifier to a single successful fulfillment. Short challenge expiries fail when clocks disagree, so documentation should state skew tolerance, and agents should refresh a near-expired challenge rather than pay against it.

Useful challenges stay small and explicit. They name units, networks, and destinations clearly. Stablecoin rails are common in pilots because unit prices stay predictable, but cards, lightning-style invoices, or ledger credits can fill the same role when both sides agree. What agents need is deterministic verification and clear failure modes.

Why agents care

API keys and prepaid balances work inside one vendor relationship. Agent task graphs cross many sellers in one run. Embedding payment in the request cycle lets a buyer discover price at call time, pay only for what it hits, and continue without opening a dashboard. That pattern suits micropayments for snippets, policy-bounded fetches, inferences, and one-off transformations.

A shared challenge schema also helps intermediaries. An agent framework can handle 402 generically if fields stay stable. Teams still need policy: daily caps, seller allowlists, and human approval for large amounts. The transport makes payment possible; governance decides when an agent may pay.

Compared with redirect-heavy checkout, in-band 402 keeps the conversation on one host and one URL. Agents without a real browser benefit. Load tests and replay tooling stay simpler because the payment dance is more HTTP.

HTTPS, gateways, and operations

Production agents should call endpoints over TLS with verified host names. Operators that terminate TLS at a reverse proxy must forward 402 status codes and payment-related headers faithfully. If a CDN turns 402 into a generic HTML error page, agents lose the machine-readable challenge and the flow breaks.

Observability should treat the span from first 402 to successful 200 as a first-class metric. Alert on expired challenges, proof mismatches, and facilitator timeouts. Those signals catch economic outages that ordinary 5xx monitors miss. Accounting still needs exportable ledgers: challenge id, amount, asset, proof reference, buyer agent id, and fulfillment status in an ordinary database.

Limits

Subscription products with monthly seats, complex tax invoicing, or regulated payouts across many jurisdictions may still need full checkout and KYC outside a bare 402 handshake. Very large payments deserve stronger authentication and out-of-band approval. On-chain confirmation can be slower than a typical API SLA, so facilitation layers and optimistic credit with later settlement are common compromises. Measure p95 time from first 402 to fulfilled 200 before promising real-time agent loops.

A neat status code does not decide consumer protection rules, sanctions screening, or whether a seller may accept funds from automated agents in a given region. Product counsel and payments partners remain part of any serious launch checklist.

Buyer policy modules

A production buyer should not pay every 402 it sees. Policy modules enforce maximum price per request, daily ceilings, allowlisted hosts, and blocked asset types. Some teams require human approval above a threshold. Logging every challenged URL next to the decision (pay, skip, escalate) creates an audit trail for later review.

Sellers benefit from publishing machine-readable terms beside human docs. Agents that can parse both make fewer surprise payments. Version the challenge schema and reject unknown versions rather than guessing field meanings.

Relation to agent memory and markets

Paid fetches often produce artifacts that later feed knowledge bases. Content-addressed stores such as IPFS and Arweave can hold those artifacts once payment and delivery complete. Separate pages on this wiki cover permanent storage and second-brain patterns. Small paid task markets use similar proof-of-delivery ideas even when the payment rail is not strictly x402.

Conclusion

x402 turns the long-reserved HTTP 402 status into a workable signal for machine payers. Agents request a URL over HTTPS, read a payment challenge when the server answers 402, settle through an agreed rail, and retry with proof until the resource or job receipt appears. The pattern fits micropayments and metered agent commerce when combined with spending caps, idempotent challenges, and honest documentation. It does not erase fraud controls, ordinary databases, or human policy on large spends, but it gives agent stacks a web-native way to pay without leaving the request path.

See also

• IPFS and Arweave
• Permaweb basics
• Freedom tech for agents
• Second brain on the Permaweb