The Pay-Per-API 402 Guide: Infrastructure and Strategy

What the 402 status code means

The HTTP 402 Payment Required status code is a reserved response code that signals a client must complete a payment before the server will fulfill the request. For decades, it sat dormant in the HTTP/1.1 specification, officially listed as "reserved for future use" by the IETF. Today, it is waking up as the standard handshake for machine-to-machine (M2M) payments and agentic commerce.

It is crucial to distinguish 402 from 403 Forbidden. When a server returns a 403, it is denying access based on identity or permissions—essentially saying, "You are not allowed here." A 402, however, indicates that access is granted, but the transaction has not yet been settled. The server is saying, "You are allowed, but you need to pay first."

In the context of API infrastructure, this distinction changes how bots and microservices handle authentication. Instead of failing silently or triggering complex fallback logic for unpaid requests, an agent can programmatically detect the 402 status, initiate a payment flow, and retry the request. This creates a clean, automated loop for billing without requiring manual intervention or separate payment gateways for every API call.

This approach shifts the burden of payment verification from the application layer to the protocol layer. For developers building autonomous agents or high-volume API services, adopting 402 means aligning with a native HTTP standard rather than inventing custom error codes for billing failures.

How x402 enables micropayments

The x402 protocol turns the HTTP 402 status code into a machine-readable payment instruction. Instead of a generic error message, the server returns a signed payload that tells the client exactly how much to pay and how to pay it. This design allows software to handle transactions automatically, without human intervention.

The Challenge-Response Cycle

The interaction follows a strict challenge-response pattern. When a client requests a paid endpoint, the server does not return the data. Instead, it sends back an HTTP 402 response containing a cryptographic challenge.

1. The Server Sends a Challenge: The response includes a Paywall header or body with a signed payment requirement. This payload contains the price, the accepted currencies, and a unique nonce to prevent replay attacks.
2. The Client Signs the Payment: The client software reads the challenge, constructs a payment transaction using its configured wallet, and signs it with the user’s private key. The signature proves the client has the funds and authorizes the transfer.
3. The Client Returns the Proof: The client resends the original request, attaching the signed payment proof in a new header (typically Authorization: Paywall <signature>).
4. The Server Verifies and Delivers: The server checks the signature against the original challenge. If valid, it processes the request and returns the API data.

This cycle ensures that every API call is backed by a verifiable transaction. The server never releases data until the cryptographic proof of payment is validated.

Why This Matters for Developers

For Web3 developers, x402 removes the need for external payment gateways or subscription management services. The payment logic is embedded directly in the HTTP protocol. This reduces infrastructure complexity and allows for granular, per-request billing.

The protocol is native to HTTP, meaning it works with existing HTTP clients and servers. You do not need a custom protocol layer. The challenge-response mechanism is secure because the nonce binds the payment to the specific request, preventing reuse of old signatures.

By integrating x402, you enable a new model of API monetization where access is granted instantly upon payment verification. This opens up possibilities for metered billing, pay-per-use models, and decentralized API marketplaces.

Step-by-step integration workflow

The Pay-Per-API 402 works best as a sequence, not a scramble through settings. Do the minimum first: confirm compatibility, connect the core hardware, update only when needed, and test the result before adding optional features. That order keeps the task understandable and makes failures easier to isolate. After each step, pause long enough for the interface to finish syncing. Many setup problems are timing problems disguised as configuration problems. If the same step fails twice, record the exact error, restart the smallest affected piece, and retry before moving deeper.

1

Confirm prerequisites

Check compatibility, account access, firmware, network, and physical access before changing the The Pay-Per-API 402 setup.

2

Make one change at a time

Apply the setup steps in order so any connection, pairing, or permission failure is easy to isolate.

3

Verify the result

Test the final state from the app and from the physical device before adding automations or optional settings.

Previous

123

Next

Subscription vs. pay-per-request: the wei-to-token math

When building an agentic workflow, you need to know whether a single API call costs a fraction of a cent or a significant chunk of your budget. The difference between a flat subscription and pay-per-request isn't just billing; it's about how you calculate costs in wei-to-token terms.

A subscription model acts like a monthly retainer. You pay a fixed amount regardless of usage. This is predictable but often inefficient for sporadic or low-volume tasks. You might pay for capacity you never use. In contrast, pay-per-request scales with your actual load. You only pay for what you call. This is essential for high-frequency APIs where costs can spike unpredictably.

The calculation behind the cost

The core of the 402 standard is the wei-to-token calculation. Before a request is processed, the cost is determined in wei (the smallest unit of an ERC-20 token). This amount is then converted to the token's base unit for the final charge.

For high-frequency APIs, this math must be precise. A small error in the conversion rate or gas estimation can turn a profitable service into a loss leader. You need to account for:

• Base fee: The cost per request in wei.
• Gas overhead: The transaction fee for the payment.
• Conversion rate: The current token price at the time of the call.

Break-even points

The break-even point is where the cost of a subscription equals the cost of pay-per-request. If your API usage is low, pay-per-request is almost always cheaper. If usage is high and consistent, a subscription might offer a discount.

For agentic workflows, usage is rarely consistent. Agents may idle for hours, then burst with hundreds of requests. This volatility makes pay-per-request the safer default. It eliminates the risk of overpaying for unused capacity.

Side-by-side comparison

Choose the model that matches your agent's behavior. For most 402-based workflows, pay-per-request offers the flexibility needed for dynamic, event-driven tasks.

Common integration errors and fixes

Even with a solid strategy, the handshake between your client and the API provider can stumble. These errors usually stem from configuration oversights rather than fundamental flaws in your approach. Below are the most frequent failure modes and how to resolve them quickly.

Signature verification timeouts

Cryptographic signatures are sensitive to system clock drift. If your server’s time is more than a few seconds off from the API provider’s, the signature verification will fail, often returning a 401 or 403 instead of the expected 402. This is particularly common in containerized environments where the host time might not sync correctly.

Ensure your application server uses Network Time Protocol (NTP) synchronization. If you are using a third-party authentication library, check its documentation for clock skew tolerance settings. A simple date command in your terminal can verify if your local time is accurate before retrying the request.

Incorrect payload formatting

APIs enforcing 402 responses often require strict payload structures, including specific headers like Content-Type: application/json or signed body hashes. Sending a raw string or an unformatted object will cause the payment gateway to reject the request before it even checks your balance.

Use a standardized HTTP client or SDK provided by the API vendor. These tools handle serialization and header injection automatically. If you must build a custom client, validate your payload against the provider’s schema documentation before sending. Always log the raw request body in a debug environment to catch formatting issues without exposing sensitive data.

Missing billing onboarding

Some APIs, such as Microsoft Graph, return a 402 if the application has not completed the billing onboarding process, even if you have configured the correct credentials. This is a provisioning issue, not a code error.

Check your provider’s developer portal to ensure your subscription is active and linked to a valid payment method. For enterprise APIs, verify with your account manager that the billing entity is correctly associated with your API key. Skipping this step is a common oversight when moving from sandbox to production.

Pre-launch verification checklist

Before you flip the switch on your pay-per-API 402 implementation, run through this audit. A single misconfigured header or unchecked edge case can break the payment flow or expose your endpoints to free usage.

• Signature validation: Ensure your middleware strictly verifies the cryptographic signature attached to the payment proof. Reject any requests where the signature doesn't match the transaction hash.
• Gas estimation: Verify that your client-side gas estimation logic accounts for current network congestion. Underestimating gas is the most common reason for failed payment transactions.
• Error handling: Test your fallback mechanisms. When a 402 Payment Required response is returned, does your client correctly parse the Pay header and guide the user to complete the payment?
• Rate limiting: Implement rate limits on your payment verification endpoint to prevent denial-of-service attacks while users are in the process of paying.

If these checks pass, you're ready to go live.

Frequently asked: what to check next