Payment Flow

Understand how x402 handles payments end-to-end, from initial request to service delivery.

The x402 Payment Protocol

x402 uses HTTP 402 "Payment Required" status code to negotiate payments between clients and servers. The entire flow is automatic when using x402 client libraries.

Step-by-Step Flow

Client Initiates Request

Client makes a standard HTTP request to a protected endpoint:

GET /api/premium-data HTTP/1.1
Host: api.example.com
Accept: application/json

Server Returns 402

Server responds with HTTP 402 and payment instructions in headers:

HTTP/1.1 402 Payment Required
X-Accept-Payment: pay.base 0.001 USDC
X-Payment-Address: 0x742d35Cc6634C0532925a3b8...
X-Payment-Network: base
X-Facilitator-URL: https://facilitator.payai.network
Content-Type: application/json

{
  "error": "Payment required",
  "price": "0.001 USDC",
  "network": "base"
}

Client Parses Payment Info

x402 client library extracts payment details from the response headers:

• Payment amount: 0.001 USDC
• Recipient address: 0x742d35Cc...
• Network: Base
• Facilitator URL for verification

Create Transaction

Client creates a blockchain transaction:

{
  "from": "0xClientWalletAddress",
  "to": "0x742d35Cc6634C0532925a3b8...",
  "value": "0",
  "data": "0x..." // USDC transfer call data
}

Sign & Broadcast

User's wallet signs the transaction and broadcasts it to the blockchain. Transaction settles in seconds.

Retry with Proof

Client retries the original request with payment proof:

GET /api/premium-data HTTP/1.1
Host: api.example.com
X-Payment-Proof: 0x5f2d8a...transaction_hash
X-Payment-Network: base
Accept: application/json

Server Validates Payment

Server queries the blockchain (via facilitator) to verify the transaction is valid, confirmed, and matches the required payment.

Service Delivered

Payment verified! Server processes the request and returns the resource:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": "Premium content here",
  "timestamp": "2025-01-01T00:00:00Z"
}

Payment Verification

On-Chain Verification

The facilitator verifies payments by querying the blockchain directly. It checks:

• Transaction is confirmed on-chain
• Recipient address matches
• Amount matches or exceeds required payment
• Transaction hasn't been used before (no replay attacks)

Facilitator Role

Facilitators are services that help verify payments without requiring servers to run blockchain nodes. They provide a simple API to check if a transaction hash is valid.

Edge Cases

Insufficient Payment

If payment is less than required, server returns 402 again with the remaining amount needed.

Network Mismatch

Client must pay on the correct network specified by the server, or request fails.

Unconfirmed Transaction

Server may accept pending transactions or require confirmation depending on configuration.

Replay Attack Prevention

Each transaction hash can only be used once. Servers track used transaction hashes.

Dive Deeper

Learn about facilitators and see code examples of the complete flow.

Facilitators Guide Code Examples