Understand the x402 protocol basics
HTTP 402 was once a theoretical placeholder for "Payment Required," but it is now the foundation for machine-to-machine commerce. The x402 protocol operationalizes this standard, allowing AI agents to negotiate and settle micropayments directly over HTTP. Instead of relying on slow, centralized payment gateways, agents use the 402 status code to signal that a resource is locked behind a payment wall, which the paying agent then resolves.
For infrastructure builders, this shifts the paradigm from subscription-based access to usage-based billing. An API endpoint returns a 402 Payment Required response along with payment instructions. The AI agent, acting as the buyer, processes the payment and retries the request to gain access. This creates a seamless economic layer where every API call can be individually priced and settled.
The x402 specification defines how these transactions are structured, ensuring that both the service provider and the AI agent have a standardized way to communicate value. By adopting x402, you are building infrastructure that supports the emerging economy of autonomous agents, where small, frequent transactions are the norm rather than the exception.
Set up the payment gateway layer
To enable AI agents to pay you directly, you need a blockchain network that supports fast, cheap transactions and a wallet infrastructure to receive them. For Pay-Per-API 402 implementations, Base is the current standard because it offers Ethereum security with minimal gas fees, making microtransactions economically viable.
This section walks you through configuring the network and wallet infrastructure required to accept USDC micropayments. We will focus on the x402 protocol, which allows your API to return a 402 Payment Required status code with a payment instruction, effectively turning your API endpoint into a payment gateway.
Select Base as your primary blockchain. It is an L2 built on Ethereum, optimized for scale and affordability. Most x402 implementations, including recent launches by Stripe and Laevitas, run on Base. This ensures compatibility with existing AI agent wallets like Phantom or Zerion that support ERC-20 tokens on Base.
Generate a new wallet specifically for API revenue. Do not use your personal holding wallet. Use a standard EOA (Externally Owned Account) or a smart contract wallet that can sign transactions. You will need the private key or a secure way to interact with it to verify payments on-chain. Tools like MetaMask or WalletConnect can help manage this.
Obtain USDC (USD Coin) on the Base network. You can bridge USDC from Ethereum mainnet or buy it directly on a Base-compatible exchange. Ensure your wallet holds enough USDC to cover any potential gas fees if you are using a smart contract wallet, though EOAs require no native token balance to receive ERC-20 tokens.
Configure your API to return a 402 Payment Required header with a Payment-URI containing the payment details (amount, token address, recipient address). When an agent calls your API without payment, it receives this 402. The agent then executes the transaction on Base, and your backend verifies the on-chain receipt before returning the data.
As an Amazon Associate, we may earn from qualifying purchases.
Implement the 402 response handler
The x402 protocol relies on a specific handshake: when an AI agent calls your API, you don't just return an error. You return a 402 Payment Required status code accompanied by a structured JSON payload. This payload tells the agent exactly how much to pay, where to send it, and what proof to attach for the next request.
Think of this handler as the toll booth operator who doesn't just say "stop," but hands the driver a ticket with the exact price and the lane number to use. For autonomous agents, this machine-readable instruction is the difference between a failed request and a completed transaction.
Step 1: Define the payment parameters
Before writing the handler logic, you need to determine the cost of the API call. This is usually calculated based on token usage, compute time, or a flat fee per request. You also need to decide on the payment chain (e.g., Solana, Ethereum L2) and the token (e.g., USDC, ETH).
The agent needs to know the chainId, the tokenAddress, and the amount in the smallest unit (wei, lamports, or satoshis). You should also generate a unique nonce for each request to prevent replay attacks. This nonce ensures that a payment for one specific API call cannot be reused for another.
Step 2: Construct the 402 JSON body
The core of the x402 standard is the JSON body returned with the 402 status. This object must include the payment object containing the transaction details. The agent's library will parse this JSON to automatically construct and sign the payment transaction.
Here is the minimal structure your endpoint should return:
{
"payment": {
"chainId": 137,
"tokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
"amount": "1000000",
"nonce": "a1b2c3d4",
"url": "https://api.yourdomain.com/v1/data"
}
}
The url field is critical. It tells the agent which endpoint to call after the payment is confirmed. Without this, the agent doesn't know where to send the request to receive the actual data.
Step 3: Attach the payment proof to the next request
Once the agent pays, it attaches the proof of payment to the header of its next request. Your handler must be ready to verify this proof before returning the 200 OK response. The proof is typically a signature or a transaction hash that can be verified on-chain or via a cryptographic signature.
Your logic should check the X-Payment-Proof header. If the proof is valid and the nonce hasn't been used, grant access. If the proof is missing or invalid, return the 402 response again. This creates a secure, stateless loop where payment and access are tightly coupled.
Step 4: Handle verification edge cases
Not all payments will be instant. Your handler should account for network latency and potential blockchain reorganizations. If you are using a blockchain that requires confirmations, your verification logic should wait for the required number of blocks before marking the nonce as "used." This prevents double-spending attacks where an agent might try to use a pending transaction as proof.
Additionally, implement a short expiration time for the 402 response. If an agent doesn't pay within a few minutes, the nonce should become invalid. This keeps your payment ledger clean and prevents stale payment instructions from cluttering your database.
Step 5: Validate and return the 200 response
Once the proof is verified, return the actual data your API provides. The response should be a standard 200 OK with the JSON payload. Ensure that your API does not leak sensitive information in the 402 response body; only include the payment instructions and the target URL.
Here is a checklist to ensure your handler is robust:
-
Generate a unique, cryptographically secure nonce for each 402 response.
-
Include the correct chainId and tokenAddress for the agent's preferred network.
-
Set the amount in the smallest unit of the token (e.g., wei).
-
Include the url field pointing to the protected resource.
-
Verify the payment proof header before returning 200 OK.
-
Mark the nonce as "used" in your database to prevent replay attacks.
-
Set a timeout for payment completion to keep the ledger clean.
By following these steps, you create a seamless payment layer that allows AI agents to pay for API access automatically. This infrastructure is essential for building sustainable, machine-to-machine commerce models where human intervention is not required for every transaction.
Verify transactions and grant access
Once the AI agent has initiated a payment, your infrastructure needs to confirm the transfer before releasing data. This verification step is the bridge between a promise to pay and actual service delivery. You aren't just checking if the blockchain received funds; you are validating the cryptographic signature to ensure the request came from the entity that paid.
The x402 protocol simplifies this by embedding payment proof directly into the HTTP response. Instead of maintaining a separate database of paid users, your API checks the blockchain for the transaction and the signature header. If both are valid, the data flows.
Use a blockchain indexer or RPC node to watch for the specific transaction hash provided in the request. For USDC payments on BASE, confirm the transaction is finalized. You need to verify that the recipient address matches your API's wallet and that the amount matches the price of the endpoint.
The agent attaches a signature to the request headers. This signature proves the transaction was created by the wallet holding the funds. Verify this signature against the public key associated with the sender. If the signature is missing or invalid, reject the request with a 402 status code, regardless of whether the blockchain shows a pending transfer.
Once the transaction is confirmed and the signature is valid, process the request normally. Return the requested data in the response body. To prevent replay attacks, you may also want to track the transaction hash in a short-term cache to ensure the same payment isn't used to access the data twice.
This flow ensures that access is granted only when payment is cryptographically proven. By relying on the x402 standard, you avoid building complex billing infrastructure from scratch, allowing your API to act as a direct payment gateway for autonomous agents.
Avoid these common 402 implementation mistakes
Building a pay-per-API infrastructure is less about the payment flow itself and more about the edge cases. When autonomous agents handle transactions, they operate at a speed and scale that traditional web apps rarely encounter. A small oversight in your logic can lead to lost revenue or, worse, security vulnerabilities. Here are the critical pitfalls to watch for during your x402 integration.
Insecure nonce handling
The nonce in an x402 response is not just a random string; it is the primary defense against replay attacks. If you generate nonces that are predictable, sequential, or reused across sessions, an attacker can intercept a valid payment response and replay it to gain unauthorized access to your API multiple times without paying again.
Ignoring failed transaction states
Agents are persistent processes, but network connections are not. If an agent sends a payment request but the connection drops before it receives the signed response, the agent will typically retry. If your server does not handle this idempotently, you risk double-charging the agent or, conversely, failing to record the payment due to race conditions.
Always design your endpoint to be idempotent. If a request with a specific nonce and amount arrives, check if that payment has already been processed. If it has, return the cached response immediately. If it hasn't, process it and store the result. This ensures that network hiccups don't break the trust model between your API and the consuming agents.
Hardcoding API keys in agent prompts
A common mistake is embedding your secret API keys or payment verification keys directly into the agent's system prompt or configuration. This exposes your credentials to anyone who can access the agent's logs or memory. Instead, use environment variables or a secure secret management service to inject these keys at runtime.
Not validating the signature
Finally, never trust the content of the x402 response without validating the cryptographic signature. The response contains the proof of payment, but if the signature is not verified against the public key associated with the agent's wallet, the data is meaningless. Use a library that supports the specific signature scheme defined in the x402 spec to ensure integrity.
No comments yet. Be the first to share your thoughts!