x402 on Testnet (Base Sepolia)
Develop and debug x402 for free. Base Sepolia mirrors mainnet exactly — only the network value differs.
How do I test x402 for free?
Set network to "base-sepolia" instead of "base" in your route config, then fund a throwaway wallet with free Base Sepolia ETH and test USDC from a faucet. The full 402 → pay → 200 flow behaves exactly like mainnet, so you can build and debug with zero real money at risk — then switch network to "base" and use a real wallet when you go live.
In your route config set network to "base-sepolia" instead of "base". Everything else stays the same.
Create a throwaway wallet (e.g. with viem or your wallet app). You only need its address on the server side to receive; the payer needs its private key.
Get free Base Sepolia ETH (for gas) and test USDC from public faucets. No real money is involved.
Call the endpoint with no payment to see the 402, then pay with an x402 client and get the 200. Identical to mainnet.
When it works, change network to "base" and use a real receiving wallet. Nothing else changes.
Testnet vs. mainnet, side by side
The only thing that changes
// Same code, testnet network — no real money
import { paymentMiddleware } from "@x402/express";
app.use(
paymentMiddleware(
"0xYourTestWalletAddress",
{
"GET /weather": {
price: "$0.01",
network: "base-sepolia", // <-- testnet
},
},
{ url: "https://x402.org/facilitator" }
)
);Full build walkthrough in the x402 tutorial.
Troubleshooting
Why: The client is signing a payment for a different network than the server expects (client on "base", server on "base-sepolia", or vice versa).
Fix: Log the raw 402 body’s network field and make sure the client’s configured network matches it exactly before it signs anything.
Why: Testnet faucets can take a minute or two to confirm, and some are rate-limited per IP/wallet for a day.
Fix: Wait ~60-90 seconds and re-check the balance on a Base Sepolia block explorer before assuming the faucet failed; try a second faucet if the first is rate-limited.
Why: USDC pays the invoice, but the wallet still needs a small amount of Base Sepolia ETH to cover the gas fee for the settlement transaction.
Fix: Fund the same address with test ETH from a Base Sepolia faucet, separate from the USDC faucet.
Why: The most common cause is forgetting to swap the receiving wallet address along with the network — a test wallet has no way to receive real USDC.
Fix: Treat "network" and "payTo address" as a pair you change together, not just the network string.
Frequently asked questions
How do I test x402 without spending real money?
Run on a testnet. Set the route’s network to "base-sepolia", fund a test wallet from free Base Sepolia faucets (ETH for gas and test USDC), and exercise the full flow — the 402 challenge, payment, retry, and 200 response work exactly like mainnet. Switch network to "base" only when you go live.
What network does x402 use for testing?
Base Sepolia is the standard testnet for x402 development. It mirrors Base mainnet behavior but uses valueless test tokens, so you can build and debug for free. The only change between testnet and production is setting network to "base-sepolia" versus "base".
Where do I get test USDC for x402?
From public Base Sepolia faucets. You’ll want a small amount of Base Sepolia ETH for gas and test USDC to make payments. Search for the official Base/Coinbase Sepolia faucet and a USDC testnet faucet; fund the wallet you’ll pay from.
Do I change my code to go from testnet to mainnet?
Almost nothing — just change the network value from "base-sepolia" to "base" and use a real receiving wallet (and real USDC on the payer side). Your route handlers, middleware setup, and client logic stay the same.
Can I use a hosted facilitator on testnet?
Yes. Hosted facilitators support testnets, so you can point the middleware at the same facilitator URL and just set the testnet network. That means you can test the complete end-to-end settlement flow without running any blockchain infrastructure yourself.
Why does my 402 test loop forever without ever paying?
Almost always a network mismatch between client and server, or a client account with test USDC but no test ETH for gas. Log the 402 body’s network field and confirm both the client config and the funded wallet match it — see the troubleshooting table above.
Is there a testnet for x402 on Solana?
Yes — if you’re building on Solana rather than Base, use Solana’s devnet with its own faucets instead of Base Sepolia. The same principle applies: test on a free network first, then switch to Solana mainnet for real settlement. See our x402 on Solana guide.
Next: full tutorial · facilitators · x402 on Solana