X402 Quick Start

This tutorial describes the complete process of Ace Data Cloud X402 with a minimal API request. The goal is not to write complex code first, but to understand: why the first request returns 402, what is in accepts, and how X-Payment turns the same API request into a paid request.

Preparation

You need to prepare:

Item Description
Wallet A wallet that supports the target network. Base / SKALE uses EVM wallets, Solana uses Solana wallets.
USDC The wallet needs to have enough USDC. The actual amount is based on maxAmountRequired in the 402 response.
Development Environment TypeScript recommends Node.js 18+; Python recommends Python 3.10+.
SDK It is recommended to use the official SDK, and not to manually write signature details.

When calling the Ace Data Cloud API with X402, an API Token is not required. The SDK's first request does not include Authorization, and the Gateway will return 402 Payment Required along with payment requirements; the SDK will automatically retry after signing.

Install SDK

Source code and package addresses:

TypeScript:

npm install @acedatacloud/sdk @acedatacloud/x402-client ethers

Python:

pip install acedatacloud acedatacloud-x402

If you want to use Solana, you also need to install the corresponding dependencies:

npm install @solana/web3.js

The Python version of the Solana signer dependency is already included in acedatacloud-x402.

Installation and import check output in a clean temporary environment:

@acedatacloud/sdk@2026.504.2
@acedatacloud/x402-client@2026.531.3
ethers@6.16.0
@solana/web3.js@1.98.4

acedatacloud 2026.4.26.1
acedatacloud-x402 2026.5.31.3
imports_ok True True True True True True
usage: acedatacloud-x402 [-h] {approve-permit2} ...

Result explanation:

  • The npm packages and PyPI packages are real published packages, not placeholder names in the documentation.
  • acedatacloud-x402[cli] will install the CLI, and the approve-permit2 subcommand can be used for Permit2 authorization in the upto scenario.

The First Request Will Return 402

You can first use curl to see what an unpaid request returns. The following example will not incur a charge because it does not carry X-Payment:

curl -sS -X POST https://api.acedata.cloud/openai/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "hi"}],
    "max_tokens": 1
  }'

The response body will include the accepts array, with a common structure as follows:

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "95215",
      "maxTimeoutSeconds": 3600,
      "resource": "/openai/chat/completions",
      "description": "...",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "chainId": 8453,
        "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      }
    }
  ]
}

The summary of the program output for the unpaid API request is as follows:

status=402
x402Version 2
accepts [
  ('base', 'exact', '95215'),
  ('base', 'upto', '95215'),
  ('solana', 'exact', '95215'),
  ('skale', 'exact', '95215'),
  ('skale', 'upto', '95215')
]

Result explanation:

  • The first request did not carry Authorization or X-Payment, so it returned HTTP 402 and did not incur a charge.
  • accepts is the only trusted signature basis for this request, containing optional networks, schemes, maximum amounts, payment addresses, and asset addresses.
  • The maximum amount for this minimal chat request for gpt-4o-mini is 95215 atomic USDC, which is 0.095215 USDC.
  • Each request should read the 402 response for that time, and do not hard-code the example amount into business code.

Field meanings:

Field Description
scheme Payment scheme. exact indicates a fixed amount, upto indicates an authorization limit, settled based on actual usage.
network Payment network, such as base, skale, solana.
maxAmountRequired Maximum payment amount, in USDC atomic units, 95215 indicates 0.095215 USDC.
payTo Payment address.
asset USDC contract address or Solana mint address.
extra Extended information needed for signing, such as chain ID, EIP-712 domain, Permit2 address, etc.

Complete Payment Retry with SDK

Here is the minimal TypeScript example. It specifies network: 'skale', and the handler will select the SKALE payment requirement from this 402 response; the actual amount and payment address will still be based on accepts:

import { Wallet } from 'ethers';
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const wallet = new Wallet(process.env.SKALE_PRIVATE_KEY!);

const evmProvider = {
  async request({ method, params }: { method: string; params?: unknown[] }) {
    if (method !== 'eth_signTypedData_v4') {
      throw new Error(`unsupported method: ${method}`);
    }
    const [, typedDataJson] = params as [string, string];
    const typedData = JSON.parse(typedDataJson);
    return wallet.signTypedData(typedData.domain, typedData.types, typedData.message);
  }
};

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'skale',
    evmProvider,
    evmAddress: wallet.address
  })
});

const response = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Reply with exactly: hello' }],
  max_tokens: 8
});

console.log(response.choices[0].message.content);

The output of the program running on the same link using the TypeScript SDK:

payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT

Result explanation:

  • content ADC_TS_SDK_X402_OK is a fixed string returned by the upstream model according to the prompt, indicating that the request has genuinely entered the model API after a paid retry.
  • payer is the local signed wallet address, and the private key has not been sent to Ace Data Cloud.
  • The SDK has completed the 402 parsing, X-Payment signing, and original request retry; the business code is still written in the usual SDK calling manner.

Four steps occurred behind this code:

  1. The SDK sends a regular API request without Authorization.
  2. The Gateway returns 402 Payment Required and accepts.
  3. createX402PaymentHandler selects the payment requirement with network = 'skale' and checks out X-Payment.
  4. The SDK retries with the same request body, and the Gateway calls the Facilitator for verification and settlement before releasing to the upstream API.

View Public Discovery Document

Ace Data Cloud provides the X402 discovery document:

curl https://platform.acedata.cloud/.well-known/x402

The return structure is:

{
  "version": 1,
  "resources": [
    "https://api.acedata.cloud/openai/chat/completions"
  ]
}

Discovery interface program output:

discovery_version 1
resources_count 70
has_chat True

Result explanation:

  • has_chat True indicates that the discovery document contains OpenAI-compatible chat resources.
  • The discovery document is used to discover resources; the actual payment amount is still based on the 402 accepts returned by the API.

Note that the discovery document is located at platform.acedata.cloud, while the actual API request is at api.acedata.cloud.

View Facilitator Support Capabilities

The production Facilitator address of Ace Data Cloud is:

https://facilitator.acedata.cloud

You can check which networks and schemes it supports:

curl https://facilitator.acedata.cloud/supported

The returned kinds will list the capabilities supported by the Facilitator, such as base/exact, base/upto, skale/exact, skale/upto, solana/exact, as well as test network capabilities. The actual call still depends on the accepts returned by the API.

Facilitator /supported program output:

kinds ['base/exact', 'base/upto', 'skale/exact', 'skale/upto', 'solana/exact', 'solana-devnet/exact']
upto_extra [
  ('base', {'facilitatorAddress': '0xd019...5708'}),
  ('skale', {'facilitatorAddress': '0xd047...CC1C'})
]

Result explanation:

  • /supported indicates that the Facilitator has verification and settlement capabilities for these networks and schemes.
  • Whether a specific network is allowed by the API still depends on the 402 accepts of that API.