Guide · Developers · 2026

How to test an x402 endpoint

If your paid API is broken, the 402 response usually tells you why. The trick is knowing how to read it. Here is a quick way to test an endpoint and spot the common problems.

The basic test

Send a plain request with no payment and look at what comes back:

curl -i https://your-api.example/api/premium

A healthy x402 endpoint answers with:

Status 402, not 200
Readable payment details in the body
A clear price
A valid payTo address
The correct network

How to read the response

When it is not 402, the status code is a clue:

200: the payment middleware is not applied. The route is open to everyone.
401 or 403: auth blocked the request before payment ran. Check your middleware order.
404: wrong URL. The route does not exist where you think.
402 with an empty or partial body: the setup is incomplete. The challenge is missing required fields.
Wrong address format: a wallet or chain is misconfigured, for example an Ethereum-style 0x address in a Solana field.

Use a checker

Reading the raw response by hand gets old fast. Paste your public HTTPS URL into the 402 Checker. It fetches the endpoint once and grades the shape of the 402, so you can see exactly which fields are missing or wrong. Want a known-good example to compare against? This site's own donate endpoint at /api/x402/donate is a live 402 you can run through it.

After a real payment

Once payment works, test the retry: call the same URL again with the payment proof attached, and confirm you get a 200 with the resource. Then try reusing the same proof a second time. If replay protection is working, the reused proof should be rejected. That check matters, because it is what stops one payment from unlocking a resource forever.

Test on Devnet first

Do all of this on Devnet until the path is boring and predictable. Then switch the Mainnet settings on purpose, one at a time, rather than discovering a misconfiguration with real money on the line.

Open the 402 Checker Build an x402 API on Solana Generate starter code

Ship x402 is an independent educational project. Not affiliated with the x402 Foundation, Coinbase, or the Solana Foundation. Not financial advice.