Skip to main content
X402 involves HTTP, SDKs, signatures, Facilitators, and on-chain transactions. When troubleshooting signing or settlement issues, it is recommended to confirm layer by layer in the order of “public endpoint -> 402 response -> SDK payment handler -> on-chain settlement.” This tutorial explains how to inspect each layer and lists common errors.

Check Public Endpoints

Facilitator capability declaration:
If it returns facilitator, supportedKinds, and protocol endpoints, the capability metadata is normal. API resource discovery has been retired; please call the target API directly and use the real-time 402 response as the source of truth. Facilitator supported capabilities:
If it returns kinds, the Facilitator endpoint is working properly.

Check 402 accepts

Send an unauthenticated request that will not incur charges:
Check whether the returned accepts includes the network you want to use. network is a CAIP-2 identifier:
  • eip155:8453 + exact (Base)
  • eip155:8453 + upto (Base, post-metering)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact (Solana)
If the target network is not present, it means that the API or current environment has not configured the corresponding X402 payment method.

Run the X402Client Advanced Validation Tools

The X402Client repository provides advanced validation tools that can be used to confirm 402 response selection, signature generation, paid retry, and on-chain settlement. They require a funded wallet, RPC, private key, and development dependencies. For normal business integration, it is recommended to use the TypeScript or Python SDK first; run these tools only when you need to troubleshoot signing or on-chain settlement issues. Repository: https://github.com/AceDataCloud/X402Client
Base:
Solana:
The validation tools usually print:
  1. The 402 response from the first request.
  2. The selected payment requirement.
  3. The signed PAYMENT-SIGNATURE summary.
  4. The HTTP status and response body after retrying.
  5. The on-chain settlement transaction, or the Facilitator error reason in case of failure.
Do not send private keys or full PAYMENT-SIGNATURE values to logging systems or support tickets. Example public API validation results:
Notes:
  • Base exact, Solana exact, and Base upto all completed paid retries from HTTP 402 to HTTP 200.
  • The on-chain transaction for Base exact is available on BaseScan, and the settlement amount is 95215 atomic USDC.
  • The signing limit for Base upto is 95215 atomic USDC, but the actual on-chain settlement is 3 atomic USDC, indicating that post-metering charges are based on actual usage.
  • The Solana path has confirmed the paid retry and model output. Public RPCs may be rate-limited; if strict on-chain reconciliation is required, please use your own Solana RPC or confirm the transaction signature using platform-side settlement records.

SDK Smoke Test

The advanced validation tools are used to inspect signatures and on-chain settlement. The business side should also perform an SDK smoke test to confirm that application code can automatically handle 402 through the payment handler. Only the core snippets are shown below; the complete code needs to include the wallet, provider, and imports. TypeScript:
Python:
If the model returns the specified fixed string, it means that the SDK, payment handler, Gateway, Facilitator, and target API are connected end to end. The two smoke tests above use Base exact, which settles at the fixed amount quoted by 402. Chat completions are a token-metered scenario; for production integration, it is recommended to pass preferScheme: 'upto' (or prefer_scheme="upto" in Python) to settle based on actual usage. The Python SDK returns a dict object, and you can use res["choices"][0]["message"]["content"] to read the content.

Order Payment E2E

Order payments use the platform API at platform.acedata.cloud and require a platform account token. The complete flow is: create a Pending order, trigger 402 with POST /api/v1/orders/{order_id}/pay/, then retry with PAYMENT-SIGNATURE. Example small-amount order payment validation results:
The following transaction records are historical test samples under the old policy, and the amounts and transaction hashes are retained as-is. New X402 orders no longer provide payment method discounts; please use the amount in the current 402 response as the basis for signing and payment.
Result explanation:
  • After creating the order, the order status is Pending, and the price is 1.26.
  • The first pay/ request returns HTTP 402. There are Base exact and Solana exact entries in accepts, both with amounts of 1200000 atomic USDC.
  • Retrying with the Base PAYMENT-SIGNATURE returns HTTP 200, the order status changes to Finished, and pay_way is X402.
  • After decoding PAYMENT-RESPONSE, it shows success=True, network=base, and provides the same transaction hash.
  • The transaction status on BaseScan is 1, and the transfer amount is 1200000 atomic USDC, which is 1.2 USDC.
  • The creation price 1.26 was paid during the old X402 payment discount policy period; the final signature and settlement amount are 1.2 USDC.
If order payment does not include Authorization: Bearer {platform_token}, or the order does not belong to the current account, it will fail at the platform permission layer; this differs from the accountless X402 API that directly calls x402.acedata.cloud.

Common Errors

Base upto Checklist

upto is currently available only on Base (eip155:8453). Since the upto signature binds more EVM typed data parameters, special confirmation is required during integration that the real-time fields in the 402 response exactly match the client signature.
If Base upto returns invalid_upto_evm_payload_invalid_signature, prioritize checking:
  1. extra.chainId in the eip155:8453 + upto entry returned by the API (it should be 8453).
  2. The extra.facilitatorAddress returned by the API.
  3. The Base upto facilitator address returned by https://facilitator.acedata.cloud/supported.
  4. The Permit2 domain, spender, USDC contract, and signing account.
  5. Whether the wallet has already approved Permit2 for Base USDC.
The upto signature digest simultaneously binds the Permit2 domain, chain ID, spender, recipient address, facilitator address, and validAfter. If any one of them is inconsistent, the Facilitator will recover an incorrect signer, thereby returning an invalid signature. If all of these are consistent but it still returns 402, check the Permit2 allowance next; when not approved, it returns PERMIT2_ALLOWANCE_REQUIRED.

Save Verification Information

A complete verification should save at least:
  • API path and request body summary;
  • Selected network and scheme;
  • maxAmountRequired;
  • Payer wallet address;
  • Final HTTP status;
  • Model output or task ID in the response;
  • Settlement transaction link;
  • Gateway trace ID or platform usage record ID.
Do not save private keys, complete PAYMENT-SIGNATURE, complete EIP-712 signature, or mnemonic phrases.

Structured Payment Errors

Signed X402 failures return stable code, safe interpolation parameters, stage, and retry flag in extensions.acedatacloud.paymentError. Prioritize troubleshooting with this structure; do not parse the top-level English error, and do not ask users to provide wallet signatures or original on-chain simulation text.
  • charged: false: Verification was explicitly rejected before settlement, and no charge was initiated this time.
  • Does not contain charged: The result is unknown or has entered the settlement stage; check the order and on-chain status first, and do not directly repeat the payment.
  • settlement_pending: Do not repeat the payment yet; refresh the order first or contact support.
  • Unrecognized code: Handle it as payment_failed, and retain the public technical code for customer service lookup.