The setup#
Three pieces, none of which costs anything.
A testnet. Base Sepolia is the most commonly supported for x402 work. Check your facilitator's documentation for what it settles on, since coverage differs and this is the constraint.
A facilitator that serves it. The default facilitator at x402.org is testnet-only, deliberately: it exists for development rather than production. That is the fastest way to a working loop.
Test tokens. A testnet stablecoin from a faucet, in the wallet you will pay from. No native token is needed on the buyer side, which is itself worth confirming during the test.
Then run the full exchange: unpaid request, 402, sign, retry with the payment header, verify, serve, settle. The first x402 payment guide walks through it with code.
What should you actually test?#
The happy path is the easy part. These are the branches that matter and the ones most integrations ship without exercising.
| Case | What should happen |
|---|---|
| No payment | 402 with full terms |
| Expired authorisation | 402 again, with fresh terms |
| Wrong amount | Refused, with the reason |
| Payment signed for a different resource | Refused. This is the binding check |
| Same authorisation replayed | Served once, refused thereafter |
| Facilitator unreachable | 503, not a payment error |
| Verify succeeds, settle fails | Decided behaviour, not an exception |
Rows four and five are the ones that catch real bugs, and both correspond to classes of attack published in 2026. Resource binding and nonce tracking is where those two are implemented.
Important
Test the replay case explicitly, by capturing a payment header and sending it twice. A server that serves on verification without recording the payment identity first will serve both times, and nothing in normal operation reveals it.
What do testnets not reproduce?#
1. The EIP-712 domain. Token contracts on testnets can carry different domain separator parameters from their mainnet counterparts. The contract name in the domain is not always the token's display name, and it is not always the same across deployments. A signature built against the wrong domain verifies nowhere, and this is the single most common failure at the mainnet cutover: everything worked yesterday, nothing works today, and the error is an opaque signature rejection.
Check the live domain parameters on each network you deploy to, rather than carrying the testnet values forward.
2. Settlement latency under load. Testnets are empty. Mainnet settlement is slower, more variable, and occasionally much slower. If you chose to serve before settling, your real exposure is the tail of that distribution and the testnet will show you none of it.
3. Facilitator behaviour under pressure. A testnet facilitator serving a handful of developers behaves nothing like a production one under rate limits and congestion. The failure mode to plan for is not an outage, which is alertable, but silent delay: a settlement that lands in twenty minutes on a request that needed an answer in two seconds.
A sensible launch sequence#
- Testnet, full matrix. Every row in the table above, including the failure branches.
- Mainnet, one endpoint, small price. A cent or less, on your least important route. This is where the domain difference surfaces.
- Mainnet, real route, watched. Price something real and watch 402-to-settlement conversion and verify-to-settle failures for a few days.
- Catalogue registration. Only once the above is stable, because a registered entry pointing at a broken endpoint is worse than no entry.
Step 2 exists specifically because of the domain problem. Finding it with a one-cent payment on a route nobody uses is a different experience from finding it when your main endpoint stops taking money.
How do you test the buyer side?#
If you are building a client rather than a seller, the equivalent checks are:
- Pay an endpoint you do not control, so you are not testing your own assumptions twice.
- Confirm your wallet holds no native token and the payment still completes. This is the property that makes the whole thing work for agents and it is easy to accidentally depend on.
- Handle the 402-with-new-terms response, not just the success case.
- Verify the settlement independently by resolving the transaction hash from the receipt header, rather than trusting the seller's 200.
That last one is worth building into the client permanently rather than only in tests. A seller's success response is a claim; the chain is the record.
Frequently asked questions#
Which testnet should I use?#
Whichever your facilitator settles on, which is usually Base Sepolia for EVM work. The choice is constrained by the facilitator rather than by preference.
Can I run my own facilitator for testing?#
Yes, the reference implementation is open source. It is useful if you intend to self-host in production, and unnecessary overhead if you do not.
Do testnet payments appear in indexes?#
Generally not in production indexes, which cover mainnet. Do not expect your testnet activity to show up anywhere a buyer would look.
How do I get testnet stablecoins?#
From a faucet for the network you are on. Availability varies and some faucets are rate limited, which is worth discovering before you plan a test session around them.
What should I check first on mainnet?#
The EIP-712 domain parameters and that a settlement actually lands. Those two cover most of what goes wrong at the cutover, and a one-cent test on a quiet route answers both.
Where to check this yourself#
Schemes and networks lists what Roundhouse's facilitator accepts per network, including testnets, and errors documents the failure responses so you can assert against them rather than guessing. Testing your agent identity covers the buyer-side equivalent.