What are you actually adding?#
Four pieces, in the request path of your priced routes.
- A 402 branch. No valid payment, return 402 with terms.
- A verify call. Payment present, ask a facilitator whether it is valid before doing anything expensive.
- A binding check. Confirm the payment was signed for this resource, amount, asset and payee.
- A settle call. Put it on-chain and return the receipt header.
That is the whole integration. For most APIs it is a middleware and a configuration table of routes to prices.
The three decisions to make first#
These are hard to change once buyers depend on them.
What is a resource? The resource field binds a payment to what it buys. If your price varies by query parameter, the resource identity has to include the parameters, or a buyer pays the cheap price and calls the expensive path. If it does not vary, including them makes every distinct query a separate unpayable resource.
Serve then settle, or settle then serve? Settling first is safe and adds a block of latency. Serving first is faster and loses you a small number of payments that verified and never settled. Both are legitimate; the mistake is not deciding, then discovering the loss rate in production.
Which routes are priced? Resist pricing everything. A free schema endpoint, a health check and a cheap sample call are what let a buyer evaluate you, and a buyer that cannot see your interface without paying usually does not pay.
Which two checks get skipped most often?#
Both were found in real implementations by security researchers in 2026, and both are cheap at build time.
Resource binding. A payment is a signed authorisation for an amount to an address. Without checking the resource field, a payment signed for your cheapest endpoint is a valid payment for your most expensive one. The check is a string comparison and skipping it is a pricing bypass.
Nonce tracking before serving. The on-chain nonce prevents double-spend after settlement, not before it. A server that releases its resource on verification alone, without recording the payment identity first, can be made to release it repeatedly under one authorisation. Record then serve, in that order, atomically.
Warning
Both of these are invisible in normal operation. Your tests pass, your buyers pay, your revenue looks right. They surface when somebody looks for them, which in a public protocol with published attack research is a matter of time rather than luck.
Fitting it to what you already have#
You have API keys. Keep them. Add x402 as a second path and connect the two: let a payment mint a key, so an anonymous buyer becomes a known one with no form. Keys against x402 covers the pairing.
You have a gateway. Most gateways can return a 402 with a custom body and read a request header, which is all the edge needs to do. The facilitator calls belong in your service, because they need your route-to-price mapping.
You have rate limits. Keep them, loosen them for paid calls. Prepaid requests are self-limiting in a way free ones are not, so the limit you need is for abuse rather than for economics.
You have an OpenAPI document. Publish which routes are priced in it. An agent reading your spec should be able to tell what costs money before it calls.
What to watch after launch#
402-to-settlement conversion. How many 402s come back paid. Low means price, latency or terms, and which one shows in whether the same clients retry with different terms or not at all.
Verify-to-settle failures. Payments that verified and did not settle. A rising rate usually means long validity windows or a struggling facilitator.
Settlement latency. How long settle takes, at the tail rather than the median. The tail is what your serve-order decision actually costs you.
How much work is it really?#
For a typical API: a day or two for the integration, plus whatever your deploy and test cycle costs. The facilitator does the hard parts, your wallet is just an address, and you never touch an RPC endpoint.
The larger cost is operational rather than engineering. You now have a second revenue path with its own reconciliation, its own failure modes and its own support questions, and that cost is ongoing. The publishing checklist covers the rest of what launching it involves.
Frequently asked questions#
Do I need a wallet?#
An address to receive at, not a wallet to operate. The facilitator settles directly to it and you never sign anything. Use an address you control and can account for.
Can I test without real money?#
Yes, on testnets. The default facilitator at x402.org is testnet-only for exactly this. Note that testnet token contracts can have different EIP-712 domain parameters from mainnet, which catches people at the cutover.
What happens if my facilitator is down?#
Verification fails, so you cannot safely serve. Returning a clear 503 is better than serving unpaid or refusing with a payment error, since the caller's payment was not the problem.
How do I price routes that already have plan-based pricing?#
Above your plan's effective per-call rate. Matching it gives committed buyers a reason to leave the plan, which cannibalises predictable revenue for nothing.
Will this bring me traffic by itself?#
No. The integration makes you payable; catalogues, declarations and a settlement history make you findable. Making your API discoverable is the other half and it is the half that takes longer.
Where to check this yourself#
Charge for your API is the step-by-step version with code, and the anatomy of a payment documents the exchange including the failure branches. Once you are live, /transactions shows the settlements arriving at your address from outside your own logs.