What is the x402 protocol

HTTP 402 has historically been a ghost in the machine. Defined in the original HTTP/1.0 specification, the "Payment Required" status code was reserved for future use but never implemented. For decades, developers treated it as a placeholder, while web services relied on subscription gateways or ad networks to monetize content. That changed with the rise of x402, which turns that dormant code into a functional standard for micropayments.

x402 is an open payment standard that allows web services and AI agents to charge for API access and content directly over HTTP. Unlike traditional payment flows that require redirects to Stripe or PayPal, x402 embeds the payment logic into the protocol itself. When a client requests a resource, the server can respond with a 402 status code, specifying the exact payment required to access the data. Once the payment is verified, the content is delivered.

This distinction is critical for developers building financial infrastructure. You are not fixing a "402 error" in the traditional sense; you are implementing a payment handshake. The protocol handles the negotiation, verification, and delivery in a single transaction, reducing friction for both providers and consumers of data.

Set up a pay-per-request flow

The x402 handshake turns the HTTP 402 status code into a functional payment gateway. Instead of relying on subscriptions or API keys, you charge for every single request. This workflow moves from the initial client request to the final data delivery, ensuring that payment precedes access.

Pay-Per-API 402 in
1
Client requests the endpoint
The client initiates a POST request to your protected route. At this stage, the server recognizes the endpoint as a paid resource and does not return the data. Instead, it prepares the payment instructions required to access the content.
2
Server returns 402 with payment URI
The server responds with an HTTP 402 status code. Crucially, this response includes a payment URI and the specific amount required in USDC. This instruction tells the client exactly where to send funds and how much is needed for this specific data payload.
3
Client pays via USDC
The client executes the transaction using the provided payment URI. The payment is processed on-chain, typically involving a stablecoin like USDC. The client must wait for the transaction to be confirmed before the payment is considered valid.
4
Server grants access
Once the server verifies the on-chain payment, it grants access to the requested data. The client can now retrieve the information they originally asked for. The cycle is complete: payment verified, data delivered.

This flow relies on the official x402 specification, which defines how the 402 status code should carry payment instructions [1]. By following this sequence, you ensure that your API monetizes usage directly without complex middleware or third-party payment processors.

Verify on-chain payments before serving data

The x402 handshake relies on a simple exchange: the client pays, and the server verifies. When a request arrives, your API checks for a valid payment token in the headers. If the token is missing or invalid, the server returns an HTTP 402 Payment Required status, blocking access to the data. This status code was originally reserved for future payment systems, but x402 puts it to work today, allowing web services and AI agents to charge for API access directly over HTTP without traditional subscriptions.

Verification happens on-chain. The server checks the transaction hash to ensure the payment was confirmed on the specified blockchain network, such as Base or Ethereum. You must confirm that the USDC balance matches the requested data tier and that the token's expiration time has not passed. If any of these checks fail, the request is rejected.

To ensure your implementation is robust, use this verification checklist:

  • Confirm the transaction hash is valid and included in a block.
  • Check the USDC balance on the specified chain matches the price.
  • Verify the expiration time of the payment token has not passed.

The client receives a proof of payment that it can store and reuse for subsequent requests within the token's validity window. This eliminates the need for persistent session management or complex API key rotation. By handling payment and verification at the HTTP layer, you create a frictionless experience for users while maintaining strict control over who accesses your data.

Avoid common integration errors

The HTTP 402 status code is the most misunderstood status code in web development. It sits in a gray area between legacy protocol definitions and modern Web3 payment rails. When you see a 402 in your logs, you need to immediately distinguish between an administrative billing failure and a successful x402 payment handshake. Confusing the two leads to broken flows and lost revenue.

Administrative 402 errors are platform-specific flags. E-commerce platforms like Shopify or payment gateways like Stripe may return 402 to signal that a subscription is expired or a payment method has failed. In these cases, the server is telling the client, "We have your account, but the billing cycle isn't settled." These are not standard HTTP protocol errors; they are business logic signals. If you are building a Web3 data API, you should not use 402 for this. Use 401 (Unauthorized) or 403 (Forbidden) for authentication failures, and reserve 402 strictly for the payment request itself.

Transactional 402 errors are the core of the x402 protocol. According to the HTTP/1.1 specification, 402 was reserved for "future use" specifically to enable digital cash and micropayment systems. In the context of x402, a 402 response is not an error. It is a valid instruction. It means the server has received your request but requires a cryptographic payment before releasing the data. The client must then trigger a payment transaction (often via Bitcoin Lightning or another on-chain mechanism) and retry.

To debug correctly, follow this sequence:

  1. Check the response body. Does it contain a payment URI or invoice details? If yes, this is a valid x402 handshake. Proceed to pay.
  2. Check the authentication status. If the response lacks payment details but returns 402, your API key or token is likely invalid. Switch to 401/403 handling.
  3. Verify the payment status. If you paid and still get 402, the blockchain confirmation may be pending. Wait for the transaction to settle and retry.

Treating 402 as a failure rather than a payment step is the most common integration mistake. Design your client to expect 402 as a normal part of the data retrieval process, not as a system error.

FAQ about HTTP 402 payments

The HTTP 402 status code is a nonstandard response code reserved for future use, specifically designed to enable digital cash or micro-payment systems. In the context of x402, this code signals that the requested content is locked until the client completes the payment handshake.