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 preloading account balances.

This set of documents is organized in the order of actual integration: first run 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 front-end 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
Pricing Explanation Understand the relationship between X402 pricing and Credits unit price, and the actual prices of each service X402 Pricing 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 advanced verification tools, 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.

Support Status

Ace Data Cloud X402 has been validated in public API, official SDK, Facilitator, and on-chain settlement paths. The table below summarizes the current status based on the most commonly used capabilities by developers during integration.

Capability Status Description
402 discovery Available https://platform.acedata.cloud/.well-known/x402 returns the public discovery document.
API 402 accepts Available Unpaid requests will return available payment requirements for Base, SKALE, and Solana.
TypeScript SDK Available @acedatacloud/sdk and @acedatacloud/x402-client can automatically handle 402, signatures, and retries.
Python SDK Available acedatacloud and acedatacloud-x402 can automatically handle 402, signatures, and retries.
Base exact On-chain validated Suitable for fixed amount APIs and order payments.
Base upto On-chain validated Suitable for post-measurement APIs like chat completion.
SKALE exact On-chain validated Suitable for low gas cost EVM payment scenarios.
SKALE upto On-chain validated Requires prior Permit2 approval for SKALE USDC.
Solana exact HTTP paid retry validated Validated API paid retry with model response; on-chain signature confirmation is recommended to use your own Solana RPC for reconciliation.
Order Payment On-chain validated Base exact order payments have completed on-chain settlement and updated order status.

The following output is for illustration of the validated path's return format. During actual integration, always refer to the current API's returned accepts.

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

SKALE upto
HTTP 402 -> HTTP 200
content I am Claude Sonnet 4.5, developed by Anthropic.
trace_id ca6f63a9-36b7-434a-b8a1-eb0857475e59
approval tx 0x646e92908cc31614bf99f22b13f48a00a74ddd89f7614327ea59802f1094629e
settlement tx 0x51831a97fb97802951bee5dfb36735f4a0b589f153e6a23976fad5495c3925bc
explorer https://skale-base-explorer.skalenodes.com/tx/0x51831a97fb97802951bee5dfb36735f4a0b589f153e6a23976fad5495c3925bc
signed ceiling 4760750 atomic USDC
settlement value 151 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

Note:

  • Both npm and PyPI packages have been successfully installed and imported in a clean environment.
  • Unpaid API requests return 402, with accepts containing 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, SKALE upto, and order payments all have publicly accessible explorer addresses.
  • The signed ceiling for SKALE upto is 4760750 atomic USDC, with an actual settlement of 151 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 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; the SDK transport layer will call the handler and retry once upon 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 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 actual usage is only known after the response, such as chat completion and model invocation. Both Base upto and SKALE upto have completed on-chain verification; if signature verification fails, please check if the chain id, facilitator address, spender, USDC contract, and Permit2 allowance are consistent with the 402 response.