x402 Protocol Guide

x402 is an open internet-native payment standard that revives the dormant HTTP 402 'Payment Required' status code, enabling direct blockchain-based transactions over HTTP.

Payment Flow

Complete payment lifecycle in 6 steps

HTTP Request

Client

Browser or AI agent initiates API request

402 Payment Required

Server

Server responds with PAYMENT-REQUIRED header containing price, currency, network, and recipient address

Payment Payload Generation

Client

Client creates EIP-3009 signed payment payload, resubmits via X-PAYMENT header

Payment Verification

Facilitator

Facilitator validates signature, amount, address, and balance (~100ms)

On-Chain Settlement

Blockchain

Facilitator submits transaction (≈2 seconds finality on Base)

Resource Delivery

Server

Server returns 200 OK with PAYMENT-RESPONSE header containing transaction confirmation

HTTP Header Specification

Three key headers used in the x402 protocol

PAYMENT-REQUIREDStep 2

Included in the 402 response from the server. Base64-encoded JSON containing scheme, network, amount, recipient address, and resource information.

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "1000",
    "resource": "https://api.example.com/data",
    "description": "API access fee",
    "mimeType": "application/json",
    "payTo": "0x1234...abcd",
    "extra": {
      "name": "USDC",
      "version": "2"
    }
  }]
}

X-PAYMENTStep 3

Attached by client on retry. Contains x402 version, scheme, network, and EIP-3009 authorization details (signature, from/to addresses, amount, validity period, nonce).

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base-sepolia",
  "payload": {
    "signature": "0xabc1234...",
    "authorization": {
      "from": "0xBuyer...",
      "to": "0xSeller...",
      "value": "1000",
      "validAfter": "0",
      "validBefore": "1700000000",
      "nonce": "0x..."
    }
  }
}

PAYMENT-RESPONSEStep 6

Returned by server on success. Contains payment status and transaction hash.

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base-sepolia",
  "payload": {
    "success": true,
    "transactionHash": "0xtxhash..."
  }
}

EIP-3009: Transfer With Authorization

x402 leverages EIP-3009 to enable gasless USDC transfers.

Users only need USDC — no ETH/SOL required

Signatures generated off-chain — no gas costs for signing

validBefore/validAfter parameters control signature lifespan

Unique nonce prevents replay attacks

Solidity Interface

// EIP-3009: Transfer With Authorization
function transferWithAuthorization(
  address from,
  address to,
  uint256 value,
  uint256 validAfter,
  uint256 validBefore,
  bytes32 nonce,
  uint8 v, bytes32 r, bytes32 s
) external;

Next Steps

Integration Guide→Back to Overview