Skip to main content
X402 is an on-chain payment protocol based on HTTP 402 Payment Required. With the X402 capabilities of Ace Data Cloud, callers can complete on-chain payments directly with USDC in each API request without creating an API Token or pre-funding account balances. This set of documents is organized in the order of actual integration: first run through a minimal request, then integrate the SDK, and finally understand networks, billing schemes, order payments, and Facilitator. It is recommended to read from top to bottom as per the table below. If you just want to call the Ace Data Cloud API, it is recommended to use the official SDKs:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Public source code and package addresses: The SDK will automatically handle the first unauthenticated request, parse 402 Payment Required, call the payment handler, and retry these steps with PAYMENT-SIGNATURE. You only need to prepare a wallet with USDC and choose the network you wish to use. If you want your own API to also support X402 payments, you will need to read the Facilitator documentation to understand the relationship between paymentRequirements, paymentPayload, /verify, and /settle.

​
Support Status

Ace Data Cloud X402 has been validated in public APIs, official SDKs, Facilitator, and on-chain settlement paths. The table below summarizes the current status based on the most commonly used capabilities by developers during integration. The following output is for illustrative purposes only to show the return format of validated paths. During actual integration, always refer to the current API’s returned accepts.
Note:
  • Both npm and PyPI packages have been successfully installed and imported in a clean environment.
  • Unpaid API requests return 402, and the accepts includes available payment methods for Base, SKALE, and Solana.
  • accepts[].network is a CAIP-2 identifier, and clients must match the network selection according to the CAIP-2 string.
  • Both TypeScript SDK and Python SDK can automatically handle 402 and complete paid retry.
  • Base exact, SKALE exact, Base upto, and order payments all have publicly accessible explorer addresses.
  • The signature ceiling for Base upto is 95215 atomic USDC, with an actual settlement of 3 atomic USDC, reflecting the characteristic of post-measurement settlement based on actual usage.
  • Solana exact has verified HTTP 402 -> HTTP 200 and model output. Due to potential rate limiting on public RPC queries, it is recommended to use a private Solana RPC or platform-side settlement records to confirm transaction signatures during strict reconciliation.

​
Access Considerations

When integrating, developers should prioritize the real-time payment requirements returned by the current request, rather than copying example amounts or addresses from the documentation:
  • accepts[].maxAmountRequired is the maximum amount that can be signed for the current request.
  • accepts[].asset is the USDC contract or mint to be used for this request.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress, and accepts[].extra.verifyingContract will participate in EVM typed data signing.
  • upto requires the wallet to first authorize Permit2 for the target chain USDC; if unauthorized, it will return PERMIT2_ALLOWANCE_REQUIRED.
  • If you explicitly wish to use post-measurement, please pass preferScheme: 'upto' in the TypeScript SDK; otherwise, the SDK will select the first available requirement returned by the server under that network.

​
Public Verification Scope

Before integration, you can verify these public endpoints and SDK behaviors:
  • API requests without Authorization or PAYMENT-SIGNATURE will return 402 Payment Required, and the accepts in the response is the only signature basis for this request.
  • Both TypeScript SDK and Python SDK provide a payment handler; the SDK transport layer will call the handler and retry once after receiving a 402.
  • https://facilitator.acedata.cloud/.well-known/x402: returns the networks, schemes, and protocol endpoints supported by the Facilitator; API pricing is still based on 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 signatures, retries, and settlement behaviors; tool outputs do not replace the accepts returned by the online API.
upto belongs to post-measurement settlement, suitable for APIs where real usage is only known after the response, such as chat completion and model invocation. Currently, only Base provides upto; if signature verification fails, please check whether the chain id, facilitator address, spender, USDC contract, and Permit2 allowance are consistent with the 402 response.