How do I test x402 on a testnet, without spending real money?
Short answer
Use a test network. Base Sepolia and Solana Devnet are copies of real blockchains where tokens have no value. Get free test USDC from a faucet, point your server at the public test facilitator at x402.org, and run the full flow of request, 402, payment and result. When it works, switch the network and the facilitator to go live.
What you need
| Piece | For testing |
|---|---|
| Network | Base Sepolia (eip155:84532), or Solana Devnet |
| Token | Test USDC, which is free and worth nothing |
| Facilitator | https://x402.org/facilitator, the public test facilitator |
| Wallets | Two: one to pay, one to receive. Make new ones for testing |
Step by step
1. Make a test wallet
Create a new wallet and use it only for testing. Do not reuse a wallet that holds real funds. A test setup is where keys most often end up in a file or a log by accident.
2. Get test USDC
Circle runs a public faucet at faucet.circle.com. Choose USDC and your test network, paste your wallet address, and it sends test tokens. At the time of review the faucet states that it gives 20 USDC per request, once every two hours per address and network, with no account required.
That is enough for thousands of test payments at typical x402 prices.
3. Run a paid endpoint
Follow the server example in how to accept x402 payments. It already uses Base Sepolia and the test facilitator. Set payTo to your receiving wallet's address.
4. Look at the 402
Before paying, check that the server is asking for what you expect. Call the endpoint with no payment and read the PAYMENT-REQUIRED header, or paste the address into the 402 checker. The checker flags offers on test networks so you can tell a demo from a live service.
5. Pay it
Use the client example in how to pay an x402 API with your test wallet's key. A successful run returns your handler's response, with a PAYMENT-RESPONSE header carrying the transaction reference. You can look that transaction up on a block explorer for the test network.
Things worth testing on purpose
- An empty wallet. Confirm your client reports a clear error instead of hanging.
- A wrong network. Fund the wallet on one network and ask it to pay on another.
- An expired payment. Sign, wait past the timeout, then send.
- A handler that throws. Check that the buyer is not charged when your code fails.
- A browser client. The payment headers are hidden from browser code unless you expose them. See the list of things that go wrong in how to accept x402 payments.
The messages you will see are explained in x402 error codes.
Going live
The x402 FAQ answers why a setup that worked on Base Sepolia can fail on Base. The changes are:
- Network. Change
eip155:84532toeip155:8453. - Facilitator. The x402.org facilitator "does not support Base mainnet". Pick a production one from the facilitator directory.
- Token. The buyer needs real USDC on the real network. Test USDC is a different token.
- Wallets. Use a new receiving address that you control and have backed up.
Then run one real payment of a fraction of a cent before announcing anything.
A warning sign
A public endpoint that only offers test networks is a demo. If a service claims to be live but its 402 reply lists only Base Sepolia or Solana Devnet, no real payment can be made to it.
Sources
Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.
Related questions
Who writes this. Ask402 is published by Havok Holdings LLC, which also runs Agent402, one of the x402 services covered here. Agent402 is labelled wherever it appears. Everything else is described from each project’s own documentation, and nobody pays to be listed.