x402station.io API reference
Seller check
Seller check for one host: can stock v1 and v2 x402 clients pay your live 402 on Base, does the gate's price / network / asset / payTo match your catalog listing and Coinbase's discovery entry, is each endpoint in Coinbase's index (CDP Bazaar), 7-day liveness per endpoint, and what changed since your last check. Every finding has a code, a severity and a concrete fix.
This HTML page is served by GET /api/v1/diagnose. The paid API operation remains POST /api/v1/diagnose.
x402 challenge example
HTTP/1.1 402 Payment Required
payment-required: <base64 PaymentRequiredResponse>
www-authenticate: x402
content-type: application/json; charset=utf-8
{
"x402Version": 2,
"error": "Payment required",
"resource": {
"url": "https://x402station.io/api/v1/diagnose",
"description": "Seller check"
},
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"asset": "USDC",
"amount": "50000",
"payTo": "0x4053338C7cB38624C0bc23c900F78Cf8470b4E38",
"maxTimeoutSeconds": 300
}
]
}
Request body
{
"host": "api.example.com"
}
Success response
{
"ok": false,
"host": "api.example.com",
"free_first_check": true,
"summary": {
"endpoints": 18,
"listed_in_agentic_market": true,
"coinbase_index": "15 of 18 endpoints are in Coinbase's index (CDP Bazaar); not indexed: https://api.example.com/v1/a, https://api.example.com/v1/b, https://api.example.com/v1/c.",
"in_coinbase_index": {
"yes": 15,
"no": 3
},
"live": {
"checked": 5,
"v2_payable": 4,
"v1_payable": 0,
"unreachable": 0
},
"findings": {
"critical": 1,
"warn": 3,
"info": 6
}
},
"since_last_check": null,
"first_check": true,
"findings": [
{
"code": "v2_clients_cannot_pay",
"severity": "warn",
"endpoint": "https://api.example.com/v1/report",
"detail": "Stock v2 clients (@x402/fetch, @x402/core) read the PAYMENT-REQUIRED header and cannot pay it: the v2 challenge names the network \"base\"; v2 clients match the CAIP-2 id \"eip155:8453\". Legacy v1 clients pay through the JSON body.",
"fix": "Use network \"eip155:8453\" in v2 challenges (\"base\" is the v1 name)."
}
]
}
Error codes
| status | meaning |
|---|---|
400 | Malformed JSON body or invalid host. |
402 | Payment required. The JSON body's free_first_check says why this request was not free. Decode payment-required, sign x402, retry. |
404 | Host not in the catalog. Not charged. |
409 | The same payment header is already being answered. Not charged; wait for the first answer. |
503 | Query timeout, or all live-check slots busy (error live_checks_busy, Retry-After). Not charged; safe to retry. |
Notes
- One check per host every 30 days is free for every host we track: send the request without a payment header. Limits: 3 free checks per client network per UTC day and a global daily cap.
- Live: up to 5 endpoints are fetched unpaid now (the one in body.url first). v2 = the stock @x402/fetch client (PAYMENT-REQUIRED header; without one it pays a v1 body); v1 = legacy clients reading the JSON body with x402Version 1. Seller text from the challenge is never echoed.
- Finding codes (live): no_client_can_pay, v2_clients_cannot_pay, v1_clients_cannot_pay, v1_only_challenge, header_carries_v1, v2_schema_mismatch, v1_schema_mismatch, address_not_checksummed, v1_v2_disagree, listed_price_mismatch, listed_network_mismatch, listed_asset_mismatch, coinbase_pay_to_mismatch, coinbase_price_mismatch, coinbase_network_mismatch, coinbase_asset_mismatch, live_unreachable, live_private_address, live_redirect, live_no_challenge, live_server_error, live_rejects_unpaid.
- Finding codes (7-day and catalog): not_in_catalog, wildcard_402, spa_fallback, unreachable, degraded, rejects_unpaid_request, no_payment_challenge, slow_p99, not_in_bazaar, never_paid_30d, cross_listed, no_recent_probes.
- Live slots: 8 checks per server and 2 per client network fetch live at once. Without a slot a paid check answers 503 live_checks_busy and is not charged; a free check answers from stored evidence with summary.live.status skipped_busy.
- since_last_check: new and fixed findings and changes in price, payTo, network, status and Coinbase indexing since the previous check of the host; null on the first check.