X-PAYMENT
RequestX-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.
Description
X-PAYMENT is the proof-of-payment header. After receiving a 402 with PAYMENT-REQUIRED, the client constructs a payment payload: the transaction hash from a USDC transfer on Base, the token contract address, the amount, the sender address, and the recipient address. This payload is signed and base64-encoded.
The server passes X-PAYMENT to its configured facilitator (Coinbase or a compatible service) which verifies: the transaction exists on-chain, the amount matches the requirement, the recipient matches, and the transaction has not been used before (replay protection).
The facilitator responds to the server synchronously (within the same HTTP request's processing), allowing the server to grant or deny access in a single round-trip.
Format
Base64(JSON): {scheme: string, payload: {txHash: string, tokenAddress: string, amount: string, from: string, to: string}}
GET /api/premium-data HTTP/1.1
Host: api.example.com
Authorization: Bearer optional-for-identity
X-PAYMENT: eyJzY2hlbWUiOiJleGFjdCIsInBheWxvYWQiOnsidHhIYXNoIjoiMHhhYmNkZWYxMjM0NTY3ODkwIiwidG9rZW5BZGRyZXNzIjoiMHg4M2E3NjNkYzE4N2Q3YWJlNjllM2M0NTYzYThhNjc0ZGU2ZjU3MTA4IiwiYW1vdW50IjoiMTAwMDAiLCJmcm9tIjoiMHh1c2VyQWRkcmVzcyIsInRvIjoiMHhzZXJ2ZXJBZGRyZXNzIn19