What HTTP 402 payment required means
The HTTP 402 status code was originally reserved in the HTTP/1.1 specification for future payment systems. For decades, it sat unused as a placeholder, while developers relied on API keys, subscription walls, and manual billing for monetization. Today, that placeholder is the foundation of programmable micropayments via the x402 protocol.
When a server returns a 402 Payment Required response, it signals that the requested resource is behind a paywall. Unlike traditional models that require upfront subscriptions or long-term contracts, 402 enables pay-per-use transactions at the protocol level. A client—whether a human browser or an AI agent—must complete a payment before the server will fulfill the request.
This shift changes how developers think about access control. Instead of maintaining complex authentication systems, you can let the HTTP response itself dictate payment terms. The client pays, receives a proof of payment, and retries the request. This works naturally for AI agents, allowing them to plan around the web and access services without human intervention or manual API key management.
Set up the x402 payment gateway
Configuring an API to accept crypto payments via the HTTP 402 status code is a straightforward process. The core concept is simple: the server returns a 402 Payment Required response containing a payment challenge, and the client must settle that payment to retry the request and receive the actual data. This mechanism replaces traditional API keys or subscription gates with a programmable, low-cost micropayment system that works naturally for AI agents and web clients alike [1].
To implement this, you need to handle the payment challenge logic on your backend. The following steps outline the workflow for enabling x402 on a backend server.
Start by identifying the API endpoint you want to monetize. For each route, determine the cost per request. This price can be fixed or dynamic based on computational load. In your backend logic, assign a specific value (e.g., in wei or a stablecoin) to each call. This value will be embedded into the payment challenge later.
When a request hits your endpoint, check for a valid payment signature. If none is present, do not return your data. Instead, return an HTTP 402 Payment Required status code. The body of this response should contain a "challenge" object. This challenge typically includes the transaction details, such as the amount to pay, the recipient address (your wallet), and a unique transaction ID or nonce to prevent replay attacks. This is the moment the client "sees" the price.
Once the client pays the challenge and retries the request with a signature, your server must verify it. Use a standard signature verification library (like ethers.js or viem) to validate that the signature was created by the wallet address that made the request and that the payment was actually sent to your address on the blockchain. If the signature is valid, proceed to return the requested data.
Clients may retry requests due to network latency or failed transactions. Ensure your server can handle duplicate signatures gracefully. You might want to implement a short-term cache of processed transaction IDs to prevent the same payment from being counted multiple times if the client sends the request twice. Also, consider adding a timeout to your challenge so that old payment requests expire.
As an Amazon Associate, we may earn from qualifying purchases.
Integrate agent wallet payments
Pay-Per-API 402 works best as a clear sequence: define the constraint, compare the realistic options, test the tradeoff, and choose the path with the fewest hidden costs. That order keeps the advice usable instead of decorative. After each step, pause long enough to check whether the recommendation still fits the reader's actual situation. If it depends on perfect timing, unusual access, or a best-case budget, include a simpler fallback.
Subscription vs. Pay-Per-API 402
Choosing between a monthly subscription and a pay-per-request model depends on your usage patterns and the predictability of your customer base. Traditional subscriptions work well for steady, high-volume users who need guaranteed access. However, they create friction for occasional users who hate paying for idle time.
Pay-per-API 402 micropayments remove that friction. Instead of an API key or a monthly bill, the server responds with a 402 Payment Required status. The client pays a small fee via a crypto wallet and retries the request. This model aligns cost directly with value, making it ideal for unpredictable workloads or AI agents that trigger on demand.
The following table breaks down the differences in cost structure, complexity, and user experience.
| Feature | Traditional Subscription | Pay-Per-API 402 |
|---|---|---|
| Cost Model | Fixed monthly fee regardless of usage | Pay only for successful requests |
| User Friction | High: requires sign-up, billing info, and keys | Low: wallet connection and instant payment |
| Usage Predictability | Best for steady, high-volume traffic | Best for sporadic or bursty traffic |
| Complexity | High: requires billing infrastructure and churn management | Low: built into the HTTP protocol via x402 |
| Best For | Enterprise SaaS and predictable B2B tools | AI agents, experimental APIs, and micro-services |
For most Web3 developers, the 402 model reduces overhead. You no longer need to manage subscription tiers or handle failed payments. The HTTP challenge-response mechanism handles the transaction automatically, allowing you to focus on the API logic rather than billing infrastructure.
Handle common integration errors
Even with a solid x402 implementation, real-world networks are messy. You will hit snags. The most frequent culprits are signature verification failures, insufficient gas, and retry header misconfigurations. Treat these not as bugs, but as expected friction points in a permissionless payment rail.
Signature Verification Failures
The most common error is the client signing the wrong payload. x402 requires the signature to cover the exact request body and headers. If your client serializes JSON differently than your server expects, the hash won't match.
Ensure your client library uses the same serialization format as your API definition. For example, if your server strips whitespace, your client must do the same before signing. Check the Authorization header format; it must include the wallet address and signature in the correct order.
Insufficient Gas and Network Congestion
Unlike traditional subscriptions, crypto payments require immediate settlement. If the user’s wallet has insufficient ETH for the gas fee, the transaction will fail. This is different from a declined credit card; the network simply rejects the transaction.
Inform users clearly if their gas balance is too low. Provide a fallback mechanism, such as prompting them to add a small amount of ETH to their wallet before retrying the request. Do not silently drop the request; a 402 response with a clear error message is better than a timeout.
Incorrect Retry Headers
Clients must respect the Retry-After header if the server returns a 429 or 402 with a specific rate limit. Sending rapid retries can trigger IP bans or wallet blacklisting.
Implement exponential backoff in your client library. If the server indicates a temporary issue, wait the specified duration before retrying. This reduces load on your infrastructure and prevents accidental denial-of-service behavior.
Frequently asked questions about 402
What is the 402 payment method?
The 402 payment method is a simple micropayment system. A server responds with a 402 status, the client pays a small fee via a crypto wallet, and then retries. There are no API keys, monthly subscriptions, or minimum transaction amounts. It is a programmable system that works as naturally for an AI agent as an HTTP request does.
How do you charge for API calls?
You can use pay-per-call pricing, where each request has a fixed price. The total cost is simply the number of calls multiplied by that rate. This model tracks the value and cost of each customer directly, making it ideal for pay-per-request API pricing.
What is the x402 payment guide?
The x402 guide covers the HTTP challenge and the wei-to-token calculation behind one request. It explains how to implement the payment flow so that clients can pay for specific API calls without complex setup.
No comments yet. Be the first to share your thoughts!