HTTP 402 Payment Required

HTTP 402 Payment Required is the status code a server returns when a resource exists but costs money. Long reserved for future use, it is now the price quote in x402 and MPP: the 402 carries the payment terms in its headers, and the payment rides on the retry.

A status code that waited

HTTP defines 402 Payment Required and, in the current specification (RFC 9110), says only that it is reserved for future use. For most of the web's history no one used it: payment happened on a separate checkout page, and the API behind it answered 401 or 403 when a key was missing.

Pay-per-request protocols give it a job. A 402 now means "this resource is here, and this is what it costs". The response tells the client how to pay, and the client pays by repeating the request with a payment attached. Two protocols define the details: x402, which puts the offer in a PAYMENT-REQUIRED header, and MPP, which uses the standard WWW-Authenticate header with a scheme named Payment.

What a 402 from this server contains

Every paid route answers an unpaid request with a 402 that carries both offers at once, plus a free path where one exists:

$ curl -i -X POST https://agent402.tools/api/hash \
    -H 'Content-Type: application/json' -d '{"text":"hello world"}'

HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIi...
WWW-Authenticate: Payment id="8w5V62E3...", realm="agent402.tools", method="evm",
  intent="charge", request="eyJhbW91bnQiOiIxMDAwIi...", expires="2026-09-24T12:41:07.520Z",
  opaque="eyJ4NDAyIjoie1wic2NoZW1l..."
X-Pow-Challenge: https://agent402.tools/api/pow/challenge?slug=hash

{"altPayment":{"protocol":"proof-of-work", ...}}
  • PAYMENT-REQUIRED: the x402 offer, base64 JSON with one entry per accepted chain.
  • WWW-Authenticate: Payment: the MPP challenge for the same price, bound to this server by a signed id and an expiry.
  • X-Pow-Challenge: on tools that accept proof-of-work, where to get a puzzle instead of paying money.

A client that speaks only one of the two protocols should look for the header it understands. An unfamiliar WWW-Authenticate scheme does not mean there is no way to pay.

A 402 costs nothing

Reading a 402 is free. It is a quote, not a charge, and no payment is taken until a request arrives carrying a signed payment that matches one of the offers. That makes the 402 a useful discovery step: an agent can learn the price of any route before deciding to buy.

Was I charged?

On this server settlement runs after the tool, and only for a successful response. So for a wallet payment the answer you hold tells you: a 200 with a PAYMENT-RESPONSE header (x402) or a Payment-Receipt header (MPP) was paid; a response with no receipt header was not charged, and neither was one whose x402 receipt reads success: false. A payment that is refused comes back as another 402, and when the refusal is about the credential the body says why in plain words.

Related

More explainers: x402 · MPP (Machine Payments Protocol) · Agent payments · Pay-per-call API · MCP payments