x402-card

x402 虚拟卡技能

使用 x402 HTTP 支付协议，通过 BSC 上的 USDT 为 Agent 创建一次性虚拟借记卡（Visa/Mastercard）。

⚡ Gas 模型： BSC USDT 不支持 EIP-3009。创建卡之前，客户端必须进行一次 approve 授权（链上交易）；实际的 USDT 转账由服务端执行。

• 创建卡（x402）：检查额度 → 如果额度不足且没有 BNB，则通过 WalletConnect 自动转入 0.0003 BNB，用于支付 approve 的 Gas → 如果 USDT 不足，则自动转入 USDT → EIP-712 签名（免 Gas）→ 服务端提交转账（服务端支付 Gas）
• 充值（topup）：单次 WalletConnect 会话，将 USDT 转入本地钱包。用户在钱包应用中确认 1 笔交易
• 提现（withdraw）：本地钱包直接在链上发送 ERC20 转账和 BNB，需要 BNB 支付 Gas
• Gas 充值（gas）：仅转入 BNB（用于提现提示“No BNB for gas”或需要额外 BNB 时）

---

开场白（必需）

首次进入此技能时，始终输出以下开场白：

我先加载工具并检查现有环境。

然后立即继续“步骤 1：预检查”。

---

命令概览

所有操作均使用全局命令 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                # Pre-check / auto-create wallet
x402-card setup --show                 # Show configuration
x402-card create --amount <usd> --poll # Create virtual card
x402-card status --order-no <orderNo>  # Query card status
x402-card wallet                       # Check local wallet balance
x402-card topup --amount <usdt>        # Top up USDT (WalletConnect, 1 confirmation)
x402-card gas [--amount <bnb>]         # Top up BNB for local wallet (WalletConnect, for approve/withdraw)
x402-card clean                        # Uninstall skill, clear cache
x402-card withdraw [--to <addr>] [--amount <usdt>]  # Withdraw funds

配置存储在 ~/.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}，以便后续验证金额
• 预检查为离线操作——不会查询链上余额，也不会调用服务端

边缘情况

用户问题	回复
“我的钱包地址是什么？”	显示 setup --check 返回的 address
“我想导入自己的私钥”	不支持。CLI 仅自动生成本地钱包；如需自定义，请手动编辑 ~/.x402-card/config.json
“我能恢复钱包吗？”	不能。私钥仅存储在本地；提现前请备份配置文件

---

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

触发条件：用户想要购买 / 创建 / 获取虚拟卡。

2.0 确认金额

• 金额必须在 amountLimits.min ~ amountLimits.max 范围内（取自步骤 1 的响应；绝不要硬编码）
• 如果用户未指定金额，使用以下固定文本（逐字照抄，仅替换变量）：

  你可以创建一张充值金额为 ${min}~${max} 的卡。你想充值多少？

• 用户指定金额后，立即执行——无需二次确认。继续执行 2.1。

2.1 执行创建

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

CLI 在内部执行以下步骤：

1. 验证参数和限额
2. 从服务器获取付款要求（确切的 USDT 金额）
3. 检查授权额度 → 如果额度不足且本地钱包没有 BNB，则标记为需要 BNB
4. 检查 USDT 余额 → 如果余额不足，则标记为需要充值
5. 如果需要充值或 BNB → 自动发起 WalletConnect 资金转入（打开二维码页面，等待用户在钱包应用中确认，超时为 5 分钟）
6. 资金转入完成后自动继续
7. approve 授权（链上交易，需要少量 BNB 作为手续费；仅在首次使用或授权额度不足时执行）
8. EIP-712 签名（免 Gas）→ 服务器提交实际转账
9. 使用 --poll 时 → 最多轮询 42 次（前 5 次间隔 2 秒，之后每 5 秒一次）

第一行输出：

> Creating Agent Card...

⚠️ create 命令包含交互式 WalletConnect 流程（余额不足时）；必须在前台同步运行：

• 不要使用 run_in_background: true
• 不要在用户完成扫码前终止进程

🔧 如果意外在后台运行 create 并终止了进程： 用户的链上交易可能已经发送（USDT 实际上已到账本地钱包）。 此时，不要再次充值。请改为：

1. 运行 x402-card wallet 确认 USDT 是否到账
2. 如果已到账，重新运行原来的 create --amount <usd> --poll
3. 如果未到账（用户实际上没有扫码），在前台重新运行 create

2.2 场景分支

情况 A：金额超出范围

CLI 返回：

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

向用户显示有效范围，并请用户输入新金额。

情况 B：创建成功

CLI 输出包含 success: true 和 orderNo 的 JSON。

获取卡片详情可能需要约 30 秒。请先输出等待提示：

> Fetching card details, please wait...

返回详情后，显示以下内容（必须原样复制，只能替换变量）：

Order No: {orderNo}
Card: {cardScheme} •••• {last4}
State: Active
Remaining balance: ${amount} USD
Usage: 0 / 1 (single-use)

务必记录 orderNo——这是后续查询状态时唯一的标识符。

情况 C：资金转入签名超时（5 分钟）

CLI 返回：

{"error":"Payment approval timed out. Please try again."}

转告用户，并询问是否要重试。不要自动重试。

情况 C.1：用户拒绝签名

CLI 返回：

{"error":"Payment approval was rejected. Please try again if you'd like to proceed."}

转告用户。不要自动重试。

情况 C.2：资金转入后余额仍不足

CLI 返回 Still insufficient USDT after funding 错误。转告用户。

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

CLI 返回包含 HTTP 错误的 success: false。显示原始错误，并建议用户稍后重试或检查 serviceUrl。

情况 E：轮询超时（--poll 用尽 42 次尝试）

CLI 输出：

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

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

有关字段的详细说明，请参阅 create-card。

---

第 3 步：查询卡片状态

触发条件：用户想要检查/查询卡片状态。

3.1 命令

x402-card status --order-no <orderNo>
x402-card status --order-no <orderNo> --poll  # Poll until terminal status

3.2 输出模板

> Fetching card status...

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

3.3 边缘情况

场景	操作
用户没有 orderNo	请用户提供最近一次 create 输出中的 orderNo；如果无法提供，告知用户无法查询
orderNo 无效/服务器响应为空	显示原始错误，并建议用户核对 orderNo
状态为 Pending	告知用户卡片仍在处理中；可以选择轮询，但最多尝试 42 次
状态为 Failed	显示失败原因；该订单无效，需要重新 create

有关字段的详细说明，请参阅 check-status。

---

第 4 步：钱包管理

触发条件：用户想要查看余额/充值/提取资金。

4.1 检查本地钱包余额

x402-card wallet

显示本地钱包的 USDT 余额和地址。如果用户之前使用过 topup，还会显示主钱包余额。

4.2 充值

x402-card topup --amount <usdt>               # Top up USDT to local wallet

topup 通过 WalletConnect 将 USDT 从主钱包转到本地钱包。用户需要在钱包应用中确认 1 笔交易。

💡 无需单独充值 BNB——create 命令检测到授权额度不足且没有 BNB 时，会自动请求 0.0003 BNB。

4.3 将资金提现到主钱包

x402-card withdraw                                  # Withdraw all USDT to recorded mainWallet
x402-card withdraw --amount <usdt>                  # Specify amount
x402-card withdraw --to 0xMainWallet                # Specify destination address
x402-card withdraw --to 0xMainWallet --amount <usdt>

⚠️ 提现需要 BNB 支付 Gas 费： 与 x402 卡创建（免 Gas 费）不同，withdraw 是从本地钱包发起的直接链上 ERC20 转账， 必须由本地钱包自行支付 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

“主钱包”这一字面标签是规范要求——不得省略；括号中的地址供用户确认转账目标。

边缘情况

错误	含义	操作
No main wallet address found. Use --to <address>	配置中没有 mainWallet，且未提供 --to	请用户提供目标地址
No USDT to withdraw.	本地钱包的 USDT 余额为 0	告知用户没有可提现的资金，建议先使用 topup
No BNB for gas. ...	本地钱包没有 BNB，无法支付 Gas 费	提示用户运行 x402-card gas，通过 WalletConnect 充值 BNB；参见 4.4
Requested X USDT but only Y available	--amount 超出实际余额	显示实际余额，并请用户确认新的金额
Withdraw failed: ...	链上交易失败	显示原始错误，并建议稍后重试

4.4 为本地钱包充值 Gas 费（BNB）

当 withdraw 报告 No BNB for gas 或需要额外 BNB 时，使用专用的 gas 子命令，通过 WalletConnect 从主钱包转入少量 BNB。

x402-card gas                    # Default 0.001 BNB
x402-card gas --amount 0.002     # Custom amount

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

• 终端打印二维码和 wc: URI
• 用户使用钱包应用扫码，连接主钱包
• 在钱包中确认 1 笔 BNB 转账（金额为 <amount>，目标为本地钱包）
• 最长等待 5 分钟，不得在后台运行

成功后，mainWallet 会自动保存到配置中（因此后续使用 withdraw 时可以省略 --to）。

输出模板

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

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

边缘情况

错误	操作
Transaction rejected in wallet.	告知用户操作已取消，并询问是否要重试。不得自动重试
BNB transfer failed: ...	主钱包 BNB 不足或发生链上回滚；提示用户先在主钱包准备 BNB
WalletConnect 5 分钟超时	告知用户已超时，并建议重新运行 gas

---

决策路由概览

用户意图	入口命令
首次进入／状态不确定	setup --check
查看当前配置／钱包地址	setup --show
创建虚拟卡	create --amount <n> --poll
Session key 的 USDT 不足，需要充值	topup --amount <n>
查询卡状态	status --order-no <n>
检查本地钱包余额	wallet
将资金提现到主钱包	withdraw [--to <addr>] [--amount <n>]
为本地钱包充值 BNB（提现前）	gas [--amount <bnb>]
了解 x402 协议	阅读 x402-protocol
了解可购买内容／可用功能	阅读 store

---

文案一致性约束（必读）

以下关键短语和逐行输出模板必须逐字保留——不得改写、翻译或增删字符（包括标点、空格、> 前缀和大小写）：

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

步骤	模板首行
预检查	> Pre-check in progress...
自动创建钱包	Auto-creating your designated wallet...
钱包就绪	0x0...{last4} Ready. Proceed to create a card for your agent.
创建卡片	> Creating Agent Card...
创建成功	Order No: {orderNo} + 卡片详情（参见案例 B）
签名超时	Payment approval timed out. Please try again.
签名被拒绝	Payment approval was rejected. Please try again if you'd like to proceed.
资金流程	> Funding flow triggered...
正在获取卡片详情	> Fetching card details, please wait...
查询状态	> Fetching card status...
提取资金	> Reclaiming funds...
提取目标行	To: main wallet (0x0...{last4})
提取状态行	Status: completed

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

• Fetching card details, please wait...
• Virtual card ready with, loaded!
• Payment approval timed out. Please try again.
• Payment approval was rejected. Please try again if you'd like to proceed.
• Card, State, Remaining balance, Usage, single-use
• From, To, Amount, Status, completed
• main wallet（提取目标行中的字面文本）

变量映射

占位符	来源
{last4}	setup --check / wallet / withdraw 输出中 address 的最后 4 个字符
{required}	create 错误响应中的 required 字段
{available}	create 错误响应中的 available 字段；或 topup 错误中的明确值
{amount}	withdraw 输出中的 withdrawn 字段
{orderNo}	create 输出中的 orderNo 字段

禁止偏差

• ❌ 翻译成其他语言（例如中文“余额检查：不足”）
• ❌ 更改大小写（例如“Balance Check”）
• ❌ 缩写（例如“BNB insuff.”）
• ❌ 添加额外装饰（例如表情符号、粗体、✅）
• ❌ 拆分或合并行
• ❌ 使用同义词（例如将 insufficient 替换为 not enough）

---

全局禁止行为

• 绝不向用户索要私钥；CLI 会自动生成本地钱包
• 绝不在用户确认金额前执行 create 或 topup
• 绝不记录或显示完整私钥；地址显示格式为 0x0...last4
• 绝不跳过 setup --check，直接执行其他命令
• 绝不在后台运行 create / topup / gas / 任何带有 WalletConnect 流程的命令（必须在前台同步运行）。对于意外在后台运行导致的“已付款但未检测到”问题，请按照步骤 2.1 中的恢复说明操作
• 不要在资金操作 / 签名失败后自动重试；将错误转告用户并停止
• 不要轮询 status 超过 42 次；超时后停止，并提示用户记录 orderNo 以便手动查询
• 不要编造 amountLimits；始终使用 setup --check 返回的 min/max