工作原理
详细流程
- 客户端发送请求到 ChainStream API,没有 API Key 或 Key 已过期。
-
网关返回 HTTP 402,消息指向
/x402/purchase。 -
客户端调用
GET /x402/purchase?plan=<plan>(不带支付头)。服务器返回 HTTP 402 及 x402 支付要求:解码后的 JSON 遵循 x402 v2 协议: -
客户端使用
@x402SDK 签署 USDC 转账,并携带支付证明重试GET /x402/purchase?plan=<plan>: -
服务器验证并结算支付,返回订阅详情:
客户端保存
apiKey用于后续所有 API 调用。
CLI 集成
ChainStream CLI 通过callWithAutoPayment 自动处理 x402 支付。当任何命令遇到 402 时,CLI 会引导你完成套餐选择和支付。
自动流程
当 CLI 遇到 402 响应时,会:- 从
/x402/pricing获取可用套餐并显示选择表格 - 提示你选择套餐
- 询问支付方式:x402(Base/Solana USDC)或 MPP(Tempo USDC.e)
- 如果选 x402:通过
@x402/fetch签名并发送支付,将返回的 API Key 保存到配置 - 如果选 MPP:打印
tempo request命令供手动购买 - 使用新 API Key 重试原始命令
如果你只有 API Key(没有钱包),CLI 会跳过 x402 并打印 MPP 购买指引。
钱包设置
CLI 需要一个有余额的钱包来进行 x402 支付:手动集成
对于自定义集成,可以使用@x402 包族实现 x402 流程。
依赖
使用 @x402/fetch(推荐)
最简单的集成方式 — 用 x402 支持封装标准fetch:
手动流程(高级)
完全控制支付流程:支持的支付链
零 Gas 费
ChainStream 运营自有的 x402 facilitator,代替 Agent 提交链上支付交易。这意味着:- 无需 Gas 费 — facilitator 代付所有 gas 费用(Base ETH / Solana SOL)
- Agent 钱包只需持有 USDC — 无需持有原生代币支付 gas
- Agent 签署 USDC 转账授权;facilitator 负责广播交易并支付执行费用
安全注意事项
- 支付上限:使用
@x402/fetch时始终设置maxAmount以防止意外扣费。 - 验证:facilitator 在结算前会在链上验证签名支付。无效签名会被拒绝。
- 幂等性:如果支付已结算但响应失败(网络错误),可以重新提交相同的
Payment-Signature。支付只会被消费一次。 - 合规:付款方地址在结算前会进行合规筛查。受制裁地址会被拒绝。

