402 Payment Required. With Ace Data Cloud’s X402 capability, callers do not need to create an API Token or prepay account balance, but instead directly complete on-chain payment with USDC in each API request.
This set of documents is organized in the actual integration order: first complete a minimal request, then integrate the SDK, and then understand networks, billing schemes, order payments, and the Facilitator. It is recommended to read from top to bottom according to the table below.
Recommended Integration Path
If you only want to call Ace Data Cloud APIs, prioritize using the official SDKs:- TypeScript:
@acedatacloud/sdk+@acedatacloud/x402-client - Python:
acedatacloud+acedatacloud-x402
The SDK automatically completes the steps of making the first unauthenticated request, parsing
402 Payment Required, calling the payment handler, and retrying with PAYMENT-SIGNATURE. You only need to prepare a wallet with USDC and choose the network you want to use.
If you want your own API to also support receiving X402 payments, you need to read the Facilitator documentation to understand the relationship between paymentRequirements, paymentPayload, /verify, and /settle.
Support Status
Ace Data Cloud X402 has completed validation on public APIs, official SDKs, Facilitator, and on-chain settlement paths. The table below summarizes the current status according to the capability dimensions most commonly used by developers during integration.
The following output is only used to illustrate the response format of validated paths. During actual integration, always rely on the
accepts returned by the current API.
- Both npm and PyPI packages have been installed and imported successfully in clean environments.
- Unpaid API requests return 402, and
acceptsincludes available payment methods for Base and Solana. accepts[].networkis a CAIP-2 identifier; clients must match by the CAIP-2 string when selecting a network.- Both the TypeScript SDK and Python SDK can automatically handle 402 and complete a paid retry.
- Base
exact, Baseupto, and order payments all have publicly accessible explorer URLs. - The signed ceiling for Base
uptois95215atomic USDC, while the actual settlement is3atomic USDC, demonstrating the characteristic of postpaid metering settlement based on actual usage. - Solana
exacthas verified HTTP 402 -> HTTP 200 and model output. Since public RPC queries may be rate-limited, it is recommended to use your own Solana RPC or platform-side settlement records to confirm the transaction signature during strict reconciliation.
Integration Notes
When developers integrate, please prioritize the real-time payment requirements returned by the current request, rather than copying example amounts or addresses from the documentation:accepts[].maxAmountRequiredis the maximum amount that can be signed for the current request.accepts[].assetis the USDC contract or mint to use for this request.accepts[].extra.chainId,accepts[].extra.facilitatorAddress, andaccepts[].extra.verifyingContractparticipate in the EVM typed data signature.uptorequires the wallet to first authorize Permit2 for USDC on the target chain; if not authorized, it returnsPERMIT2_ALLOWANCE_REQUIRED.- If you explicitly want to use postpaid metering, pass
preferScheme: 'upto'in the TypeScript SDK; otherwise, the SDK selects the first available requirement returned by the server for that network.
Scope That Can Be Publicly Verified
Before integration, you can first verify these public endpoints and SDK behaviors:- API requests without
AuthorizationorPAYMENT-SIGNATUREreturn402 Payment Required; theacceptsin the response is the sole signing basis for the current request. - Both the TypeScript SDK and Python SDK provide payment handlers; upon receiving 402, the SDK transport layer calls the handler and retries once.
https://facilitator.acedata.cloud/.well-known/x402: returns the networks, schemes, and protocol endpoints supported by the Facilitator; API prices are still subject to the real-time 402 returned by the target request.https://facilitator.acedata.cloud/supported: returns the networks and schemes supported by the Facilitator.- The X402Client repository includes advanced on-chain verification tools that can be used to confirm signature, retry, and settlement behavior; tool output does not replace the
acceptsreturned by the online API.
upto is a postpaid metering settlement method, suitable for APIs where actual usage is only known after the response, such as chat completions and model calls. Currently, only Base provides upto; if signature verification fails, check whether the chain id, facilitator address, spender, USDC contract, and Permit2 allowance are consistent with the 402 response.
