What is the x402 payment status?

The HTTP 402 status code was originally intended for future use. For decades, it sat in the HTTP/1.1 specification (RFC 7231) as a placeholder, rarely seen in the wild. While some legacy systems use it for specific payment gateways, it never became the standard for general web payments. That changed with the rise of x402, which has revived the code for a new purpose: agent-to-agent micropayments.

In the context of x402, the 402 status code serves as a clear signal to API clients: "Payment required." When a server receives a request it cannot fulfill without compensation, it responds with a 402 status. This is not an error in the traditional sense; it is a functional instruction. The resource is available, but it is locked behind a payment requirement. Once the client completes the transaction, access is granted.

This shift transforms 402 from a forgotten reservation into the backbone of agentic commerce. By using a standard HTTP response, x402 allows autonomous agents to negotiate and execute payments seamlessly, without needing custom payment flows or third-party intermediaries for every micro-transaction.

Set up the x402 payment flow

Implementing x402 shifts your API from a passive endpoint to an active merchant. Instead of guessing how an AI agent will pay, you define the price and the payment method directly in the HTTP response. The agent reads the instructions, executes the transaction, and sends proof back to you.

Here is the technical workflow for setting up this flow, based on the Base documentation and standard implementations.

1
Define priced endpoints

Start by identifying which API routes require payment. For each endpoint, determine the cost in a supported token (like USDC on Base) and the specific network. You need to know exactly how much the agent must pay before it even makes the request. This pricing logic should be static or dynamically calculated based on the resource being accessed.

2
Server returns 402 with payment URI

When the agent calls your API without valid proof of payment, your server must respond with an HTTP 402 Payment Required status code. This response is not an error; it is an instruction manual. It must include:

  • Payment-Required header: Contains the payment URI or instructions.
  • Payment-Uri header: A URI containing the contract address, token symbol, amount, and chain ID.
  • Payment-Proof header: A placeholder or specific format the agent must fill.

The agent parses this header to understand exactly where to send funds and how much.

3
Agent executes transaction

The AI agent receives the 402 response and parses the Payment-Uri. It then constructs a transaction on the specified blockchain (e.g., Base) to send the required amount of USDC to your wallet. This step is automated by the agent's payment library, which handles gas fees and transaction signing.

4
Server verifies and grants access

Once the agent completes the transaction, it includes the transaction hash or a signed proof in the Payment-Proof header of its next request. Your server verifies this proof by checking the blockchain for the transaction. If the payment is confirmed and matches the required amount, you grant access to the resource. If not, you return another 402 with updated instructions.

This flow ensures that you get paid before delivering value. By adhering to the x402 standard, you make your API compatible with a wide range of AI agents without building custom payment gateways.

Verify on-chain transactions before granting access

You cannot rely on the client’s claim that payment was made. In the x402 model, the 402 status code is a request for payment, not proof of it. To secure your API, you must independently verify that the transaction is confirmed on-chain before releasing the data.

This verification process prevents fraud, double-spending, and race conditions. It ensures that your service is compensated for every call. The following steps outline how to implement a robust verification flow.

1
Extract the transaction hash from the request

When a client sends a request with a 402 response, they typically include the transaction hash in the headers or body. This hash is the unique identifier for the payment on the blockchain. If the client fails to provide this hash, reject the request immediately. Do not attempt to verify a payment without a reference point.

2
Query the blockchain for confirmation

Use a blockchain explorer or RPC endpoint to check the status of the transaction hash. You are looking for two things: the transaction status (successful) and the number of block confirmations. For high-value transactions, require more confirmations. For low-value, high-frequency API calls, a single confirmation may suffice, but this increases risk.

3
Validate the recipient address and amount

Ensure the transaction was sent to your specific wallet address. Check that the amount matches the price of the API call exactly. Be aware of token decimals; a payment of 1 USDC is not the same as 1 wei. If the amount is short or the address is wrong, the payment is invalid. Return a 402 response with an error message indicating the discrepancy.

4
Grant access and cache the result

Once the transaction is confirmed, valid, and final, grant the client access to the requested data. To improve performance, cache the verification result for a short period. This prevents you from re-querying the blockchain for every subsequent request from the same client within a short timeframe. However, always re-verify if the cache expires or if the client claims a new payment.

By following these steps, you ensure that your API is secure and that you are paid for every request. Verification is the backbone of the x402 model, turning a simple HTTP status code into a reliable payment system.

Common x402 integration errors

Even with a clear payment flow, implementation details can trip up developers. The most frequent issues usually stem from how the 402 status code is handled or how the payment confirmation is verified. Below are the specific pitfalls to watch for and how to resolve them.

Misusing HTTP 402 Status Codes

The HTTP 402 Payment Required status code is reserved for future use, though x402 leverages it for micropayments. A common error is returning 402 without providing a valid Pay header or payment URI. The client needs a clear path to pay. If you return 402 with no instructions, the request fails without a chance for recovery. Always ensure the response includes the necessary payment details so the client can retry after payment.

Ignoring Payment Confirmation

Another frequent mistake is assuming the payment is complete immediately after the client sends the transaction. In x402, the server must verify the payment on-chain or via the payment layer before granting access. Skipping this step can lead to unauthorized access or race conditions. Use the official Base documentation to implement robust verification logic. This ensures that only confirmed payments allow access to the API endpoint.

Handling Retry Logic Incorrectly

Clients may retry requests multiple times if they receive a 402 error. Without proper idempotency keys or rate limiting, this can lead to duplicate payments or server overload. Implement a mechanism to track pending payments and reject duplicate requests within a short window. This keeps your API clean and prevents financial discrepancies.

Verify your x402 implementation

Before pushing to production, run through this final checklist to ensure your pay-per-API system is robust and secure. A misconfigured x402 endpoint can lead to lost revenue or security vulnerabilities, so precision matters.

Check the 402 Response

Your endpoint must return 402 Payment Required with a valid Payment-URI header when a request is made without payment. This header contains the on-chain payment instructions (usually USDC on Base). If the client doesn't receive this specific status code, the payment flow breaks immediately.

Validate Payment Logic

Ensure your server correctly verifies the on-chain transaction before granting access. Use official documentation from Nansen or Base to confirm your verification logic matches the standard. Never trust client-side claims; always verify the transaction hash on-chain.

Test Post-Payment Access

Once a payment is confirmed, the same request should return 200 OK with the expected data. This idempotency check ensures that users aren't charged repeatedly for the same action. Test this with a real transaction on the testnet first.

  • Endpoint returns 402 with valid Payment-URI
  • On-chain payment verification logic is secure and tested
  • Access is granted (200 OK) only after confirmed payment
  • Idempotency prevents double-charging for the same request

Frequently asked questions about 402