x402 Header Format

v2 header map

PAYMENT-REQUIRED is server-to-client. It appears with the 402 response and tells the client what payment options are acceptable. PAYMENT-SIGNATURE is client-to-server. It carries the signed scheme-specific payment payload on the retry. PAYMENT-RESPONSE is server-to-client. It reports settlement or payment execution feedback.

Treat those headers as structured data. Logging only the raw Base64 string is not enough for support. Decoding them for internal troubleshooting helps identify wrong network, wrong amount, wrong recipient, stale v1 examples, and missing retry-safety fields.

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 PaymentRequired>

GET /paid-resource HTTP/1.1
PAYMENT-SIGNATURE: <base64 PaymentPayload>

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <base64 SettlementResponse>

PaymentRequired shape

A v2 PaymentRequired object should identify the protocol version, describe the resource, and include one or more accepted payment options. In common exact-payment examples, each accepted option names the scheme, CAIP-2 network, atomic token amount, asset, and seller recipient.

Seller route configuration may use a dollar string such as "$0.01" when a default asset exists for the network. The advertised payment requirements still need unambiguous token and amount data so a client can decide whether the offer fits policy.

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.example.com/paid-report",
    "description": "Single paid JSON report",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0xYourRecipientAddress"
    }
  ]
}

Legacy migration

Many older examples use X-PAYMENT for the client header and X-PAYMENT-RESPONSE for the response header. The migration guide maps those to PAYMENT-SIGNATURE and PAYMENT-RESPONSE in v2. It also maps base-sepolia to eip155:84532 and base to eip155:8453.

If a paid request keeps returning 402 after a retry, check for a mixed v1/v2 client, a legacy network alias, or a server that emits one header generation while expecting the other on retry.

• v1 client payment header: X-PAYMENT.
• v2 client payment header: PAYMENT-SIGNATURE.
• v1 response header: X-PAYMENT-RESPONSE.
• v2 response header: PAYMENT-RESPONSE.

Safe debugging

Decoded headers can contain resource URLs, wallet addresses, signed payloads, payment identifiers, or extension metadata. Keep them out of public issue trackers unless they are sanitized. A local decoder is useful because the payload never has to leave the machine used for debugging.

Decoding is not verification. A Base64 string can be valid JSON and still be an invalid payment. Verification requires the scheme rules, the selected network, the original payment requirements, and usually facilitator or chain access.