X402 Python SDK 接入教程

X402 Python SDK 接入教程

💡 原文中文,约4700字,阅读约需12分钟。
📝

内容提要

本文介绍 X402 Python SDK 的接入方法:安装 acedatacloud 与 acedatacloud-x402,使用 EVM 或 Solana 钱包进行本地签名,并通过 create_x402_payment_handler 自动生成 PAYMENT-SIGNATURE 请求头。该 SDK 支持同步与异步客户端,以及 upto 后置计量方式,按实际用量结算,但需先完成 Permit2 授权;此外也可直接调用低层签名函数。

🔎

延伸解读

私钥本地签名,降低泄露风险

文章强调钱包私钥只在本地用于签名,不会发送给 Ace Data Cloud。EVM 通过环境变量读取私钥,Solana 使用 base58 编码的 secret key。这意味着接入时私钥管理责任仍在开发者一侧,应避免把私钥硬编码进代码或提交到仓库,生产环境需配合安全的密钥存储方式。

upto 按实际用量结算,但需先授权

对于聊天补全等成本需等响应结束才能确定的 API,可设置 prefer_scheme="upto" 优先使用后置计量。示例中结算金额为 3 atomic USDC,而非完整上限,说明按实际用量扣费。但首次使用前必须对目标链 USDC 完成一次 Permit2 approve,授权一个结算上限,实际金额不能超过该上限。

对账需自行保存交易凭证

文章建议对账时保存 tx hash、payer、completion id 和请求摘要。Base 示例的 settlement tx 可在 BaseScan 打开确认。Solana 路径虽在生产 API 返回 HTTP 200,但公开 RPC 查询遇到限流,未稳定确认链上 signature,因此需要自行用 Solana RPC 查询该次交易,不能仅凭接口返回判断链上状态。

普通业务优先用高层封装

SDK 提供 create_x402_payment_handler 自动生成 PAYMENT-SIGNATURE 请求头,同一 handler 可同时用于同步 AceDataCloud 和异步 AsyncAceDataCloud。低层 sign_evm_payment 更适合测试、代理层、网关集成或非官方 SDK 场景。另外当前 Python SDK 返回 dict,应使用下标访问结果,不要假设存在 .choices 属性。

❓

Q&A

X402 Python SDK 需要安装哪些包?

需要安装 acedatacloud 和 acedatacloud-x402。如果要用 upto 后置计量,还需安装 acedatacloud-x402[cli] 以获取 approve-permit2 CLI 工具。

如何用 EVM 钱包在 Python 中接入 X402 支付?

使用 EVMAccountSigner.from_private_key 加载私钥,然后通过 create_x402_payment_handler 指定 network='base' 和 evm_signer 创建支付处理器,再传给 AceDataCloud 客户端即可。私钥只在本地签名,不会发送给服务端。

Solana 钱包如何配置 X402 支付?

使用 SolanaKeypairSigner.from_base58 加载 base58 编码的 secret key,然后通过 create_x402_payment_handler 指定 network='solana' 和 solana_signer 创建支付处理器。Solana 路径会构造并提交 SPL USDC TransferChecked 交易,并将交易签名放入 PAYMENT-SIGNATURE envelope。

X402 SDK 支持异步客户端吗?

支持。同一个 payment handler 可以用于 AsyncAceDataCloud,用法与同步客户端类似,只需在异步客户端中传入相同的 payment_handler 即可。

upto 后置计量是什么?如何使用?

upto 是一种后置计量方式,按实际用量结算,而不是扣完整上限。使用时在 create_x402_payment_handler 中设置 prefer_scheme='upto'。首次使用前需要对目标链上的 USDC 完成一次 Permit2 授权(approve),可通过 CLI 或 approve_permit2 函数完成,该授权是幂等的。

如果不使用 SDK,如何直接生成 PAYMENT-SIGNATURE 请求头?

可以调用低层签名函数 sign_evm_payment,传入 requirement 和 EVMAccountSigner,得到 envelope 后将其 JSON 序列化并 base64 编码,即可作为 PAYMENT-SIGNATURE 请求头。低层函数适合测试、代理层、网关集成或非官方 SDK,普通业务代码建议优先使用 create_x402_payment_handler。

🏷️

标签

➡️

继续阅读