x402 Payment Headers

The x402 payment flow uses three HTTP headers. The server declares payment requirements in PAYMENT-REQUIRED. The client proves payment in X-PAYMENT. The server confirms settlement in X-PAYMENT-RESPONSE. All values are base64-encoded JSON.

PAYMENT-REQUIRED

Response

PAYMENT-REQUIRED is the x402 response header returned alongside HTTP 402 Payment Required. It contains a base64-encoded JSON object describing the payment requirements: accepted schemes, price, currency (USDC), network (Base), and the recipient address.

Format

Base64(JSON): {schemes: [{scheme: string, network: string, amount: string, currency: string, address: string}]}

PAYMENT-REQUIRED example

http

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJzY2hlbWVzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJiYXNlIiwiYW1vdW50IjoiMTAwMDAiLCJjdXJyZW5jeSI6IlVTREMiLCJhZGRyZXNzIjoiMHgxMjM0NTY3ODkwYWJjZGVmIn1dfQ==
Content-Type: application/json

{"error":"payment_required","message":"This endpoint costs $0.01 USDC"}

Full reference →

X-PAYMENT

Request

X-PAYMENT is the client-side x402 request header containing a base64-encoded signed payment payload. The client attaches X-PAYMENT when retrying a request that returned 402 Payment Required. The server verifies the payment via a facilitator before granting access.

Format

Base64(JSON): {scheme: string, payload: {txHash: string, tokenAddress: string, amount: string, from: string, to: string}}

X-PAYMENT example

http

GET /api/premium-data HTTP/1.1
Host: api.example.com
Authorization: Bearer optional-for-identity
X-PAYMENT: eyJzY2hlbWUiOiJleGFjdCIsInBheWxvYWQiOnsidHhIYXNoIjoiMHhhYmNkZWYxMjM0NTY3ODkwIiwidG9rZW5BZGRyZXNzIjoiMHg4M2E3NjNkYzE4N2Q3YWJlNjllM2M0NTYzYThhNjc0ZGU2ZjU3MTA4IiwiYW1vdW50IjoiMTAwMDAiLCJmcm9tIjoiMHh1c2VyQWRkcmVzcyIsInRvIjoiMHhzZXJ2ZXJBZGRyZXNzIn19

Full reference →

X-PAYMENT-RESPONSE

Response

X-PAYMENT-RESPONSE is the x402 response header returned alongside a successful 200 response after payment verification. It contains a base64-encoded JSON receipt confirming the payment was verified, the transaction hash, and the settlement timestamp.

Format

Base64(JSON): {success: boolean, txHash: string, network: string, settledAt: string}

X-PAYMENT-RESPONSE example

http

HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0eEhhc2giOiIweGFiY2RlZjEyMzQ1Njc4OTAiLCJuZXR3b3JrIjoiYmFzZSIsInNldHRsZWRBdCI6IjIwMjYtMDEtMTVUMTA6MDA6MTBaIn0=

{"data":"Premium content..."}

Full reference →