x402serpsHelp & troubleshooting
Payment not detected
- An unpaid call returns HTTP 402. In x402 v2 the requirements are in the
PAYMENT-REQUIREDresponse header (base64 JSON) and mirrored in the JSON body (x402Version: 2,accepts[]). - Retry the same request (same method, path and body) with the signed payment in the
PAYMENT-SIGNATUREheader (v2). Legacy v1 clients sendX-PAYMENTand should also sendX402-Version: 1to get a v1-format challenge. - If you send both a payment header and
Authorization: Bearer xs_..., the payment header wins and the credit key is ignored. - Payment is verified and settled by the facilitator before results are returned. A successful paid response is HTTP 200 with your results; another 402 means the payment was not accepted (see the error codes below). Failed calls (4xx/5xx from our side after verification) are not charged.
- Per-unit endpoints (multi-URL
extract,crawl) are priced from the request body, so the body you pay for must be the body you send. Legacy v1 payments cover one unit only; multi-unit requests return HTTP 400 asking for x402 v2 or a credit key.
Wrong chain or amount on Base or Solana
- We accept USDC only, with the
exactscheme, on Base mainnet (eip155:8453) and Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Testnets (Base Sepolia, Solana devnet) are not accepted. - Always use the
amount,assetandpayTofrom the 402 you just received rather than hard-coding them. Prices: search $0.004, extract $0.003 per URL; see pricing. - Base: sign with an EVM wallet (
@x402/evm). Solana: sign with an SVM wallet (@x402/svm). Your wallet needs enough USDC on that chain.
x402 error codes
These codes come from the x402 libraries and the facilitator and are returned in the 402 response (error / invalidReason).
| Code | Meaning and fix |
|---|---|
payment_required | No payment header was sent. Pay using the requirements in the response and retry. |
invalid_payload | The payment header could not be decoded. Send base64 JSON produced by an x402 client such as @x402/fetch. |
invalid_scheme / unsupported_scheme | Use scheme exact. |
invalid_network, invalid_exact_evm_network_mismatch | The payment is for a different chain than the requirement you picked. Use Base or Solana mainnet as listed in accepts[]. |
invalid_exact_evm_insufficient_balance | Not enough USDC on Base in the paying wallet. |
invalid_exact_evm_recipient_mismatch, invalid_exact_svm_payload_recipient_mismatch | Paid to the wrong address. Use payTo from the 402. |
invalid_exact_evm_payload_authorization_value_mismatch, invalid_exact_svm_payload_amount_mismatch | Wrong amount. Use the amount from the 402 for this exact request body. |
invalid_exact_evm_payload_authorization_valid_before / _valid_after | The signed authorization expired or is not yet valid. Sign a fresh payment and retry promptly; check your clock. |
invalid_exact_evm_nonce_already_used | A payment was reused. Sign a new payment for every call. |
invalid_exact_evm_signature, invalid_exact_evm_failed_to_verify_signature | Signature invalid. Make sure the signer owns the paying address. |
invalid_exact_svm_payload_mint_mismatch | Solana payment used a token other than USDC. |
settle_failed, invalid_exact_evm_transaction_failed | The on-chain transfer failed at settlement. Check your balance and retry; if funds left your wallet, contact us with the tx hash. |
MCP errors
- Endpoint:
https://x402serps.com/api/mcp(JSON-RPC over HTTP POST).initializeandtools/listare free. -32700 Parse error: the request body was not valid JSON-RPC.-32601 Method not found: unknown method or tool name. Calltools/listand use an exact tool name.- Tool result with
isError: trueand text "Payment required (x402)": the call needs payment, a credit key (Authorization: Bearer xs_...on the MCP request) orX-Trial: 1. - Missing arguments return the endpoint's error inside the tool result, for example
missing q(search tools) ormissing url (or urls[])(extract). Check the tool'sinputSchema.
API keys, credits and Stripe
- Credit packs are bought with a card at pricing. After checkout the key (
xs_...) is shown once on the success page. If the page says "Payment pending", refresh once Stripe confirms the payment. 401 unknown API key: the key is wrong or mistyped. Send it asAuthorization: Bearer xs_....- Not enough credits: the call falls back to an x402 402 response with header
X-Credits-Statusshowing credits left and needed. Top up or pay with x402. 503 credits temporarily unavailable: a temporary database problem; retry shortly. You are not charged.- Check your balance:
GET /api/v1/balancewith your Bearer key. Every credit-key response includesX-Credits-RemainingandX-Credits-Charged. - Cached results (header
X-Cache: HIT) on search, news and vertical endpoints cost 50% for credit keys; the refund shows inX-Credits-Refunded. - Lost the key, or saw "Key already shown"? Email us with your Stripe receipt. We can't show a key a second time.
Free trial
- Send
X-Trial: 1on search, news, single-URL extract, images, places, shopping, scholar or videos. 25 calls per network in total, up to 10 a minute. 403: the endpoint isn't covered by the trial, or you sent more than one URL to extract.429: per-minute limit, retry after 60 s. If the trial is used up you get the normal 402 withX-Trial-Status.
Still stuck? Contact us
Email hello@x402serps.com. Include the transaction hash (for x402 payments), the endpoint, the time (with timezone), the request body and the response status and body. Never send your API key, private key or seed phrase. We will never ask for them.