What the 402 status code enables

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.

The simplest way to use this section is to write down the real constraint first, compare each option against it, and choose the path that still works outside ideal conditions.

Set up the x402 payment server

The first step in building a pay-per-API is installing the payment server. This lightweight application sits between your clients and your data. It intercepts incoming requests, checks for payment, and returns a standard 402 Payment Required response when funds are missing.

The server handles the heavy lifting: validating crypto payments, verifying transaction confirmations, and granting temporary access tokens. By using an existing framework like pay-server, you avoid writing complex blockchain verification logic from scratch. This keeps your main application focused on business logic rather than payment infrastructure.

Pay-Per-API 402
1
Install the payment server
Use Node.js to install the pay-server package. This tool provides a ready-made HTTP server that implements the x402 protocol. Run npm install pay-server in your project directory to get started.
2
Configure your wallet and network
Generate a new wallet address to receive payments. Update the server configuration with your private key and the target blockchain network. The server uses these credentials to verify that incoming payments are sent to your specific address.
3
Set up the payment endpoint
Define the API routes that require payment. The server will automatically return a 402 status code with a JSON body containing payment instructions. This body includes the amount due, the destination address, and the required confirmation count.
4
Test the integration
Send a test request to your endpoint. Confirm that the server responds with the correct 402 error. Once you send a real transaction to the provided address, verify that the server unlocks the endpoint for subsequent requests.

This setup creates a secure gate for your data. Clients must pay before accessing your API, ensuring that your resources are compensated for every call.

Handle the 402 response in your client

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.

Fix common 402 payment errors

Pay-Per-API 402 troubleshooting should start with a clear boundary: what is actually broken, and what still works normally. Check the display, network connection, paired devices, app access, and recent updates before assuming the whole system needs a reset. A small connection failure can make the main screen feel unreliable even when the core system is fine. Work from low-risk checks to deeper resets. Confirm power state, safe parking, account access, and signal first. Then restart the interface, wait for it to reload completely, and test the original symptom. Avoid changing multiple settings at once because that makes it harder to know which step actually fixed the problem. If the issue affects safety information, repeats after every restart, or appears with warning messages, treat the reset as a temporary diagnostic step rather than the final fix. Document the symptom and move to official support instead of stacking more DIY attempts.

The simplest way to use this section is to keep the setup small, verify each change, and record the stable configuration before adding optional accessories.

Verify on-chain payment settlement

Once the client has signed the x402 payment message and broadcasted the transaction, your job isn't done until you confirm the ledger actually reflects it. Unlike standard web requests where a 200 OK is enough, x402 requires proof of settlement. The server must verify that the transaction is included in a block and, depending on your security threshold, that it has reached the required number of confirmations.

Start by monitoring the transaction hash returned by the client. Use a block explorer or a node provider to check the transaction status. If the transaction is pending, wait for it to be included in a block. Once confirmed, verify the recipient address matches your server's wallet and the amount matches the x-paywalled-amount header. This step ensures the client didn't attempt to pay with a different currency or a lower amount.

After confirming the on-chain state, update your server's internal state to mark the resource as unlocked. You can cache this state for a short duration to prevent redundant chain lookups for subsequent requests from the same client. Finally, return the requested data. If the verification fails or the transaction remains unconfirmed after a reasonable timeout, return the 402 status code again, prompting the client to retry or check their wallet balance.

Frequently asked questions about 402