跳转到主要内容
简而言之
AI 智能体可以通过开放的智能体支付协议,使用稳定币按请求为 API 和数据付费。借助 Blockradar,智能体从私钥始终保留在 Blockradar 内的钱包付款,使用的正是您已有的类型化数据签名端点。

支持的协议

您是向智能体出售服务?请参阅接收智能体支付。

前提条件

1

API 密钥

从 Blockradar 控制台 获取您的 API 密钥。进入 Developers 生成密钥。
2

EVM 主钱包

在控制台中,于 API 收费所在的链(例如 Base)上创建主钱包(参见创建主钱包)。通过 Blockradar 进行的智能体支付仅支持 EVM。
3

启用 USDC

在钱包上启用 USDC,以便跟踪余额和存款。参见资产管理。

为智能体设置独立预算

签名没有单笔付款的支出上限
任何持有可访问某个钱包的 API 密钥的人,都可以从该钱包或其地址签署任意金额的付款。Blockradar 不会限制智能体签署的金额。为智能体分配一个专用地址,只存放它被允许支出的资金,以限制行为异常的智能体或泄露的密钥可能造成的损失。
关闭自动归集的子地址非常适合作为智能体预算。向其中充值智能体可支出的金额,智能体的付款就永远不会超过该余额。
请在智能体的地址上保持 disableAutoSweep: true。如果开启自动归集,您为智能体充值的 USDC 会被归集到主钱包,智能体的付款将因资金不足而失败。
也可以从主钱包付款。在下面的示例中使用主钱包端点,并省略 addressId。此时主钱包的全部余额都在智能体的可支配范围内,因此仅在主钱包专供该智能体使用时才这样做。 在 Checkout 计划下,子地址相关操作不可用,请使用专用于该智能体的主钱包。

x402 工作原理

x402 是一种开放协议,允许 API 按请求收费:它以 HTTP 402 Payment Required 响应,调用方随后携带已签名的 USDC 付款重试请求。x402 涉及三方:买方(您的智能体)、卖方(被付费的 API),以及负责校验付款并将其提交上链的 facilitator。
1

API 请求付款

智能体调用付费端点。API 返回 402 Payment Required,以及列出其接受条件的 PAYMENT-REQUIRED 请求头:网络、代币、金额和 payTo 地址。
2

Blockradar 签署付款

智能体将其中一个选项转换为 EIP-3009 TransferWithAuthorization,并通过 Blockradar 的类型化数据端点进行签名。此时尚未向链上发送任何内容。
3

智能体携带签名重试

智能体重新发送请求,并在 PAYMENT-SIGNATURE 请求头中附上已签名的付款。
4

facilitator 完成结算

卖方的 facilitator 验证签名并将转账提交上链,由其自行支付 Gas。API 返回响应,结算结果位于 PAYMENT-RESPONSE 响应头中。
智能体的钱包需要 USDC,但不需要 Gas。签名只授权一笔向确定地址转账确定金额的交易,facilitator 无法更改其中任何一项。

使用 x402 付款

请先按照为智能体设置独立预算中的说明为智能体的地址充值。

方式 1:使用 x402 客户端 SDK

官方的 @x402/fetch 客户端会替您处理 402 交互。它只需要一个具有 address 和 signTypedData 方法的签名器。下面的适配器基于 Blockradar 的类型化数据端点实现了该签名器,因此密钥始终保留在 Blockradar 中。
JavaScript
为智能体付款的每个网络注册一个 scheme(测试时 Base Sepolia 使用 eip155:84532),并确保每个网络背后都有该链上的钱包。

方式 2:自行构建付款

不使用 SDK 或使用其他语言时,一次付款需要三次 HTTP 调用:首次请求、调用 Blockradar 签名,以及付费后的重试。以下步骤在 Base 上支付 0.01 USDC。

第 1 步:读取付款要求

调用 API。402 响应带有一个 base64 编码的 PAYMENT-REQUIRED 请求头。解码后如下所示:
在 accepts 中选择一个您的钱包可以支付的条目:
  • scheme 为 exact。
  • network 为钱包所在的链。eip155:8453 是 Base 主网。
  • extra.assetTransferMethod 不存在或为 eip3009。permit2 方式需要先进行链上代币授权,这会消耗 Gas,因此本指南不涉及。
amount 以代币的最小单位表示。USDC 有 6 位小数,因此 10000 即 0.01 USDC。

第 2 步:签署授权

根据付款要求构建 TransferWithAuthorization,并从智能体的地址签名:
如需改为从主钱包签名,请使用 POST /v1/wallets/{walletId}/signing/typed-data,并将 from 设为主钱包的地址。响应为标准的类型化数据响应;签名位于 data.signedTransaction.signature 中。

第 3 步:携带付款重试

将签名和授权封装到付款载荷中,进行 base64 编码,并在同一请求的 PAYMENT-SIGNATURE 请求头中发送:
JavaScript

第 4 步:检查结算结果

成功的响应包含一个 base64 编码的 PAYMENT-RESPONSE 响应头:
transaction 是 USDC 转账的链上哈希。如果付款失败,API 会再次返回 402,PAYMENT-RESPONSE 中会带有 errorReason,例如 insufficient_funds。
使用 x402 版本 1 的服务器与上述流程有四点不同:
  • 付款要求位于 402 响应的正文中,而不是请求头中。
  • 网络使用名称(base、base-sepolia),而不是 eip155:<chainId>。Base 的链 ID 为 8453;Base Sepolia 为 84532。
  • 金额字段为 maxAmountRequired,而不是 amount。
  • 付款放在 X-PAYMENT 请求头中,格式为 base64 编码的 JSON,包含 x402Version: 1、scheme、network 以及相同的 payload 对象;结算结果通过 X-PAYMENT-RESPONSE 返回。
使用 Blockradar 的签名步骤完全相同。

集成中容易出错的签名规则

每个签名都会被记录为一笔 SIGNED 交易,并触发 signed.success Webhook,为您的智能体授权的每笔付款提供审计记录。签名并不等于付款:只有当卖方的 facilitator 完成结算时,USDC 才会转移。当卖方不在 Blockradar 上时,结算会显示为从智能体地址发出的转账。对账时,请将 signed.success Webhook 与 PAYMENT-RESPONSE 标头中的链上交易进行匹配。

MPP 工作原理

MPP(Machine Payments Protocol)是一种按请求通过 HTTP 付费的开放协议。它的 EVM charge 与 x402 的工作方式相同:智能体通过 Blockradar 签署同样的 EIP-3009 TransferWithAuthorization,服务器将其在链上结算并支付 Gas,智能体的钱包需要 USDC,但不需要 Gas。不同之处在于签名外层的封装:

使用 MPP 付款

官方的 mppx 客户端会处理 MPP 交互(包括与 challenge 绑定的 nonce),并签署 EIP-3009 authorization 凭证。它接受一个 viem 账户,因此下面的适配器将 Blockradar 的类型化数据端点封装为一个 viem 账户。它发送的签名请求与 x402 相同。
JavaScript
maxAmount 是由客户端强制执行的单笔付款上限:超过该金额时,mppx 会在调用 Blockradar 之前拒绝付款,因此不会签署任何内容。Blockradar 本身不会限制其签署的金额,因此请务必设置该值。 对账时,请将 signed.success Webhook 与每个 Payment-Receipt 中的 reference(即链上交易哈希)进行匹配。
向 Blockradar 发送的签名请求与第 2 步中的相同,但有三点不同:
  • 从 WWW-Authenticate: Payment 请求头中读取 challenge。其 request 参数是 base64url 编码的 JSON,包含 amount、currency、recipient 和 methodDetails.chainId。
  • 将 nonce 设为 keccak256(abi.encodePacked(challenge.id, challenge.realm)),将 validBefore 设为 challenge 的 expires 时间。从代币合约中获取 domain.name 和 domain.version。
  • 以 Authorization: Payment <base64url JSON> 的形式发送凭证,其中回传 challenge,并附带 type: "authorization" 及已签名字段组成的 payload。
完整格式请参阅 MPP EVM charge 规范。

限制

  • 仅支持 EVM。 付款使用 EIP-712 类型化数据签名,而 Blockradar 仅在 EVM 链上支持该功能。不支持 Solana 及其他非 EVM 网络。
  • 仅支持 EIP-3009 付款。 支持具有 transferWithAuthorization 的代币,例如 USDC。不支持 x402 的 permit2 转账方式,以及 MPP 的 permit2、transaction 和 hash 凭证。
  • Tempo 上的 MPP 即将推出。 在此之前,暂不支持 Tempo charge 和 MPP session。
  • 不支持 Circle Gateway 纳米支付。 暂不支持 Circle 的批量亚美分付款选项。
  • 向另一家 Blockradar 商户付款。 当卖方同样使用 Blockradar 地址收款时,智能体的转出付款通常不会出现在其交易历史中,也不会触发 Webhook。余额是正确的。请根据 PAYMENT-RESPONSE 或 Payment-Receipt 中的交易哈希进行对账。

最佳实践

  • 在智能体中强制执行限额。 Blockradar 会签署来自有效 API 密钥的任何格式正确的请求。请在智能体代码中设置单笔和每日限额(使用 MPP 时,maxAmount 可覆盖单笔限额),并通过智能体地址的余额限制总风险敞口。
  • 每个智能体一个地址。 独立的预算可以清楚显示每个智能体花了多少钱,并让您通过清空其地址来停用某个智能体。
  • 签名前检查价格。 将 amount 与您的智能体为该资源最多应支付的金额进行比较,拒绝任何更高的价格。
  • 检查收款方。 如果您的智能体只为已知 API 付款,请维护一份 payTo(x402)或 recipient(MPP)地址白名单。
  • 使用 metadata 和 Webhook。 使用 metadata 标记智能体地址,并将 signed.success Webhook 与每个 PAYMENT-RESPONSE 或 Payment-Receipt 中的链上交易进行对账。
  • 锁定 API 访问。 通过 IP 白名单仅接受来自您自己服务器的 API 请求,使泄露的密钥无法在其他地方使用。
  • 先在 Base Sepolia 上测试。 在动用真实资金之前,使用测试网钱包(eip155:84532)以及来自水龙头的测试网 USDC。

API 参考