x402 v2 Protocol Headers
The x402 protocol now uses dedicated headers: PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE.
The x402 protocol has moved to v2, introducing three dedicated HTTP headers for the payment flow. This replaces the previous single X-PAYMENT header with a clearer, directional design.
New headers
| Header | Direction | Description |
|---|---|---|
PAYMENT-REQUIRED | Server → Client | Base64-encoded payment requirements (schemes, price, network, destination) |
PAYMENT-SIGNATURE | Client → Server | Base64-encoded payment payload proving the client authorized payment |
PAYMENT-RESPONSE | Server → Client | Base64-encoded settlement response with structured outcome feedback |
Why the change?
The single X-PAYMENT header was overloaded — it carried different data depending on direction. The v2 headers make the protocol self-documenting: each header has one purpose and one direction.
Migration
If you're using @x402/core v2+, no code changes are needed — the SDK handles the new headers automatically. If you built a custom client, update your header names:
- Sending payment: use
PAYMENT-SIGNATUREinstead ofX-PAYMENT - Reading requirements: parse the
PAYMENT-REQUIREDheader from 402 responses - Reading settlement result: check the
PAYMENT-RESPONSEheader