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

> 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](https://www.ask402.ai/x402/x402-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

```bash
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](https://www.ask402.ai/tools/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](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md)
- [x402 version 2 HTTP transport specification](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md)
- [x402 version 1 specification](https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v1.md)
- [x402 version 1 HTTP transport specification](https://github.com/x402-foundation/x402/blob/main/specs/transports-v1/http.md)

---

Facts checked against the sources above on 2026-11-20. Canonical page: https://www.ask402.ai/x402/x402-headers-and-fields
