静觅 崔庆才的个人站点 - Python爬虫教程

0%

X402 快速开始

作者 发表于 分类于 阅读次数： 本文字数： 5.5k 阅读时长 ≈ 5 分钟

本教程用一个最小的 API 请求说明 Ace Data Cloud X402 的完整流程。目标不是先写复杂代码，而是先看懂：为什么第一次请求会返回 402、accepts 里有什么、X-Payment 又是怎样让同一个 API 请求变成已支付请求的。

准备工作

你需要准备：

项目 说明
钱包 一个支持目标网络的钱包。Base / SKALE 使用 EVM 钱包，Solana 使用 Solana 钱包。
USDC 钱包中需要有足够 USDC。实际金额以 402 响应里的 maxAmountRequired 为准。
开发环境 TypeScript 推荐 Node.js 18+；Python 推荐 Python 3.10+。
SDK 推荐使用官方 SDK，不建议手写签名细节。

X402 调用 Ace Data Cloud API 时不需要 API Token。SDK 第一次请求不带 Authorization，Gateway 会返回 402 Payment Required 和支付要求；SDK 签名后自动重试。

安装 SDK

源码和包地址：

TypeScript：

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

Python：

1
 
pip install acedatacloud acedatacloud-x402

如果要使用 Solana，还需要安装对应依赖：

1
 
npm install @solana/web3.js

Python 版本的 Solana signer 依赖已经包含在 acedatacloud-x402 中。

干净临时环境的安装和导入检查输出：

1
2
3
4
5
6
7
8
9
 
@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} ...

结果说明：

  • npm 包和 PyPI 包都是真实发布包，不是文档里的占位名称。
  • acedatacloud-x402[cli] 会安装 CLI，approve-permit2 子命令可用于 upto 场景的 Permit2 授权。

第一次请求会返回 402

你可以先用 curl 看看未支付请求返回什么。下面示例不会产生扣费，因为它没有携带 X-Payment：

1
2
3
4
5
6
7
 
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
  }'

返回体会包含 accepts 数组，常见结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
{
  "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"
      }
    }
  ]
}

生产 API 未支付请求的程序输出摘要如下：

1
2
3
4
5
6
7
8
9
 
status=402
x402Version 2
accepts [
  ('base', 'exact', '95215'),
  ('base', 'upto', '95215'),
  ('solana', 'exact', '95215'),
  ('skale', 'exact', '95215'),
  ('skale', 'upto', '95215')
]

结果说明：

  • 第一次请求没有携带 Authorization 或 X-Payment，所以返回 HTTP 402，不会产生扣费。
  • accepts 是本次请求唯一可信的签名依据，包含可选网络、scheme、金额上限、收款地址和资产地址。
  • 这次 gpt-4o-mini 最小聊天请求的上限金额是 95215 atomic USDC，也就是 0.095215 USDC。
  • 每次请求都应该读取当次 402 响应，不要把示例金额硬编码进业务代码。

字段含义：

字段 说明
scheme 支付方案。exact 表示固定金额，upto 表示授权上限、按实际用量结算。
network 支付网络，例如 base、skale、solana。
maxAmountRequired 最大支付金额，单位是 USDC atomic units，95215 表示 0.095215 USDC。
payTo 收款地址。
asset USDC 合约地址或 Solana mint 地址。
extra 签名需要的链 ID、EIP-712 domain、Permit2 地址等扩展信息。

用 SDK 完成支付重试

下面是最小 TypeScript 示例。它指定 network: 'skale'，handler 会从本次 402 响应中选择 SKALE 的 payment requirement；实际金额和收款地址仍以 accepts 为准：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
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);

同一链路用 TypeScript SDK 的程序运行结果：

1
2
3
4
 
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT

结果说明：

  • content ADC_TS_SDK_X402_OK 是上游模型按提示词返回的固定字符串，说明付费重试后请求真实进入了模型 API。
  • payer 是本地签名钱包地址，私钥没有发送给 Ace Data Cloud。
  • SDK 完成了 402 解析、X-Payment 签名和原请求重试；业务代码仍按普通 SDK 调用方式写。

这段代码背后发生了四步：

  1. SDK 发送一次普通 API 请求，不带 Authorization。
  2. Gateway 返回 402 Payment Required 和 accepts。
  3. createX402PaymentHandler 选择 network = 'skale' 的 payment requirement 并签出 X-Payment。
  4. SDK 用同一个请求体重试，Gateway 调用 Facilitator 验证并结算后放行到上游 API。

查看公开发现文档

Ace Data Cloud 提供 X402 discovery 文档：

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

返回结构为：

1
2
3
4
5
6
 
{
  "version": 1,
  "resources": [
    "https://api.acedata.cloud/openai/chat/completions"
  ]
}

Discovery 接口程序输出：

1
2
3
 
discovery_version 1
resources_count 70
has_chat True

结果说明：

  • has_chat True 表示 discovery 文档中包含 OpenAI-compatible chat 资源。
  • discovery 文档用于发现资源；实际支付金额仍以 API 请求返回的 402 accepts 为准。

注意 discovery 文档位于 platform.acedata.cloud，而实际 API 请求位于 api.acedata.cloud。

查看 Facilitator 支持能力

Ace Data Cloud 的生产 Facilitator 地址为：

1
 
https://facilitator.acedata.cloud

可以查看它支持哪些网络和 scheme：

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

返回的 kinds 会列出 Facilitator 支持的能力，例如 base/exact、base/upto、skale/exact、skale/upto、solana/exact，以及测试网络能力。实际调用时仍以 API 返回的 accepts 为准。

Facilitator /supported 程序输出：

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

结果说明：

  • /supported 说明 Facilitator 具备这些网络和 scheme 的验证、结算能力。
  • 具体 API 是否允许某个网络，仍以该 API 的 402 accepts 为准。
相关文章