What do you decide before writing any code?#
1. Decide what one call is. Your unit of sale has to be a thing a buyer wants exactly one of. If your value comes from a session or an accumulated corpus, per-call pricing fits badly and you should know that before building for it.
2. Pick the chain and asset together. They are a pair, not two choices. The pair has to support gasless authorisation or the whole design collapses for your buyers. Which chains support x402 and stablecoin choice cover the constraint.
3. Pick a facilitator that covers that pair. Coverage differs and this constrains you more than most people expect. Check before building, not after.
4. Set a price. From your cost per call, checked against comparable endpoints. Pricing for agents covers the method and the units trap.
The integration#
5. Return a real 402. Full terms in the accepts array: scheme, network, asset, amount in smallest units, payTo, resource, timeout. A bare 402 with no body is unusable by anything.
6. Verify before you work. Call your facilitator's verify before doing anything expensive. This is what stops an attacker spending your compute with an invalid authorisation.
7. Bind the payment to the resource. Check that the authorisation was signed for this endpoint, this amount, this asset, this payee. A payment valid in isolation but signed for something else is not payment for this, and a server that skips this check can be made to serve expensive endpoints at cheap prices.
8. Track nonces before serving. Record the payment identity before releasing the resource. Security work in 2026 found implementations where one authorisation could unlock a resource repeatedly because the server released it on verification without recording anything. The known attacks covers the class and testing the replay case is how you confirm it.
9. Decide your serve-and-settle order. Settle then serve is safe and slower. Serve then settle is faster and you will lose a small number of payments. Pick deliberately and know your loss rate rather than discovering it.
Important
Steps 7 and 8 are the two that are skipped most often and the two that cost money when skipped. Both are cheap to implement at build time and awkward to retrofit once you have traffic.
What makes the endpoint findable?#
10. Keep a free path open. A schema endpoint, a health check and a short description, unpaid. A buyer that cannot see your interface without paying usually will not pay. This costs you nothing and is the single highest-conversion thing on this list.
11. Register with catalogues. More than one. Check that the payTo you register matches your live 402, because drift between them is common and the live response is what a buyer pays. Catalogue coverage is uneven enough that one registration leaves most buyers unable to find you.
12. Publish your declarations. An OpenAPI document and an x402 declaration at predictable paths. Which well-known files covers what is read and the status-code trap in serving them.
After launch#
Three things to watch, none of which is revenue.
402-to-settlement conversion. The proportion of 402s that come back paid. A low rate is a price, latency or terms problem, and which one it is shows in whether the same clients retry.
Settlement failures after verification. Payments that verified and did not settle. A rising rate usually means your facilitator is struggling or your validity windows are too long.
Your public record. Your receiving address accumulates a history that buyers read when deciding whether to try you. Check what it looks like from outside, because that is the view they get. Auditing a service's traffic is the buyer's side of it.
What to skip#
A few things that feel necessary and are not.
- A wallet of your own to run. The facilitator settles directly to your address. You do not need to operate on-chain infrastructure to take on-chain payments.
- Identity for your buyers. You get a wallet address. Trying to resolve it to a company is work that mostly fails and buys little.
- Refund machinery. There is no reversal. If refunds are routine in your business, that is an argument for keys and invoices rather than for building a refund path on top of a final settlement.
- Supporting every chain on day one. Start with one pair, add a second when a buyer asks or when you can see demand.
Frequently asked questions#
How long does the integration take?#
For an existing API, typically a day or two: a 402 response, two facilitator calls, nonce tracking and the binding check. Charge for your API walks through it.
Do I have to drop my API keys?#
No, and you should not. Keys serve buyers who integrate deliberately. The strong pattern is to let a payment mint a key, so an anonymous buyer becomes a known one with no form in between.
What if my endpoint is already behind a gateway?#
Most gateways can return a 402 with a custom body and inspect a request header, which is all this needs. The facilitator calls happen in your service rather than at the edge.
How do I handle a buyer who pays and then gets an error?#
Decide in advance and document it. Either settle only on success, which costs latency, or refund by sending a payment back, which costs you the gas. Silence is the option that damages your record.
Should I rate limit paid callers?#
Lightly, for abuse rather than for economics. Every request is prepaid, so volumetric abuse is self-limiting in a way it never is behind a free tier. Rate limiting an agent buyer covers the three limits still worth having.
Where to check this yourself#
/services shows how your endpoint appears once catalogues and host probing have picked it up, including the terms recorded against it. If those terms disagree with your live 402, that is the discrepancy a buyer hits. /transactions shows the settlements arriving at your address.