Python SDK 适合后端服务、数据任务、自动化 Agent 和批处理脚本。acedatacloud 负责 API 调用,acedatacloud-x402 负责签出 PAYMENT-SIGNATURE 请求头。
源码与包地址:
- SDK 仓库:https://github.com/AceDataCloud/SDK
- X402 Client 仓库:https://github.com/AceDataCloud/X402Client
- PyPI SDK:https://pypi.org/project/acedatacloud/
- PyPI X402 Client:https://pypi.org/project/acedatacloud-x402/
安装依赖
1 |
pip install acedatacloud acedatacloud-x402 |
如果要使用 upto,还需要一次性调用 Permit2 approve CLI,该 CLI 依赖 web3:
1 |
pip install 'acedatacloud-x402[cli]' |
干净 Python venv 的安装和导入检查输出:
1 |
acedatacloud 2026.4.26.1 |
结果说明:
acedatacloud和acedatacloud-x402均可从 PyPI 安装并导入。pip install 'acedatacloud-x402[cli]'会带上approve-permit2CLI,用于upto前置授权。
Base 示例
下面示例不需要 API Token。钱包私钥只在本地签名,不会发送给 Ace Data Cloud。
1 |
import os |
Python SDK 当前返回的是 dict,所以示例使用 res["choices"][0]["message"]["content"]。不要直接假设它一定有 .choices 属性。
Solana 示例
Solana 使用 base58 编码的 secret key:
1 |
import os |
Solana 路径会构造并提交 SPL USDC TransferChecked 交易,然后把交易签名放进 PAYMENT-SIGNATURE envelope。
Solana paid retry 在生产 API 上已返回 HTTP 200 和 ADC_SOLANA_E2E_OK。本次公开 RPC 查询遇到限流,未稳定确认链上 signature;需要对账时请用你自己的 Solana RPC 查询该次交易。
Async 客户端
同一个 payment handler 可以用于 AsyncAceDataCloud:
1 |
import os |
使用 upto 后置计量
聊天补全、模型调用等 API 的真实成本可能需要等响应结束后才知道。此时 API 可能同时返回 exact 和 upto。如果要优先使用 upto:
1 |
client = AceDataCloud( |
Base upto 的程序运行结果:
1 |
payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105 |
链上确认:
1 |
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 |
结果说明:
content ADC_BASE_UPTO_OK说明请求真实进入模型 API。settled value 3 atomic USDC说明upto按实际用量结算,而不是扣完整上限。settlement tx可在 BaseScan 打开,对账时保存 tx hash、payer、completion id 和请求摘要。
upto 使用 Permit2 授权一个上限,实际结算金额不能超过该上限。第一次使用前,需要对目标链上的 USDC 做一次 approve(Permit2, amount)。
CLI 方式:
1 |
X402_PRIVATE_KEY=0x... acedatacloud-x402 approve-permit2 --network base |
程序方式:
1 |
from acedatacloud_x402 import EVMAccountSigner, approve_permit2 |
该 helper 是幂等的。如果 allowance 已经足够,会返回 {"skipped": true},不会重复发链上交易。
低层签名
如果你不使用 SDK,也可以直接调用低层签名函数:
1 |
import base64 |
低层函数适合测试、代理层、网关集成或非官方 SDK。普通业务代码优先使用 create_x402_payment_handler。