X402 Integration Guide

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.

Tutorial Applicable Scenarios Link
Quick Start Understand 402, accepts, and X-Payment process with a minimal request X402 Quick Start
TypeScript SDK Call Ace Data Cloud API in browser, Node.js, or frontend applications TypeScript SDK Integration
Python SDK Call API in Python services, scripts, Agents, or data pipelines Python SDK Integration
Order Payment Use X402 to pay for Ace Data Cloud console orders Order Payment Tutorial
Networks and Payment Methods Understand assets, signatures, and applicable scenarios for Base, SKALE, and Solana Networks and Payment Methods
exact and upto Distinguish between fixed price API and usage-based billing API Billing Scheme Explanation
Facilitator Understand the server-side link of verify, settle, and self-built payment APIs Facilitator Integration
E2E and Troubleshooting Check public entry points, run repository verification scripts, and locate common 402, signature, and settlement issues E2E Verification and Troubleshooting

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:

Project Address
Ace Data Cloud SDK https://github.com/AceDataCloud/SDK
X402 Client https://github.com/AceDataCloud/X402Client
X402 Facilitator https://github.com/AceDataCloud/FacilitatorX402
npm SDK https://www.npmjs.com/package/@acedatacloud/sdk
npm X402 Client https://www.npmjs.com/package/@acedatacloud/x402-client
PyPI SDK https://pypi.org/project/acedatacloud/
PyPI X402 Client https://pypi.org/project/acedatacloud-x402/

The SDK will automatically handle the first unauthenticated request, parse 402 Payment Required, call the payment handler, and retry these steps with X-Payment. 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.

Production Verification Summary

Below are only the results that have been actually run. Each sub-tutorial contains more complete program output and explanations.

Program run result summary:

packages
@acedatacloud/sdk@2026.504.2 import ok
@acedatacloud/x402-client@2026.531.3 import ok
acedatacloud==2026.4.26.1 import ok
acedatacloud-x402==2026.5.31.3 import ok

API 402
status 402
accepts base/exact, base/upto, solana/exact, skale/exact, skale/upto

TypeScript SDK
content ADC_TS_SDK_X402_OK

Python SDK
content ADC_PY_SDK_X402_OK

Base exact
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3

SKALE exact
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

Base upto
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Solana exact
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run

Order payment
order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151

Result Explanation:

  • Both npm and PyPI packages have been successfully installed and imported in a clean environment.
  • Unpaid API requests return 402, with accepts including available payment methods for Base, SKALE, and Solana.
  • 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.
  • Solana exact only writes HTTP 200 and model output; the current on-chain signature was not confirmed in this run, so no tx hash is written.

Public Verification Scope

Before integration, you can verify these public entry points and source code behaviors:

  • API requests without Authorization or X-Payment 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, and the SDK transport layer will call the handler and retry once after receiving a 402.
  • https://platform.acedata.cloud/.well-known/x402: Returns the X402 discovery document.
  • https://facilitator.acedata.cloud/supported: Returns the networks and schemes supported by the Facilitator.
  • The X402Client repository contains on-chain E2E scripts that can be used for internal regression and troubleshooting; the script results do not replace the accepts returned by the online API.

upto belongs to post-measurement settlement, suitable for APIs where the actual usage for chat completion, model invocation, etc., is only known after the response. The base upto is the recommended path to verify first; SKALE upto needs to confirm that the live Facilitator and Gateway's chain ID and facilitator address configuration are consistent before being used in production.