x402-card

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

x402 Virtual Card Skill

x402 虚拟卡技能

Purchase virtual debit cards (Visa/Mastercard) by paying with USDT on BSC via the x402 HTTP payment protocol.

通过x402 HTTP支付协议，在BSC网络上使用USDT支付购买虚拟借记卡（Visa/Mastercard）。

CLI Tool

CLI 工具

All operations use

npx @aeon-ai-pay/x402-card

bash

undefined

所有操作都使用

npx @aeon-ai-pay/x402-card

命令：

bash

undefined

First time: provide your EVM wallet private key (service URL has a built-in default)

首次使用：提供你的EVM钱包私钥（服务URL有内置默认值）

npx @aeon-ai-pay/x402-card setup --private-key 0x...

Show current config

展示当前配置

npx @aeon-ai-pay/x402-card setup --show

Create a virtual card ($5 USD, auto-poll status)

创建一张虚拟卡（面值5美元，自动轮询状态）

npx @aeon-ai-pay/x402-card create --amount 5 --poll

Check card status

查询卡片状态

npx @aeon-ai-pay/x402-card status --order-no <orderNo>

Check wallet balance

查询钱包余额

npx @aeon-ai-pay/x402-card wallet

undefined

npx @aeon-ai-pay/x402-card wallet

undefined

Configuration

配置说明

Config is stored at

~/.x402-card/config.json

(file permission 600). Only

privateKey

is required — service URL has a built-in default.

Priority (high to low):

CLI flags:
```
--private-key
```
,
```
--service-url
```
Environment variables:
```
EVM_PRIVATE_KEY
```
,
```
X402_CARD_SERVICE_URL
```
Config file:
```
~/.x402-card/config.json
```
(set via
```
setup
```
command)

配置存储在

~/.x402-card/config.json

（文件权限为600），仅需要配置

privateKey

字段——服务URL有内置默认值。

配置优先级（从高到低）：

CLI参数：
```
--private-key
```
、
```
--service-url
```
环境变量：
```
EVM_PRIVATE_KEY
```
、
```
X402_CARD_SERVICE_URL
```
配置文件：
```
~/.x402-card/config.json
```
（通过
```
setup
```
命令设置）

Step 0: Check Config and Version

步骤0：检查配置和版本

Before ANY operation (create, wallet, status), run these two checks:

在执行任何操作（创建卡片、查询钱包、查询状态）之前，先运行以下两项检查：

0a. Auto-upgrade skill (run once per session)

0a. 自动升级技能（每个会话运行一次）

bash

npx @aeon-ai-pay/x402-card upgrade --check

```
"upToDate": true
```
→ skip.

"upToDate": false

→ inform user and run upgrade:

bash

npx @aeon-ai-pay/x402-card upgrade

bash

npx @aeon-ai-pay/x402-card upgrade --check

返回
```
"upToDate": true
```
→ 跳过升级。

"upToDate": false

→ 告知用户并运行升级命令：

bash

npx @aeon-ai-pay/x402-card upgrade

0b. Check config

0b. 检查配置

bash

npx @aeon-ai-pay/x402-card setup --check

Exit code 0 +
```
"ready": true
```
→ proceed to user intent.
Exit code 1 +
```
"ready": false
```
→ only
```
privateKey
```
is needed (service URL has a built-in default). Ask user:

"Please provide your EVM wallet private key (BSC network). It will be stored locally at ~/.x402-card/config.json with restricted file permissions and never transmitted elsewhere."

Then run:

bash

npx @aeon-ai-pay/x402-card setup --private-key <key>

Do NOT ask for service URL unless the user explicitly wants to change it.

bash

npx @aeon-ai-pay/x402-card setup --check

退出码为0 + 返回
```
"ready": true
```
→ 继续处理用户需求。
退出码为1 + 返回
```
"ready": false
```
→ 仅需要提供
```
privateKey
```
（服务URL有内置默认值），询问用户：

"请提供你的EVM钱包私钥（BSC网络），它将被本地存储在~/.x402-card/config.json中，文件权限受限，绝不会被传输到其他地方。"

之后运行命令：

bash

npx @aeon-ai-pay/x402-card setup --private-key <key>

除非用户明确想要修改，否则不要询问服务URL。

Decision Tree

决策流程

After config is verified, determine user intent and route:

配置验证通过后，判断用户意图并执行对应流程：

1. User wants to BUY / CREATE a virtual card

1. 用户想要购买/创建虚拟卡

Read create-card for the full workflow.
Amount limit: minimum $0.6, maximum $800 USD per card. IMPORTANT: Do NOT invent different limits — the exact range is $0.6 to $800.
CLI will auto-check wallet balance before payment. If insufficient, it reports the shortfall.
MUST confirm amount with the user before running the create command. Show the exact limits: "$0.6 ~ $800 USD".

查看 create-card 了解完整工作流。
金额限制：单张卡片最低0.6美元，最高800美元。重要提示：不要自行修改限制，准确范围就是0.6到800美元。
CLI会在支付前自动检查钱包余额，如果余额不足会提示差额。
运行创建命令前必须和用户确认金额，告知准确限制："$0.6 ~ $800 USD"。

2. User wants to CHECK card status

2. 用户想要查询卡片状态

Read check-status for status query details.
Requires an
```
orderNo
```
from a previous creation.

查看 check-status 了解状态查询详情。
需要提供之前创建订单返回的
```
orderNo
```
。

3. User wants to SETUP or UPDATE config

3. 用户想要设置或更新配置

Read wallet-setup for configuring the EVM wallet.
Must be done before any card purchase.

To update, run

setup

with only the field to change:

bash

# Update private key
npx @aeon-ai-pay/x402-card setup --private-key <new-key>
# Update service URL (optional, only if user explicitly requests)
npx @aeon-ai-pay/x402-card setup --service-url <new-url>

After update, run
```
setup --show
```
to confirm (private key is masked).

查看 wallet-setup 了解EVM钱包配置方法。
必须在任何卡片购买操作前完成配置。

如需更新，只需要在

setup

命令后带上要修改的字段即可：

bash

# 更新私钥
npx @aeon-ai-pay/x402-card setup --private-key <new-key>
# 更新服务URL（可选，仅当用户明确要求时使用）
npx @aeon-ai-pay/x402-card setup --service-url <new-url>

更新完成后，运行
```
setup --show
```
确认配置（私钥会被掩码处理）。

4. User wants to understand the PROTOCOL

4. 用户想要了解协议细节

Read x402-protocol for how x402 works.

查看 x402-protocol 了解x402的工作原理。

Anti-patterns

反模式

NEVER proceed with payment without explicit user confirmation of the amount.
NEVER log or display the full private key. Mask it as
```
0x...last4
```
.
NEVER skip the wallet setup check before attempting a purchase.
DO NOT poll status more than 10 times. If still pending, inform the user and stop.

未获得用户对金额的明确确认前，绝对不要继续支付流程。
绝对不要记录或展示完整私钥，需将其掩码为
```
0x...最后4位
```
的格式。
尝试购买前绝对不要跳过钱包设置检查步骤。
状态轮询不要超过10次，如果仍处于待处理状态，告知用户后停止轮询。

Insufficient Balance Handling

余额不足处理

When create returns

"error": "Insufficient USDT balance"

, present to user:

Wallet USDT balance is insufficient.
- Required: {required}
- Available: {available}
- Shortfall: {shortfall}

Please transfer at least {shortfall} USDT (BEP-20) to your wallet:
  {address}

Note: Send USDT on the BSC (BNB Smart Chain) network only. Transfers on other networks (ERC-20, TRC-20, etc.) will result in loss of funds.

After depositing, run the card creation again.

Do NOT attempt to transfer funds on behalf of the user. Depositing is the user's responsibility.

当创建接口返回

"error": "Insufficient USDT balance"

时，向用户展示以下内容：

Wallet USDT balance is insufficient.
- Required: {required}
- Available: {available}
- Shortfall: {shortfall}

Please transfer at least {shortfall} USDT (BEP-20) to your wallet:
  {address}

Note: Send USDT on the BSC (BNB Smart Chain) network only. Transfers on other networks (ERC-20, TRC-20, etc.) will result in loss of funds.

After depositing, run the card creation again.

不要尝试代用户转账，充值操作由用户自行负责。