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 by | With | Holds | Version 1 equivalent |
|---|---|---|---|---|
PAYMENT-REQUIRED | Server | A 402 reply | The price and payment options | The JSON response body |
PAYMENT-SIGNATURE | Client | The repeated request | The signed payment | X-PAYMENT |
PAYMENT-RESPONSE | Server | The result | The settlement receipt | X-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:
| Field | Required | Meaning |
|---|---|---|
x402Version | Yes | 2 |
resource | Yes | What is being sold. See below |
accepts | Yes | A list of offers. The client picks one |
error | No | Why payment is needed, or why the last payment failed |
extensions | No | Extra features, such as the Bazaar listing |
The resource object:
| Field | Required | Meaning |
|---|---|---|
url | Yes | The address being paid for |
description | No | What it does, in words |
mimeType | No | The type of the result, such as application/json |
serviceName, tags, iconUrl | No | Display details |
Each offer in accepts:
| Field | Required | Meaning |
|---|---|---|
scheme | Yes | How payment is made: exact, upto and so on |
network | Yes | Which network, in CAIP-2 form such as eip155:8453 |
amount | Yes | The price, as a whole number in the token's smallest unit |
asset | Yes | The token's contract or mint address |
payTo | Yes | The address that receives the payment |
maxTimeoutSeconds | Yes | How long the payment may take to complete |
extra | No | Details the scheme needs. For EVM tokens, name and version identify the token for signing |
PAYMENT-SIGNATURE
| Field | Required | Meaning |
|---|---|---|
x402Version | Yes | 2 |
accepted | Yes | A copy of the offer the client chose |
payload | Yes | The signed payment. Its shape depends on the scheme and network |
resource | No | The resource being paid for |
extensions | No | Extension data |
For exact on an EVM network, payload holds a signature and an authorization with from, to, value, validAfter, validBefore and nonce.
PAYMENT-RESPONSE
| Field | Required | Meaning |
|---|---|---|
success | Yes | Whether settlement succeeded |
transaction | Yes | The blockchain transaction identifier |
network | Yes | The network it settled on |
payer | No | The paying address |
amount | No | The amount settled |
errorReason, errorMessage | No | Why 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
- x402 version 2 specification
- x402 version 2 HTTP transport specification
- x402 version 1 specification
- x402 version 1 HTTP transport specification
Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.
Related questions
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.