Check Public Endpoints
Facilitator capability declaration: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:
kinds, the Facilitator endpoint is working properly.
Check 402 accepts
Send an unauthenticated request that will not incur charges:
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)
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- The 402 response from the first request.
- The selected payment requirement.
- The signed
PAYMENT-SIGNATUREsummary. - The HTTP status and response body after retrying.
- The on-chain settlement transaction, or the Facilitator error reason in case of failure.
PAYMENT-SIGNATURE values to logging systems or support tickets.
Example public API validation results:
- Base
exact, Solanaexact, and Baseuptoall completed paid retries from HTTP 402 to HTTP 200. - The on-chain transaction for Base
exactis available on BaseScan, and the settlement amount is95215atomic USDC. - The signing limit for Base
uptois95215atomic USDC, but the actual on-chain settlement is3atomic 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: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 atplatform.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.
- After creating the order, the order status is
Pending, and the price is1.26. - The first
pay/request returns HTTP 402. There are Baseexactand Solanaexactentries inaccepts, both with amounts of1200000atomic USDC. - Retrying with the Base
PAYMENT-SIGNATUREreturns HTTP 200, the order status changes toFinished, andpay_wayisX402. - After decoding
PAYMENT-RESPONSE, it showssuccess=True,network=base, and provides the same transaction hash. - The transaction status on BaseScan is
1, and the transfer amount is1200000atomic USDC, which is1.2USDC. - The creation price
1.26was paid during the old X402 payment discount policy period; the final signature and settlement amount are1.2USDC.
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.
upto returns invalid_upto_evm_payload_invalid_signature, prioritize checking:
extra.chainIdin theeip155:8453+uptoentry returned by the API (it should be8453).- The
extra.facilitatorAddressreturned by the API. - The Base
uptofacilitator address returned byhttps://facilitator.acedata.cloud/supported. - The Permit2 domain, spender, USDC contract, and signing account.
- Whether the wallet has already approved Permit2 for Base USDC.
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.
PAYMENT-SIGNATURE, complete EIP-712 signature, or mnemonic phrases.
Structured Payment Errors
Signed X402 failures return stablecode, 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.

