Ask402

What are the x402 headers and what does each field mean?

Short answer

x402 version 2 uses three HTTP headers, each holding base64-encoded JSON. PAYMENT-REQUIRED is sent by the server with a 402 and lists the price and options. PAYMENT-SIGNATURE is sent by the client with the signed payment. PAYMENT-RESPONSE is sent by the server with the result and acts as the receipt. Version 1 used a JSON body and the X-PAYMENT headers.

The three headers

Header (version 2)Sent byWithHoldsVersion 1 equivalent
PAYMENT-REQUIREDServerA 402 replyThe price and payment optionsThe JSON response body
PAYMENT-SIGNATUREClientThe repeated requestThe signed paymentX-PAYMENT
PAYMENT-RESPONSEServerThe resultThe settlement receiptX-PAYMENT-RESPONSE

Every value is a JSON object encoded as base64. In version 2 all protocol information is in headers, and the response body belongs to the server.

PAYMENT-REQUIRED

The top-level object:

FieldRequiredMeaning
x402VersionYes2
resourceYesWhat is being sold. See below
acceptsYesA list of offers. The client picks one
errorNoWhy payment is needed, or why the last payment failed
extensionsNoExtra features, such as the Bazaar listing

The resource object:

FieldRequiredMeaning
urlYesThe address being paid for
descriptionNoWhat it does, in words
mimeTypeNoThe type of the result, such as application/json
serviceName, tags, iconUrlNoDisplay details

Each offer in accepts:

FieldRequiredMeaning
schemeYesHow payment is made: exact, upto and so on
networkYesWhich network, in CAIP-2 form such as eip155:8453
amountYesThe price, as a whole number in the token's smallest unit
assetYesThe token's contract or mint address
payToYesThe address that receives the payment
maxTimeoutSecondsYesHow long the payment may take to complete
extraNoDetails the scheme needs. For EVM tokens, name and version identify the token for signing

PAYMENT-SIGNATURE

FieldRequiredMeaning
x402VersionYes2
acceptedYesA copy of the offer the client chose
payloadYesThe signed payment. Its shape depends on the scheme and network
resourceNoThe resource being paid for
extensionsNoExtension data

For exact on an EVM network, payload holds a signature and an authorization with from, to, value, validAfter, validBefore and nonce.

PAYMENT-RESPONSE

FieldRequiredMeaning
successYesWhether settlement succeeded
transactionYesThe blockchain transaction identifier
networkYesThe network it settled on
payerNoThe paying address
amountNoThe amount settled
errorReason, errorMessageNoWhy it failed. See error codes

Version 1 differences

Version 1 sent the requirements as the 402 response body: x402Version, error and accepts. Each offer carried maxAmountRequired instead of amount, plain network names such as base, and its own resource, description and mimeType, because there was no top-level resource object.

Reading a header by hand

curl -si "https://agent402.tools/api/search?q=test" \
  | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' | base64 -d

Or use the 402 checker, which decodes the header and explains each offer.

In browsers

None of the three headers is on the list browsers expose to scripts by default. A server that expects browser clients must name them in Access-Control-Expose-Headers and Access-Control-Allow-Headers.

Sources

Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.

Who writes this. Ask402 is published by Havok Holdings LLC, which also runs Agent402, one of the x402 services covered here. Agent402 is labelled wherever it appears. Everything else is described from each project’s own documentation, and nobody pays to be listed.