Skip to main content
This tutorial uses a minimal API request to illustrate the complete Ace Data Cloud X402 flow. The goal is not to write complex code first, but to first understand: why the first request returns 402, what is in accepts, and how PAYMENT-SIGNATURE turns the same API request into a paid request.

Preparation

You need to prepare: No API Token is required when calling the Ace Data Cloud API with X402. The SDK does not include Authorization in the first request, and the Gateway returns 402 Payment Required and payment requirements; the SDK automatically retries after signing.

Install the SDK

Source code and package addresses: TypeScript:
Python:
If you want to use Solana, you also need to install the corresponding dependency:
The Solana signer dependency for the Python version is already included in acedatacloud-x402. Installation and import check output in a clean temporary environment:
Result description:
  • Both npm packages and PyPI packages are actually published packages, not placeholder names in the documentation.
  • acedatacloud-x402[cli] installs the CLI, and the approve-permit2 subcommand can be used for Permit2 authorization in upto scenarios.

The First Request Returns 402

You can first use curl to see what an unpaid request returns. The following example does not incur charges because it does not carry PAYMENT-SIGNATURE:
The response body contains the accepts array, with a common structure as follows:
The same challenge content is also placed in the PAYMENT-REQUIRED response header in base64 form, making it convenient for clients to read payment requirements without parsing the body. The program output summary for an unpaid request to the production API is as follows:
Result description:
  • The first request does not carry Authorization or PAYMENT-SIGNATURE, so it returns HTTP 402 and does not incur charges.
  • accepts is the only trusted signing basis for this request, containing the available networks, schemes, maximum amount, recipient address, and asset address.
  • network is a CAIP-2 identifier, and clients must match by the CAIP-2 string when selecting a network.
  • The maximum amount for this minimal gpt-4o-mini chat request is 95215 atomic USDC, which is 0.095215 USDC.
  • Every request should read the current 402 response; do not hardcode example amounts into business code.
Field meanings:

Complete the Payment Retry with the SDK

The following is a minimal TypeScript example. It specifies network: 'base', and the handler selects the Base payment requirement from the current 402 response; the actual amount and recipient address are still subject to accepts:
Four steps occur behind this code:
  1. The SDK sends a normal API request, without Authorization.
  2. The Gateway returns 402 Payment Required and accepts.
  3. createX402PaymentHandler selects the payment requirement for network = 'base' and signs a PAYMENT-SIGNATURE.
  4. The SDK retries with the same request body, and the Gateway calls the Facilitator to verify and settle before allowing the request through to the target API.

View Facilitator capabilities

The X402 API does not depend on a resource catalog. The client directly calls a known API, and uses the 402 Payment Required and accepts returned in real time by that request as the sole basis for pricing and signing. The Facilitator’s capability declaration is located at:
It only describes /supported, /verify, /settle, and the currently enabled payment networks, and does not list API resources. Ace Data Cloud’s production Facilitator address is:
You can check which networks and schemes it supports:
The returned kinds lists the networks and schemes supported by the Facilitator. For actual calls, the accepts returned by the API still takes precedence. Facilitator /supported output:
The results indicate:
  • /supported indicates that the Facilitator has verification and settlement capabilities for these networks and schemes.
  • Both Base and Solana support exact; upto is currently available only on Base.
  • Whether a specific API allows a certain network is still determined by that API’s 402 accepts.