Skip to main content
TypeScript is one of the most recommended ways to integrate Ace Data Cloud X402. The official SDK is responsible for regular API calls, task polling, error handling, and automatic retries; @acedatacloud/x402-client is responsible for signing the PAYMENT-SIGNATURE request header when encountering 402 Payment Required. Source code and package links:

Install Dependencies

If using Base, EVM signing capability is required:
If using Solana, a Solana wallet adapter or @solana/web3.js is required:
Installation and import check output for a clean npm project:
Result notes:
  • Both @acedatacloud/sdk and @acedatacloud/x402-client can be installed from npm and imported by Node.js.
  • ethers is used for EVM typed data signing, and @solana/web3.js is used for Solana transaction construction.

Base Example

In the browser, you can directly use window.ethereum. In Node.js, you can wrap ethers.Wallet in an EIP-1193-style provider.

Browser Wallet Example

When using MetaMask, Coinbase Wallet, or WalletConnect in a frontend application, you typically pass the EIP-1193 provider directly:
The browser wallet will display a signature confirmation prompt. What the user signs is not an arbitrary message, but the payment requirement returned by the API: the recipient address, USDC contract, amount, validity period, and nonce are all included in the signature.

Solana Example

Solana uses SPL USDC TransferChecked. The wallet adapter passed in needs to expose publicKey and signAndSendTransaction.
The Solana path currently supports only exact and does not support upto. If the API returns multiple accepts, the handler selects the item with network = 'solana'. The Solana path has been verified on the same public API, where paid retry can return HTTP 200 and ADC_SOLANA_E2E_OK. Public RPC queries may be rate-limited, so this article does not include a Solana tx hash; when on-chain reconciliation is needed, please use your own Solana RPC or confirm through console records.

Choose exact or upto

The current TypeScript handler selects the first payment requirement matching the network returned by the server. Ace Data Cloud’s API usually places exact for the same network before upto, so if you explicitly want to use post-paid metering, you need to pass preferScheme: 'upto'. Example:
If the server does not return an upto requirement for that network, the handler automatically falls back to the first available requirement for that network, which is usually exact. upto requires a one-time Permit2 authorization. upto is currently only available on Base, so only a one-time authorization for Base USDC is required:
Base upto has completed public API verification: HTTP 402 -> HTTP 200, and the post-paid settlement tx is 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. See the billing scheme documentation for the full output.

What the SDK Does

The transport of @acedatacloud/sdk executes the payment handler once when it receives a 402:
The handler returned by @acedatacloud/x402-client will:
  1. Select the payment requirement for the target network from ctx.accepts.
  2. Construct an EVM EIP-712 signature or Solana transfer transaction according to the network.
  3. Serialize the envelope as Base64.
  4. Return { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. The SDK automatically retries with the original request body.
This means business code only needs to be written like a regular SDK call, without manually handling 402 retries.