Integrating the x402 payment protocol—an HTTP 402-based payment standard—into an API is relatively straightforward on paper. Your server intercepts an unauthenticated or unpaid request, returns a payment challenge, and waits for the client to fulfill it and retry.
However, a subtle configuration mistake in how your endpoint issues that challenge can break the payment flow entirely.
Why You Should Self-Check Your Payment Challenge Before Going Live
Unlike traditional web forms where a human user might notice a broken button or report an error message, x402 endpoints are frequently consumed by automated scripts and agent clients. When an automated client hits an API expecting a standard x402 payment challenge and receives a malformed payload, a missing field, or an unrecognized network identifier, it rarely opens a support ticket. Instead, agent clients silently fail, drop the request, or move on.
For an API provider, a broken challenge translates directly to lost revenue and invisible integration friction. Maybe your middleware stripped a custom response header, or perhaps a typo crept into your asset configuration during deployment. Testing your endpoint with curl helps, but visually parsing JSON bodies or base64-encoded headers leaves plenty of room for human error.
Before pushing your API to production, you can run a quick automated diagnostic using x402check, a free, no-registration health-check tool where you paste any API URL to verify whether the endpoint properly supports the x402 payment protocol.
Depending on how your server responds, the tool returns one of five overall verdicts: ready, partial, not_detected, unreachable, or invalid. To understand how that verdict is calculated, let's break down the six specific checks the tool runs and what a failure in each one means for your deployment.
The Six Checks Behind a Healthy x402 Endpoint
1. reachable
What it checks: Verifies that the target API endpoint actually responds to an incoming request over the network.
What a failure means: If this check fails, your diagnostic stops immediately with an unreachable verdict. Common culprits include DNS misconfigurations, firewall rules blocking external requests, a crashed server process, or a simple typo in the URL you pasted.
2. https
What it checks: Inspects the transport protocol and warns if the endpoint is served over plain HTTP rather than HTTPS.
What a failure means: Handling payment challenges and client retry signatures over unencrypted HTTP exposes payment metadata and headers in transit. If this warns, you need to configure TLS on your reverse proxy, load balancer, or edge worker before accepting real payments.
3. payment_required
What it checks: Looks for an HTTP 402 status code or the presence of a PAYMENT-REQUIRED response header.
What a failure means: If neither is present, the tool will return a not_detected verdict. This usually means your x402 middleware is not firing on that specific route, your server is returning a 200 OK (giving away data for free), or a standard authentication layer is intercepting the request and returning a 401 Unauthorized or 403 Forbidden before the x402 logic can run.
4. x402_body
What it checks: Parses the payment challenge envelope. Because x402 has evolved, the check supports both x402 v1 (where the challenge lives in the 402 JSON response body) and x402 v2 (where the challenge is delivered in a base64-encoded PAYMENT-REQUIRED response header, designed for flows where the client retries with a PAYMENT-SIGNATURE header).
What a failure means: Your server signaled that payment is required, but the challenge payload itself could not be decoded. In v1, this indicates malformed JSON in the response body. In v2, it indicates corrupted base64 encoding or invalid JSON inside the PAYMENT-REQUIRED header. This typically triggers an invalid or partial verdict.
5. accepts_shape
What it checks: Inspects the parsed challenge to verify that the payment options are structurally complete. Specifically, it checks for five required fields: scheme, network, amount, payTo, and asset.
What a failure means: Even if your JSON parses cleanly, an x402 client cannot construct a payment transaction if any of these five parameters are missing or null. For example, forgetting to define payTo or asset in your environment variables will cause this check to fail, resulting in a partial or invalid verdict.
6. networks
What it checks: Validates the network identifier specified in your payment options. It recognizes networks named plainly (such as base, base-sepolia, or solana) as well as standard CAIP-2 formatted identifiers (for example, eip155:8453 for Base).
What a failure means: If your endpoint specifies an unrecognized or misspelled network string, clients won't know which chain to broadcast the payment on. Failing this check means you need to normalize your network configuration to either a recognized plain name or a valid CAIP-2 string.
Walking Through a Real Sample: The Astra Endpoint
To see what a clean configuration looks like in practice, we can look at a real public endpoint: https://astra-x402-data.astratc.workers.dev/v1/coin?id=bitcoin
When you run this URL through x402check, it returns an overall verdict of ready with 6/6 checks passing:
-
reachable(Pass): The Cloudflare Worker responds promptly to the GET request. -
https(Pass): The endpoint is served securely over HTTPS. -
payment_required(Pass): The server responds with an HTTP 402 status. -
x402_body(Pass): The tool detects and cleanly parses an x402 v1 challenge inside the 402 JSON response body. -
accepts_shape(Pass): All five required parameters (scheme,network,amount,payTo,asset) are present and populated. Specifically, the challenge requests payment in USDC (asset) for 10000 atomic units (amount, which equals $0.01) directed to the configured recipient address (payTo). -
networks(Pass): The challenge specifies the Base network, which the parser recognizes as a valid target network.
Because all six checks pass without warnings, any x402-compatible client or automated agent hitting this route has everything it needs to execute the $0.01 USDC payment on Base and retrieve the Bitcoin data payload.
Pre-Launch Checklist for Your x402 API
Before announcing your endpoint or handing the URL over to client developers, run through this quick checklist:
- [ ] Endpoint is live on HTTPS: Plain HTTP is disabled or redirects properly, ensuring no
httpswarnings. - [ ] Unpaid requests trigger a 402 challenge: Your route returns an HTTP 402 status or a
PAYMENT-REQUIREDheader instead of a 200, 401, or 500. - [ ] Challenge envelope matches your target spec (v1 or v2): Your v1 JSON body or v2 base64-encoded
PAYMENT-REQUIREDheader (paired withPAYMENT-SIGNATUREclient retry handling) decodes cleanly without syntax errors. - [ ] Payment options include all 5 required keys: Every accepted payment option explicitly defines
scheme,network,amount,payTo, andasset. - [ ] Network identifier is standard: Your network field uses a recognized plain name (
base,base-sepolia,solana) or CAIP-2 format (eip155:8453). - [ ] Verdict is ready: Pasting your production URL into x402check yields 6/6 passing checks.
