x402 教程：让你的 AI 代理用 USDC 为 AIHubMix 充值

AIHubMix 现已支持 USDC 充值。你的 AI 代理可以用钱包里的 USDC 为自己的账户充值：无需打开网页，也无需有人点击按钮。

通过 x402，单次充值最低可以只有 $1。代理可以边用边充，因此你不必提前存入大额余额。

整个过程分两步：先在网页和应用中准备好令牌、钱包和一些 USDC，然后用一条命令运行我们提供的现成充值脚本。付款后约 20 秒，额度就会到达你的账户。

如果需要，你可以跟着这个30 秒视频操作：

最简单的方法：如果你使用的 AI 工具可以运行终端命令，例如 Claude Code、Cursor 或 Codex，请先完成第 1 步，然后把本文的链接发给它，并说“帮我设置这个”。它会按照本文末尾的“给 AI 助手的说明”操作。令牌和私钥只需由你自己填写一次，不要发给 AI。

开始之前

• 金额只能是整数美元，默认每次充值为 $1 到 $10
• 每个账户每天最多创建 3 笔订单（按 UTC 时间计算）
• 仅支持 Base 主网上的 USDC，没有测试网，因此建议先从 $1 开始
• 此通道是为程序设计的，人无法在浏览器中付款。手动充值请继续使用支付宝或 Stripe

第 1 步：获取令牌、钱包和 USDC

这一步的所有操作都在网页或手机应用中完成。

1. 获取系统访问令牌

登录 aihubmix.com，打开个人设置，生成一个系统访问令牌（32 位字符串）。

请注意，这不是以 sk- 开头的 API 密钥，两者不能互换使用。

2. 创建付款钱包

在 MetaMask 或类似的钱包应用中，新建一个仅用于代理付款的账户。不要使用你的主钱包。然后：

• 复制该账户的地址（以 0x 开头）；下一步你需要向它转入 USDC
• 从账户详情中导出它的私钥，并保存在密码管理器中。任何拿到私钥的人都可以转移钱包中的资金

3. 购买 USDC 并转入此钱包

MetaMask 是钱包：私钥由你自己持有，脚本需要用它来签名。Coinbase 是交易所，用于购买加密货币。交易所账户中的资金不附带私钥，因此脚本无法使用。这就是为什么你要先在交易所购买，然后再把 USDC 转到上一步创建的钱包。

以 Coinbase 交易所为例（不是 Coinbase Wallet）：

1. 在 Coinbase 上购买 USDC
2. 将 USDC 发送到你复制的地址，并选择 Base 网络
3. 转入的金额略多于你计划的充值额，例如充值 $1 就转入 1.5 到 2 USDC

稍等片刻，然后打开 https://basescan.org/address/your-wallet-address。一旦看到 USDC 余额，就说明已到账。其他支持在 Base 网络提现 USDC 的交易所也可以使用；更多选项请参阅 Base 文档。

钱包不需要任何 ETH：付款的网络手续费由 FluxA 承担。

第 2 步：运行充值脚本

无需下载任何东西，也无需创建文件：uv 会从网上获取脚本并运行。打开终端（Windows 上为 PowerShell），复制粘贴以下命令。

1. 安装 uv（只需一次）

uv 是一个 Python 工具，可以为脚本运行准备好所需的一切。

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，关闭终端并重新打开。

2. 检查设置（不产生费用）

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

首次运行时，脚本会要求输入系统访问令牌（System access token）和钱包私钥（Wallet private key）。输入的内容不会显示在屏幕上；粘贴后按回车即可。接着它会询问是否保存（Save to ...? [Y/n]）。按回车保存，之后就不必再次输入。首次运行需要稍等片刻，因为 uv 正在进行初始化。

看到以下内容，说明设置完成：

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. 充值

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

末尾的 1 是以美元为单位的金额。如果一切顺利，你会看到：

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: credited 表示额度已到账。登录 aihubmix.com 即可看到余额增加；$1 对应 500,000 额度。

如果最后一行显示的是其他内容：

• failed：订单已关闭或已过期。如有需要可以重新运行，但这会占用当天的另一笔订单额度。
• pending：10 分钟内未确认到账。这并不代表失败，额度稍后会自动到账。请不要重新运行。

故障排查

如果在打印出 tradeNo 之后出现超时或网络错误，款项可能已经付出。请不要立即重新运行。几分钟后检查余额；如果没有到账，请携带 tradeNo 联系我们。

令牌和私钥保存在你电脑上的 ~/.aihubmix-topup.env 中（Windows 上位于用户文件夹中）。在 macOS 和 Linux 上，只有你自己的账户可以读取该文件。如需更改令牌或私钥，请编辑此文件。

接入你的代理

• 设置保存后，代理可以在需要额度时运行 uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 进行充值，无需有人在场
• 每天只允许 3 笔订单，因此要限制代理的充值频率，并且绝不要在循环中重试创建订单
• 将输出中的 tradeNo 和 txHash 保存到数据库或日志中，以便对账
• 长期使用时，请下载脚本并在运行前固定版本；运行前可以先阅读源代码
• 如果每次 $10 或每天 3 笔的限制不够用，请联系我们提高上限

给 AI 助手的说明

如果你是帮助用户设置 AIHubMix USDC 充值的 AI 助手，请按以下顺序操作：

1. 确认用户已完成第 1 步：拥有系统访问令牌，以及持有 Base 主网 USDC 的钱包及其私钥。如果没有，请先引导用户完成第 1 步。
2. 运行 uv --version 检查 uv 是否已安装。如果没有，请使用第 2 步中的命令进行安装。
3. 运行 uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check。
4. 如果它报告缺少令牌或私钥（Missing access token or private key），说明脚本已创建配置文件 ~/.aihubmix-topup.env。请让用户用文本编辑器打开并自行填写（macOS 上运行 open -e ~/.aihubmix-topup.env；Windows 上运行 notepad $HOME\.aihubmix-topup.env）。不要读取此文件，不要把令牌或私钥放入任何命令中，也不要要求用户把它们发给你。
5. 用户填写完成后，再次运行 check，直到看到 Access token and private key are fine. Ready to top up.。如果出现错误，请参照上方的故障排查表处理。
6. 充值会花费真实资金。在运行 uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount> 之前，请先与用户确认金额。

底层原理：脚本做了什么

脚本按顺序执行五项操作：

1. 检查余额：创建订单会占用当天的一笔订单额度，因此脚本会先确认私钥有效且 USDC 余额充足。
2. 创建订单：调用 POST /api/pay/fluxa/crt，获得付款链接和订单号 tradeNo。令牌会原样放入 Authorization 请求头中，不加 Bearer。业务错误同样以 HTTP 200 返回，因此脚本会检查响应中的 success 字段。
3. 检查付款请求：对付款链接发起 GET 请求，会返回 HTTP 402 及付款要求。签名前，脚本会检查四项内容：scheme 为 exact，network 为 eip155:8453，asset 为 Base 主网上的 USDC 合约，maxAmountRequired 等于金额乘以 1,000,000。只要有任何一项不符，脚本就会停止。
4. 签名并付款：脚本用私钥对 USDC 转账授权进行签名，放入 X-PAYMENT 请求头中，并再次向付款链接发送 GET 请求。返回 200 或 202 表示付款已提交；响应中的 txHash 即为本次付款的链上凭证。两次请求都不携带 AIHubMix 令牌。
5. 等待到账：每隔 8 秒调用一次 GET /api/pay/fluxa/qry?trade_no=...，直到状态变为 TRADE_SUCCESS。服务器每 5 秒才刷新一次，因此轮询得更快并没有帮助。

每个付款链接的有效期为 30 分钟，且只能支付一次。

用其他语言实现

付款链接返回的 402 响应如下所示：

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

签名采用 EIP-712 格式，基于 EIP-3009 中的 TransferWithAuthorization 结构体：

签名域：name = USD Coin，version = 2（如果 402 响应中存在 extra，则使用其中的值），chainId = 8453，verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913。

X-PAYMENT 请求头的值是以下 JSON 的 base64 编码：

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

参考资料

• x402 文档
• EIP-3009：Transfer With Authorization
• EIP-712：结构化数据的类型化哈希与签名
• Circle：USDC 合约地址
• uv 安装指南