Pay-Per-API 402 Guide: Build and Test x402 Endpoints

What the 402 status code means for agents

The HTTP 402 Payment Required status code is the handshake that turns an API call into a transaction. It tells the client: "I have the data you want, but you need to pay me before I release it." This is the foundation of agentic micropayments, but it is not the same 402 most developers remember from the early web.

For years, 402 was a ghost. The IETF reserved it in RFC 7231, but browsers and servers ignored it because no standard payment gateway supported it. Most developers never saw it. When they did, it was often a generic error catch-all for failed payment gateways, as noted by MDN Web Docs.

x402 changes that. It treats the HTTP status code as a smart contract trigger. Instead of checking a database for a user's subscription status, the server checks for a signed payment. If the payment isn't there, it returns 402. If it is, it returns the data. This shift moves payment from the background (billing cycles, accounts) to the foreground (the request itself).

This distinction matters because it changes how agents interact with the web. Agents don't have credit cards or login sessions. They have private keys and wallets. The 402 code is the only standard HTTP response that allows an agent to pay and receive data in a single, atomic step. It turns every API endpoint into a potential payment point.

As SatGate notes, this enables "APIs charge per call at the moment of use." There are no subscriptions. No invoices. Just a request, a payment, and a response. This is what makes 402 the backbone of the agentic economy.

Set up the x402 payment middleware

Pay-Per-API 402 works best when the purchase path is explicit. Verify the source, compare the offer against real alternatives, check the total cost, and confirm what happens after payment before you decide. After each comparison, write down the one risk that would change your mind. If the seller, condition, support, warranty, shipping, or upkeep still feels uncertain, resolve that question before moving to checkout.

Handle client-side payment verification

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.

1

Define the constraint

Name the space, budget, timing, or skill limit that shapes the Pay-Per-API 402 decision.

2

Compare realistic options

Use the same criteria for each option so the tradeoff is visible.

3

Choose the practical path

Pick the option that still works after cost, maintenance, and fallback needs are included.

Previous

123

Next

x402 vs. subscription models

Choosing between pay-per-API 402 and traditional subscriptions depends on your user base and cash flow needs. Subscriptions offer predictable revenue but introduce friction: users must create accounts, enter payment details, and manage renewals. x402 removes this barrier by handling payments at the moment of use.

With x402, there are no accounts, no invoices, and no billing cycles. Access is granted immediately after payment, making it ideal for sporadic or unpredictable usage. This model aligns cost directly with value, which often converts better for new or trial users who hesitate to commit to a recurring plan.

For developers, x402 simplifies the stack by embedding payment logic into the HTTP response code itself. For users, it eliminates the fear of forgotten charges. Use subscriptions for steady, high-retention services, and x402 for flexible, low-friction access.

Debug common x402 integration errors

Even with a working payment flow, x402 endpoints often fail during integration due to strict signature verification rules or payload formatting mismatches. Since the 402 status code is not standardized in the same way as 404 or 200, browsers and agents may interpret responses differently depending on how the response body is structured.

Start by verifying the HTTP status code. MetaMask agents expect a strict 402 Payment Required status. If your server returns 200 OK with a payment request in the body, the agent will likely treat it as a successful API call rather than a payment gate, causing the transaction to hang or fail silently. Ensure your middleware explicitly sets the status code before sending any response body.

Next, check the signature verification logic. The x402 protocol relies on the agent signing a specific payload. If your server rejects the signature, it is usually because the payload being signed does not match exactly what the server expects. This often happens when the request body is modified by a logger, middleware, or compression layer before verification. Ensure the raw body is preserved for signature checks.

Finally, validate the payload format. The payment request must include valid transaction details, including the correct chain ID and recipient address. If the payload is malformed or missing required fields, the agent will not generate a signature. Use a tool like Postman or a simple Python script to manually construct and send a test request with a valid signature to isolate whether the issue lies in your server logic or the client-side agent configuration.

Finalize your API with a verification checklist

Before you expose your x402 endpoint to the public, run through this checklist to ensure your implementation is secure and compliant. A single misconfigured header can break payment flows or expose your backend to abuse.

• Verify Pay header parsing: Ensure your server correctly extracts and validates the Pay header from incoming requests. If the header is missing or malformed, the endpoint must return a 402 Payment Required status code with a valid Pay-Allowed header.
• Check Pay-Allowed syntax: Your 402 response must include a Pay-Allowed header containing a valid x402 payment URI. Test this with a tool like curl to confirm the URI is parseable and the payment instructions are clear.
• Validate signature verification: If you are using signed payments, ensure your backend verifies the cryptographic signature against the payment URI. Reject any requests with invalid or expired signatures.
• Test idempotency: Verify that duplicate payment requests do not result in duplicate charges or data corruption. Implement idempotency keys if your logic supports it.
• Review rate limiting: Protect your endpoint from denial-of-service attacks by implementing rate limiting based on IP address or payment signature.

Once these checks pass, your x402 API is ready for production. Remember to monitor your logs for any unusual payment patterns or failed verification attempts.

Frequently asked questions about x402

What is HTTP 402 Payment Required?

The 402 status code signals that a server requires payment before fulfilling a request. While originally intended for digital payment systems, it is now rarely used in standard web traffic. Instead, it serves as a specific indicator for x402 endpoints, where the server rejects the request until a crypto payment is verified.

How do I fix a 402 error in x402?

Unlike typical web errors, a 402 in x402 is a feature, not a bug. To resolve it, you must attach a valid proof of payment (PoP) to your request headers. If you are testing, ensure your wallet has sufficient funds and that your signature matches the expected payload. Check MDN’s documentation for standard 402 behaviors to distinguish them from x402-specific requirements.

Can I use 402 for non-crypto payments?

Technically, yes, but it is not recommended. The 402 code lacks standardized handling for traditional payment gateways like Stripe or PayPal. For fiat transactions, use 401 (Unauthorized) or 403 (Forbidden) to gate access, and reserve 402 specifically for the x402 protocol’s on-chain verification flow.