X402 Card

命令一览

所有操作通过全局命令 x402-card。

📦 前置安装（仅一次）：

npm install -g @aeon-ai-pay/x402-card@latest

用全局命令而非 npx，可避免每次 4-5 秒的冷启动延迟。 升级：npm update -g @aeon-ai-pay/x402-card。

x402-card setup --check                # 预检查 / 自动建钱包
x402-card setup --show                 # 查看配置
x402-card create --amount <usd> --poll # 创建虚拟卡
x402-card status --order-no <orderNo>  # 查询卡片状态
x402-card wallet                       # 查询本地钱包余额
x402-card topup --amount <usdt>        # 自动充值 USDT + BNB（WalletConnect, 2 笔确认）
x402-card gas [--amount <bnb>]         # 给本地钱包充 BNB（WalletConnect, 用于 withdraw）
x402-card withdraw [--to <addr>] [--amount <usdt>]  # 提取资金

配置存储在 ~/.x402-card/config.json（权限 600）。 绝不向用户索要私钥；本地钱包私钥由 CLI 自动生成。

步骤 1：预检查（自动钱包初始化）

无论用户意图为何，首先运行：

x402-card setup --check

CLI 行为：

1. 读取 ~/.x402-card/config.json
2. 若 privateKey 缺失 → 用 viem.generatePrivateKey() 在本地生成新私钥并保存
3. 返回 JSON：{ ready, created, mode, address, mainWallet, serviceUrl, amountLimits }

输出模板

固定先输出一行进度提示：

> Pre-check in progress...

分支 A：钱包已存在（ready: true，created: false）

0x0...{last4} Ready. Proceed to create a card for your agent.

分支 B：本次自动创建（ready: true，created: true）

Auto-creating your designated wallet...
0x0...{last4} Ready. Proceed to create a card for your agent.

• {last4} 取自返回的 address 末 4 位
• 记录 amountLimits.{min,max} 供后续金额校验使用
• 预检查 不联网、不查链上余额、不调用服务端

边界场景

步骤 2：创建虚拟卡（含余额不足时自动充值）

触发：用户想 buy / create / get a virtual card。

2.0 金额确认

• 金额必须落在 amountLimits.min ~ amountLimits.max（来自步骤 1 返回，禁止硬编码）
• 若用户未指定金额，向用户展示有效区间并请求确认

2.1 执行创建

x402-card create --amount <usd> --poll

CLI 内部依次执行：

1. 参数与限额校验
2. 链上余额检查（USDT + BNB）
3. approve 授权（链上交易，消耗少量 BNB）
4. EIP-712 签名（免 gas）→ 服务端提交实际转账
5. 若带 --poll → 最多轮询 10 次，每次间隔 5 秒

输出首行：

> Creating Agent Card...

2.2 情况分支

情况 A：金额超出范围

CLI 返回：

{"error":"Amount must be at least $0.6 ...","min":0.6,"max":800}

向用户展示有效区间，请求重新确认。

情况 A.1：BNB 不足（approve 授权需要 gas）

CLI 返回：

{"error":"No BNB for approve transaction...","hint":"Run 'x402-card gas' or 'x402-card topup'"}

提示用户：

Balance check: no BNB for approve gas
→ Run 'x402-card topup' (includes BNB automatically)
→ Or run 'x402-card gas' to add BNB only

topup 会自动附带 0.001 BNB，用户在钱包内确认 2 笔交易（1 笔 USDT + 1 笔 BNB）。

情况 B：USDT 充足，创建成功

CLI 输出 JSON 包含 success: true 与 orderNo。展示：

Card created successfully.
Order No: {orderNo}
Card: ****{last4}
Status: {orderStatus}

务必记录 orderNo —— 这是后续状态查询的唯一凭证。

情况 C：USDT 余额不足 → 启动 WalletConnect 自动充值

CLI 返回：

{"error":"Insufficient USDT balance","required":"5 USDT (approx)","available":"0 USDT","shortfall":"5.000000 USDT","address":"0x..."}

向用户展示（文案必须完全一致，下方变量替换为实际值，其余文字逐字保留）：

Balance check: insufficient
Required amount: {required} USDT

→ Fund manually: 0x0...{session_last4}
→ Or auto-authorize transfer by link: WalletConnect (will open QR code)

征得用户同意后执行：

x402-card topup --amount <required>

⚠️ WalletConnect 流程为交互式，必须前台同步运行：

• 终端打印 QR 码 + wc: URI
• 用户用钱包 App（MetaMask、Trust Wallet、imToken 等）扫码连接
• 在钱包 App 中确认 1 笔 USDT 转账（金额 = <required>，目标 = 本地钱包）
• 全过程最长 120 秒

🚫 绝对禁止：

• 不要用 run_in_background: true 调用 topup / gas / connect 等 WalletConnect 命令
• 不要在用户扫码完成前 kill 进程
• 一旦命令进入后台或被中断，即使用户在钱包内已签名，CLI 也无法记录 mainWallet 与确认链上回执 → 会出现"已支付但未被检测"的假象

🔧 如果误把 topup 放到后台并已 kill： 用户的链上交易很可能已经发出（USDT 实际已到本地钱包）。 此时不要重新 topup，直接：

1. 跑 x402-card wallet 确认 USDT 已到账
2. 若到账，直接重跑原 create --amount <usd> --poll
3. 若未到账（用户也没真扫码），再前台 topup

输出阶段提示：

> Funding flow triggered...
Initializing WalletConnect session...
Waiting for wallet confirmation...
USDT transfer confirmed.

情况 C.1：用户在钱包内拒绝交易

CLI 返回 "error": "Transaction rejected in wallet."。 告知用户本次充值已取消，询问是否重试。不要自动重试。

情况 C.2：WalletConnect 超时（120s 未扫码或未确认）

CLI 返回连接/超时错误。告知用户超时，建议重新执行 topup。

情况 C.3：主钱包 USDT 不足（链上 revert）

CLI 返回 "error": "USDT transfer failed: ..."。展示：

> Funding flow triggered...

Source balance insufficient
Funding aborted
- 需要: {required}
- 可用: {available}
Add funds to continue

提示用户向其主钱包补 USDT，不要循环重试。

情况 C.4：充值成功 → 自动重试创建

topup 返回 success: true 后，CLI 已自动把 mainWallet 字段写回 config（提取资金时会用到）。

自动重试一次 create：

x402-card create --amount <usd> --poll

若再次失败，按对应分支处理；不要进入第三次重试。

情况 D：服务端网络/调用失败

CLI 返回 success: false 及 HTTP 错误。展示原始错误，建议用户稍后重试或检查 serviceUrl。

情况 E：轮询超时（--poll 用满 10 次）

CLI 输出：

Polling timeout after 10 attempts. Check manually with: x402-card status --order-no {orderNo}

告知用户卡片仍在处理中，记下 orderNo，稍后用步骤 3 查询。禁止继续轮询。

详细字段见 create-card。

步骤 3：查询卡片状态

触发：用户想 check / query card status。

3.1 命令

x402-card status --order-no <orderNo>
x402-card status --order-no <orderNo> --poll  # 轮询直至终态

3.2 输出模板

> Fetching card status...

Card: ****{last4}
State: {Active | Used | Expired | Pending | Failed}
Remaining balance: {balance} USD
Usage: {used} / {total} (single-use)

3.3 边界场景

详细字段见 check-status。

步骤 4：钱包管理

触发：用户想 查询余额 / 追加充值 / 提取资金。

4.1 查询本地钱包余额

x402-card wallet

输出本地钱包 USDT 余额及地址。若曾通过 topup 充值，会附带主钱包余额。

4.2 追加充值（同 2.C 流程）

x402-card topup --amount <usdt>               # USDT + 0.001 BNB（默认）
x402-card topup --amount <usdt> --skip-gas     # 仅 USDT，不附带 BNB

topup 默认在一次 WalletConnect 会话内同时转 USDT 和 0.001 BNB，用户需在钱包 App 内依次确认 2 笔交易：

1. 第 1 笔：USDT（指定金额）
2. 第 2 笔：0.001 BNB（用于 BSC USDT approve 授权的 gas）

若第 2 笔 BNB 失败（如拒绝或余额不足），不阻断——USDT 已到账，BNB 可后续用 x402-card gas 单独补充。

4.3 提取资金到主钱包

x402-card withdraw                                  # 提全部 USDT 到记录的 mainWallet
x402-card withdraw --amount <usdt>                  # 指定金额
x402-card withdraw --to 0xMainWallet                # 指定目标地址
x402-card withdraw --to 0xMainWallet --amount <usdt>

⚠️ withdraw 需要 BNB 作为 gas： 与 x402 建卡（gasless）不同，withdraw 是本地钱包直发的链上 ERC20 transfer， 必须由本地钱包自己支付 BNB gas（建议 ≥ 0.0005 BNB）。 用户需要从交易所或自己钱包向本地钱包地址手动转入少量 BNB 才能赎回。

目标地址解析优先级

1. CLI 参数 --to <address>
2. ~/.x402-card/config.json 中的 mainWallet（仅在用户曾用过 topup 后才会有）

输出模板（文案必须完全一致，仅变量替换）

> Reclaiming funds...

From: 0x0...{session_last4}
To: main wallet (0x0...{main_last4})

Amount: {amount} USDT
Status: completed

字面 "main wallet" 标签是规格要求，不要省略；括号内地址用于让用户确认转账目标。

边界场景

4.4 为本地钱包补 gas（BNB）

当 withdraw 报 No BNB for gas 时，使用专用 gas 子命令通过 WalletConnect 从主钱包转少量 BNB 进来。

x402-card gas                    # 默认 0.001 BNB
x402-card gas --amount 0.002     # 自定义金额

⚠️ 此命令为交互式 WalletConnect 流程（与 topup 同机制）：

• 终端打印 QR 码 + wc: URI
• 用户用钱包 App 扫码连接主钱包
• 在钱包内确认 1 笔 BNB 转账（金额 = <amount>，目标 = 本地钱包）
• 最长等待 120 秒，不可后台运行

成功后会自动把 mainWallet 写回 config（后续 withdraw 可省略 --to）。

输出模板

> Topping up gas...
Initializing WalletConnect session...
Waiting for wallet confirmation...
BNB transfer confirmed.

Local wallet: 0x0...{last4}
Balance: {bnb} BNB

边界场景

决策路由总览

文案一致性约束（必读）

以下 关键短语 与 行级输出模板 必须逐字一致，不得改写、翻译、增减字符（包括标点、空格、> 前缀和大小写）：

行级模板（必须完全一致）

关键短语（必须保留原词）

• Balance check、insufficient、Required amount
• Fund manually、auto-authorize transfer by link
• Source balance insufficient、Funding aborted、Add funds to continue
• Card、State、Remaining balance、Usage、single-use
• From、To、Amount、Status、completed
• main wallet（withdraw 目标行的字面文字）

变量映射

禁止的偏离

• ❌ 翻译为中文（如 "余额检查：不足"）
• ❌ 改大小写（如 "Balance Check"）
• ❌ 简写（如 "BNB insuff."）
• ❌ 加额外修饰（如 emoji、加粗、✅）
• ❌ 拆行或合并行
• ❌ 用同义词替换（如把 insufficient 换成 not enough）

全局禁止行为

• 绝不向用户索要私钥；本地钱包由 CLI 自动生成
• 绝不在未经用户确认金额的情况下执行 create 或 topup
• 绝不记录或显示完整私钥；地址展示为 0x0...last4 格式
• 绝不跳过 setup --check 直接执行其他命令
• 绝不让 topup / gas / 任何 WalletConnect 命令在后台运行（必须前台同步等待）。误后台导致的"已支付未检测"问题，按步骤 2 情况 C 的「如果误把 topup 放到后台」恢复
• 不要在 topup 失败后无限重试，按对应模板提示后停止
• 不要轮询 status 超过 10 次；超时即停，提示用户记下 orderNo 自行查询
• 不要自行编造 amountLimits；始终使用 setup --check 返回的 min/max