What is HTTP 402 Payment Required?
The HTTP 402 status code is reserved for "payment required." While historically unused in traditional web development, it is now central to machine-to-machine billing in Web3. Unlike standard 4xx errors that signal client mistakes, a modern 402 acts as a functional instruction: the resource is available, but access is gated behind a crypto transaction.
This shift transforms 402 from an error message into a revenue stream. When an AI agent or scraper hits a paywall, a 402 response now includes instructions on how to pay via cryptocurrency, automating billing without human intervention.
Set up the x402 Payment Flow
Implementing x402 requires shifting from standard 200 OK responses to a payment-gated architecture. The server returns a 402 Payment Required status with embedded payment instructions. The client (human or agent) processes these headers, executes the transaction, and retries the request with proof of payment.
1. Define Priced Endpoints
Identify which API routes require payment. For each protected endpoint, determine the price per request. When a client hits a protected route without valid payment proof, your server constructs a specific 402 response containing the amount due and the payment destination, rather than a generic error.
2. Return the 402 Response
The HTTP response must include headers specifying the USDC contract address, the amount to send, and a unique transaction reference. This transforms the error response into a payable invoice. The client uses this data to initiate the transfer.
3. Handle Payment Retry
After the client executes the USDC transfer, they retry the original API request. This time, the request includes a signature or token proving payment. Your server validates this proof; if valid, it returns the data with a 200 OK status. If invalid, it returns the 402 response again.
Integrate Crypto Payments into Your API
To monetize an API using 402, bridge the gap between HTTP requests and blockchain transactions. The goal is to verify a confirmed USDC transaction before returning data, eliminating the need for complex API keys or subscription logins.
1. Set Up a Dedicated Payment Wallet
Generate a fresh Ethereum wallet address to act as your API's "cash register." Use tools like MetaMask or libraries like ethers.js to manage this key. Keep this wallet separate from your main treasury to track revenue and manage gas fees independently. Ensure it holds a small amount of ETH for potential gas refunds if using smart contract logic.
2. Configure Your API to Return 402
Modify your endpoint logic to check for a payment header (e.g., x-payment) before processing. If the header is missing or invalid, return an HTTP 402 Payment Required status. Include the payment amount and wallet address in the response headers so the client knows exactly what to pay and where.
3. Verify the Transaction On-Chain
Do not trust the client's claim that they paid. Use a provider like Alchemy, Infura, or Etherscan to query the transaction status. Verify that:
- The transaction is confirmed (wait for at least one block confirmation).
- The amount sent matches the required price.
- The sender address is not a known spam wallet.
Only after these checks pass should your API return the requested data. If the transaction is pending, return the 402 error with a "Payment pending" message.
4. Handle Retries and Edge Cases
Network congestion can delay transactions. Implement a retry mechanism in your client documentation and a timeout on the server side. If a transaction remains unconfirmed after a set period (e.g., 5 minutes), reject the request to prevent resource abuse. Consider issuing a short-lived session token after successful payment to allow multiple requests without re-verifying the blockchain for every call.
Common 402 Integration Errors
Technical missteps can block revenue. The 402 status code is a handshake between your API and the payer; when it fails, transactions are lost.
Ignoring Payment Instructions Headers
RFC 7725 suggests including a Paywall or Payment-Instructions header in a 402 response. Many developers treat 402 as a generic "access denied" error and drop the connection. This breaks the user experience because the client has no idea where to send funds. Always parse response headers before rejecting the request.
Misconfiguring Retry Logic
A 402 error is transient. Standard retry logic for 5xx server errors will fail here, as retrying without payment results in the same 402 response, wasting API calls and triggering rate limits. Implement a distinct retry policy for 402s: pause the request queue and wait for payment confirmation before resuming.
Hardcoding Currency or Amount
Hardcoding payment amounts in client-side code is a security risk and maintenance burden. If pricing changes, you must update every client instance. Let the API determine the amount. The server should calculate the fee based on the requested resource and return it in the 402 response, keeping pricing logic centralized.
Failing to Handle Partial Payments
Not all 402 scenarios are binary. Some APIs support partial payments or tiered access. If your integration assumes 402 means "total failure," you miss opportunities for upsells. Check your API documentation for partial payment support and design your UI to offer options like "Pay $5 for limited access."
Tools for Pay-Per-API 402 Implementation
Specialized libraries handle the heavy lifting of wallet connections and transaction verification.
x402 Protocol
The x402 protocol is an open standard for charging for API access directly over HTTP. It removes the need for traditional API keys. You can implement this in Next.js to monetize endpoints by returning a 402 status code with a payment request. For a practical guide, see the x402 protocol documentation.
Python Crypto Data Libraries
Libraries supporting the x402 pay-per-use model allow you to pull crypto prices using just a wallet with USDC. This simplifies access for users who prefer per-request payments over monthly fees. See how to access crypto data with x402 for a step-by-step breakdown.
As an Amazon Associate, we may earn from qualifying purchases.
No comments yet. Be the first to share your thoughts!