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

0%

X402 集成指南

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

X402 是基于 HTTP 402 Payment Required 的链上支付协议。通过 Ace Data Cloud 的 X402 能力，调用方可以不创建 API Token、不预充值账户余额，而是在每一次 API 请求中直接用 USDC 完成链上支付。

这组文档按真实接入顺序组织：先跑通一次最小请求，再接入 SDK，之后理解网络、计费方案、订单支付和 Facilitator。建议按下表从上到下阅读。

教程 适用场景 链接
快速开始 先用一个最小请求理解 402、accepts 和 PAYMENT-SIGNATURE 流程 X402 快速开始
TypeScript SDK 在浏览器、Node.js 或前端应用中调用 Ace Data Cloud API TypeScript SDK 接入
Python SDK 在 Python 服务、脚本、Agent 或数据流水线中调用 API Python SDK 接入
订单支付 用 X402 支付 Ace Data Cloud 控制台订单 订单支付教程
网络与支付方式 了解 Base、SKALE、Solana 的资产、签名和适用场景 网络与支付方式
exact 与 upto 区分固定价格 API 和用量后置结算 API 计费方案说明
价格说明 了解 X402 价格与 Credits 单价的关系，及各服务真实价格 X402 价格说明
Facilitator 理解 verify、settle 和自建收款 API 的服务端链路 Facilitator 集成
E2E 与故障排查 检查公开入口、运行高级验证工具，定位常见 402、签名和结算问题 E2E 验证与故障排查

推荐接入路径

如果你只是想调用 Ace Data Cloud API，优先使用官方 SDK：

  • TypeScript：@acedatacloud/sdk + @acedatacloud/x402-client
  • Python：acedatacloud + acedatacloud-x402

公开源码与包地址：

项目 地址
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/

SDK 会自动完成第一次无认证请求、解析 402 Payment Required、调用 payment handler、携带 PAYMENT-SIGNATURE 重试这些步骤。你只需要准备一个有 USDC 的钱包，并选择希望使用的网络。

如果你要让自己的 API 也支持 X402 收款，则需要阅读 Facilitator 文档，理解 paymentRequirements、paymentPayload、/verify 和 /settle 的关系。

支持状态

Ace Data Cloud X402 已在公开 API、官方 SDK、Facilitator 和链上结算路径完成验证。下表按开发者接入时最常用的能力维度汇总当前状态。

能力 状态 说明
402 discovery 可用 https://x402.acedata.cloud/.well-known/x402 返回公开发现文档。
API 402 accepts 可用 未支付请求会返回 Base、SKALE 和 Solana 的可用 payment requirement。
TypeScript SDK 可用 @acedatacloud/sdk 与 @acedatacloud/x402-client 可自动处理 402、签名和重试。
Python SDK 可用 acedatacloud 与 acedatacloud-x402 可自动处理 402、签名和重试。
Base exact 已链上验证 适合固定金额 API 和订单支付。
Base upto 已链上验证 适合聊天补全等后置计量 API，当前唯一提供 upto 的网络。
SKALE exact 已链上验证 适合低 gas 成本的 EVM 支付场景。
Solana exact HTTP paid retry 已验证 已验证 API paid retry 与模型响应；链上签名确认建议使用自有 Solana RPC 对账。
订单支付 已链上验证 Base exact 订单支付已完成链上结算并更新订单状态。

以下输出仅用于说明已验证路径的返回形态。实际接入时，请始终以当前 API 返回的 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
33
34
35
36
37
38
39
40
41
42
 
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 eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact

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

说明：

  • npm 和 PyPI 包都已在干净环境安装并导入成功。
  • 未支付 API 请求返回 402，accepts 中包含 Base、SKALE 和 Solana 的可用支付方式。
  • accepts[].network 是 CAIP-2 标识，客户端选网时必须按 CAIP-2 字符串匹配。
  • TypeScript SDK 与 Python SDK 都能自动处理 402 并完成 paid retry。
  • Base exact、SKALE exact、Base upto 和订单支付都有可公开打开的 explorer 地址。
  • Base upto 的签名上限为 95215 atomic USDC，实际 settlement 为 3 atomic USDC，体现了后置计量按真实用量结算的特性。
  • Solana exact 已验证 HTTP 402 -> HTTP 200 和模型输出。由于公开 RPC 查询可能限流，严格对账时建议使用自有 Solana RPC 或平台侧结算记录确认交易签名。

接入注意事项

开发者接入时，请优先关注当前请求返回的实时支付要求，而不是复制文档中的示例金额或地址：

  • accepts[].maxAmountRequired 是当前请求可签名的最大金额。
  • accepts[].asset 是本次请求要使用的 USDC 合约或 mint。
  • accepts[].extra.chainId、accepts[].extra.facilitatorAddress 和 accepts[].extra.verifyingContract 会参与 EVM typed data 签名。
  • upto 需要钱包先对目标链 USDC 授权 Permit2；未授权时会返回 PERMIT2_ALLOWANCE_REQUIRED。
  • 如果明确希望使用后置计量，请在 TypeScript SDK 中传入 preferScheme: 'upto'，否则 SDK 会选择该网络下服务器返回的第一个可用 requirement。

可以公开核验的范围

接入前可以先核验这些公开入口和 SDK 行为：

  • 未带 Authorization 或 PAYMENT-SIGNATURE 的 API 请求会返回 402 Payment Required，响应中的 accepts 是本次请求的唯一签名依据。
  • TypeScript SDK 和 Python SDK 都提供 payment handler，SDK 传输层在收到 402 后会调用 handler 并重试一次。
  • https://x402.acedata.cloud/.well-known/x402：返回 X402 discovery 文档和规范资源地址。
  • https://facilitator.acedata.cloud/supported：返回 Facilitator 支持的网络与 scheme。
  • X402Client 仓库包含高级链上验证工具，可用于确认签名、重试和 settlement 行为；工具输出不替代线上 API 返回的 accepts。

upto 属于后置计量结算，适合聊天补全、模型调用等真实用量在响应后才知道的 API。当前只有 Base 提供 upto；如果签名验证失败，请检查 chain id、facilitator 地址、spender、USDC 合约和 Permit2 allowance 是否与 402 响应一致。

相关文章