Skip to main content
X402 is an on-chain payment protocol based on HTTP 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. 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
Public source code and package addresses: 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.
Notes:
  • Both npm and PyPI packages have been installed and imported successfully in clean environments.
  • Unpaid API requests return 402, and accepts includes available payment methods for Base and Solana.
  • accepts[].network is 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, Base upto, and order payments all have publicly accessible explorer URLs.
  • The signed ceiling for Base upto is 95215 atomic USDC, while the actual settlement is 3 atomic USDC, demonstrating the characteristic of postpaid metering settlement based on actual usage.
  • Solana exact has 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[].maxAmountRequired is the maximum amount that can be signed for the current request.
  • accepts[].asset is the USDC contract or mint to use for this request.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress, and accepts[].extra.verifyingContract participate in the EVM typed data signature.
  • upto requires the wallet to first authorize Permit2 for USDC on the target chain; if not authorized, it returns PERMIT2_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 Authorization or PAYMENT-SIGNATURE return 402 Payment Required; the accepts in 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 accepts returned 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.