x402 Virtual Card Skill

CLI Tool

npx @aeon-ai-pay/x402-card

# First time: provide your EVM wallet private key (service URL has a built-in default)
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)
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

Configuration

~/.x402-card/config.json

privateKey

1. CLI flags:

   --private-key

   ,

   --service-url

2. Environment variables:

   EVM_PRIVATE_KEY

   ,

   X402_CARD_SERVICE_URL

3. Config file:

   ~/.x402-card/config.json

   (set via

   setup

   command)

Step 0: Check Config and Version

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

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

0b. Check config

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.

Decision Tree

1. User wants to BUY / CREATE a virtual card

• 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".

2. User wants to CHECK card status

• Read check-status for status query details.
• Requires an

  orderNo

  from a previous creation.

3. User wants to SETUP or UPDATE config

• 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).

4. User wants to understand the PROTOCOL

• Read x402-protocol for how x402 works.

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.

Insufficient Balance Handling

"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.