Set up the payment endpoint

Build a Pay-Per-API 402 Service 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.

The Pay-Per-API 402
1
Confirm prerequisites
Check compatibility, account access, firmware, network, and physical access before changing the Build a Pay-Per-API 402 Service 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.

Verify the on-chain payment

Before returning any data, your server must confirm that the client’s transaction is real and complete. The x402 protocol uses the HTTP 402 Payment Required status code to trigger this exchange, but the server is responsible for the final validation. You cannot trust the transaction hash alone; you must verify the settlement on the blockchain.

1
Extract transaction details from the request

When a client sends a payment, it includes the transaction hash and the blockchain network in the request headers or body. Your server needs to parse these fields to identify which chain to query. This metadata tells your verification logic where to look for the proof of payment.

2
Query the blockchain for confirmation

Use a blockchain explorer API or a node client to check the status of the provided transaction hash. Look for the specific from address (the payer) and the to address (your payment wallet). Verify that the amount sent matches or exceeds the price defined in your API’s pricing logic.

3
Wait for sufficient block confirmations

A single block confirmation is often insufficient for high-value or high-risk transactions. Implement a check that waits for a specific number of confirmations (e.g., 12 for Ethereum, or fewer for faster chains) to ensure the transaction is irreversible. This step prevents double-spending attacks where a transaction might be reverted.

4
Return the protected resource

Once the transaction is confirmed, your server should release the requested data. You can do this by sending a 200 OK response with the payload, or by issuing a short-lived access token that the client can use for subsequent requests. Log the transaction hash for auditing purposes.

This verification step is the core of the pay-per-API model. By handling the logic server-side, you ensure that only verified payments unlock your resources, maintaining the integrity of the x402 standard.

Choose the right network for fees

Build a Pay-Per-API 402 Service 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.

FactorWhat to checkWhy it matters
FitMatch the option to the primary use case.A good deal still fails if it does not fit the job.
ConditionVerify age, wear, and service history.Hidden condition issues erase upfront savings.
CostCompare purchase price with likely upkeep.The cheapest option is not always the lowest-cost option.

Debug common integration errors

Even with a solid architecture, HTTP 402 implementations often fail at the handshake level. The protocol is still emerging, and most client libraries expect standard 200/401/403 responses. When a server returns 402, the client must explicitly handle the payment challenge. If your integration is breaking, check these three common failure points first.

Missing or malformed headers

The 402 response must include specific headers to tell the client how to pay. The Payment header (defined in the x402 specification) contains the payment URI and required parameters. If this header is missing, the client cannot initiate the transaction. Similarly, the Retry-After header helps manage rate limits during payment processing. Ensure your server is returning these headers exactly as specified in the MDN documentation. A single typo in the header name can cause the entire integration to fail silently.

Invalid signatures

Security is the main reason 402 was designed for high-value transactions. Your server must verify the cryptographic signature of the payment proof before releasing the API key or data. If the signature validation fails, the server should return a 402 with a clear error message indicating which part of the proof was invalid. Do not return a generic 500 error, as this masks the real issue. Use a consistent error structure that includes the expected signature format and the actual value received. This helps developers debug their client-side signing logic quickly.

Client library compatibility

Most standard HTTP clients (like fetch or axios) do not automatically handle 402 responses. They may treat them as errors and throw exceptions before your payment logic runs. You need to explicitly intercept 402 responses in your client code. Check the response status code before parsing the body. If it is 402, extract the Payment header and trigger your payment flow. If your library throws an error on any non-2xx status, you must configure it to allow 402 responses to pass through to your handler.

Verify your implementation

Before you send traffic to production, run through this checklist to ensure your 402 endpoints behave correctly. The x402 protocol relies on strict adherence to HTTP semantics, so even minor deviations in header structure or payment proof validation can break machine-to-machine integrations.

Use this guide to audit your service against the standard expectations for 402 Payment Required responses.

  • Check 402 Headers: Ensure your server returns 402 Payment Required with a valid Pay header containing the payment URI and required metadata.
  • Validate Payment Signature: Verify that the Pay-Proof header is cryptographically signed and matches the expected payment method (e.g., Bitcoin, Lightning).
  • Test Resource Delivery: Confirm that the protected resource is delivered only after the payment proof is successfully verified and the signature is accepted.
  • Handle Edge Cases: Test how your server responds to malformed proofs, expired signatures, or unsupported payment methods to ensure graceful error handling.
The Pay-Per-API 402

Frequently asked: what to check next