MathWallet Agent CLI 使用教程

https://github.com/mathwallet/mathwallet-agent-skill/

面向 AI Agent 自动化的多链 Web3 钱包命令行工具。一套 BIP39 助记词派生所有链地址，支持 EVM（Ethereum、BSC、Polygon、Arbitrum、Optimism、Base、Avalanche 等）、Solana、Bitcoin、TRON、SUI、TON。功能包括：CAIP-2 链标识、余额查询（含 USD 估值）、代币发送、交易记录、离线签名、MathSwap 代币兑换、x402 HTTP 支付协议，以及面向 AI Agent 互联的 A2A JSON-RPC 服务器。

环境要求

依赖	版本
Node.js	≥ 20.0.0
pnpm	推荐 8+

安装

# 1. 安装依赖（在项目根目录）
pnpm install

# 2. 编译
pnpm build

# 3a. 直接运行（开发阶段）
node packages/mathwallet-cli/dist/index.js <命令>

# 3b. 全局链接（推荐日常使用）
cd packages/mathwallet-cli && npm link
mathwallet <命令>

# 3c. npm 全局安装（发布后）
npm install -g @mathwallet/agent-cli

初始化钱包

首次使用前必须执行一次：

mathwallet init

在 ~/.mathwallet/ 目录下创建：

.encryption-key — 32 字节机器绑定 AES 密钥（权限 0600）
wallet.enc — AES-256-GCM 加密的 BIP39 助记词（0600）

助记词不会显示在终端。迁移到新机器时，必须同时拷贝 wallet.enc 和 .encryption-key 两个文件。

链标识格式（CAIP-2）

--chain 参数支持三种等价格式：

格式	示例	说明
CAIP-2	`eip155:1`	推荐，无歧义
别名	`ethereum`	易读简写
Chain ID	`1`	仅 EVM 链可用

类型关键词（evm、solana、bitcoin、tron、sui、ton）可匹配该类型下所有链。

命令参考

大多数命令支持 --json 参数，以结构化 JSON 格式输出结果，替代默认的人类可读文本。格式统一为：

{ "success": true,  "data": { ... } }
{ "success": false, "error": "错误信息" }

出错时退出码为 1。支持 CAIP-2 的链会在 JSON 响应中包含 caip2 字段（如 "caip2": "eip155:1"）。export 命令仅支持交互模式，不支持 --json。

`status` — 检查钱包状态

mathwallet status
mathwallet status --json

检查 wallet.enc 和 .encryption-key 是否存在。执行任何钱包操作前建议先调用此命令。

`export` — 导出助记词

mathwallet export

必须在交互式终端中执行，并手动输入 EXPORT 确认；不支持 --json。

`chain` — 管理链配置

mathwallet chain list                # 列出所有链（CAIP-2 + 别名 + 类型 + 符号）
mathwallet chain list --json

# 更换 RPC 节点
mathwallet chain rpc --chain eip155:1 --rpc https://mainnet.infura.io/v3/YOUR_KEY
mathwallet chain rpc --chain ethereum  --rpc https://mainnet.infura.io/v3/YOUR_KEY

# 设置 API Key（TON、TRON 等需要认证的节点）
mathwallet chain apikey --chain ton --key YOUR_TONCENTER_KEY

# 添加自定义 EVM 链
mathwallet chain add \
  --name     mychain \
  --chain-id 999 \
  --rpc      https://rpc.mychain.com \
  --symbol   XYZ \
  --type     evm \
  --explorer https://explorer.mychain.com

`address` — 查看钱包地址

mathwallet address                   # 每种链类型各显示一个地址
mathwallet address --chain ethereum  # 指定单条链
mathwallet address --chain eip155:1  # 同上，CAIP-2 格式
mathwallet address --json

指定 --chain 时只输出地址字符串，方便脚本管道调用：

ADDR=$(mathwallet address --chain ethereum)

`balance` — 查询余额（含 USD 估值）

默认（不传参数）： 查询 10 条常用链 — EVM：ethereum、bsc、base、polygon、arbitrum；非 EVM：bitcoin、solana、sui、ton、tron。

mathwallet balance                                      # 默认 10 条链
mathwallet balance --chain ethereum                     # 单条链
mathwallet balance --chain ethereum,base                # 多条链（逗号分隔）
mathwallet balance --chain ethereum --chain base        # 多条链（重复参数）
mathwallet balance --chain evm                          # 配置中全部 EVM 链
mathwallet balance --all                                # 全部已配置链（慢，慎用）
mathwallet balance --chain ethereum --sort-by-value --json
mathwallet balance --refresh                            # 强制刷新代币列表缓存

# 查询指定合约代币（需单一具体 --chain）
mathwallet balance --chain eip155:1 --token-contract 0xdAC17F958D2ee523a2206206994597C13D831ec7 --json

参数	必填	说明
`--chain`	否	一条或多条链。可重复或逗号分隔。`evm` 匹配所有 EVM 链
`--all`	否	查询全部已配置链，非常慢，建议用 `--chain` 代替
`--token-contract`	否	查询指定合约地址的代币。需要且仅能配合单一具体链使用
`--sort-by-value`	否	按 USD 估值从大到小排序
`--refresh`	否	强制重新获取代币列表，忽略缓存

Assets API 不可用时降级使用缓存代币列表；若无缓存则仅返回原生币余额。
Bitcoin 余额包含未确认（mempool）UTXO；send 只能花费已确认 UTXO。
单条链失败不影响其他链继续查询（错误输出到 stderr）。

`send` — 发送代币或调用合约

# 发送前务必先 dry-run 确认手续费
mathwallet send --chain ethereum --to 0x收款地址 --token native --amount 0.1 --dry-run

# 发送原生币
mathwallet send --chain ethereum --to 0x收款地址 --token native --amount 0.1

# 发送 ERC-20 代币（--token 填合约地址）
mathwallet send --chain ethereum --to 0x收款地址 \
  --token 0xdAC17F958D2ee523a2206206994597C13D831ec7 --amount 100

# 任意合约调用（仅 EVM/TRON）
mathwallet send --chain ethereum --to 0x合约地址 --data 0x7ff36ab5... --value 0.1 --dry-run

参数	必填	说明
`--chain`	是	CAIP-2、别名或 chainId
`--to`	是	收款地址或合约地址
`--token`	是*	`native`、代币符号或 ERC-20 合约地址。*使用 `--data` 时可省略
`--amount`	是*	发送数量，人类可读格式（如 `0.1`、`100`）。*使用 `--data` 时可省略
`--data`	否	合约调用 hex calldata（仅 EVM/TRON）。填写后 `--token`/`--amount` 变为可选
`--value`	否	随 `--data` 附带的原生币数量（如 `"0.1"` ETH）。默认为 `0`
`--max-fee`	否	手续费上限，单位为原生币（各链含义不同，见注释）
`--dry-run`	否	只估算手续费，不广播

--max-fee 各链含义说明：

EVM / Bitcoin — 总手续费硬上限；超出则拒绝执行。
Solana — 设置计算单元价格（优先费），不强制限制总费用。
TRON — 设置 energy feeLimit（单位 TRX）。
SUI — 设置 gas budget（单位 SUI，内部转换为 MIST）。
TON — 忽略（手续费固定约 0.005 TON）。

`history` — 查看交易记录

mathwallet history --chain ethereum           # 最近 20 条（默认）
mathwallet history --chain eip155:1 --limit 50
mathwallet history --chain solana --token native --json
mathwallet history --chain ethereum --refresh

参数	必填	说明
`--chain`	是	指定具体链，不支持跨链合并查询
`--token`	否	按代币筛选：`native`、符号（如 `USDT`）或合约地址
`--limit`	否	返回条数，1–100，默认 20
`--refresh`	否	强制重新获取，忽略 5 分钟缓存

`sign` — 离线签名（不广播）

# EIP-712 结构化数据签名（仅 EVM）
mathwallet sign typed-data \
  --chain   eip155:1 \
  --domain  '{"name":"MyApp","version":"1","chainId":1,"verifyingContract":"0x..."}' \
  --types   '{"Transfer":[{"name":"to","type":"address"},{"name":"amount","type":"uint256"}]}' \
  --message '{"to":"0x...","amount":"1000000"}' \
  --json

# 消息签名（EVM 返回 0x hex，Solana 返回 base64）
mathwallet sign message --chain ethereum --message "Hello" --json
mathwallet sign message --chain solana   --message "Hello" --json

# 签名原始交易（不广播）
mathwallet sign transaction --chain eip155:1 --tx '{"to":"0x...","value":"0x0",...}' --json
mathwallet sign transaction --chain solana   --tx "<base64 未签名交易>" --json

`swap` — 代币兑换（MathSwap）

支持 MathSwap API 返回的所有链。完整执行（swap exec）仅支持 EVM 链；报价、状态查询、历史记录、代币搜索支持全部链。

原生币地址： 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee 代表该链原生币（ETH、BNB 等）。

# 列出 MathSwap 支持的所有链
mathwallet swap chains --json

# 查看支持 swap 的代币（已连接钱包时返回有余额的代币，否则返回默认推荐列表）
mathwallet swap tokens --chain ethereum --json

# 按 symbol 或合约地址搜索可 swap 的代币
mathwallet swap tokens --chain ethereum --search USDC --json

# 获取实时报价
mathwallet swap quote \
  --chain  ethereum \
  --from   0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to     0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 0.1 --json

# Dry-run：执行全部 API 步骤，不广播任何交易
mathwallet swap exec \
  --chain  ethereum \
  --from   0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to     0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 0.1 --dry-run --json

# 执行兑换
mathwallet swap exec \
  --chain  ethereum \
  --from   0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to     0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 0.1 --json

# 查询订单状态（exec 超时时使用）
mathwallet swap status --chain ethereum --order <order_no> --json

# 查看历史订单
mathwallet swap history --chain ethereum --json

swap exec 参数：

参数	必填	说明
`--chain`	是	EVM 链（如 `ethereum`、`bsc`、`base`）
`--from`	是	卖出代币地址（原生币填 `0xeee…eee`）
`--to`	是	买入代币地址
`--amount`	是	卖出数量，人类可读格式（如 `0.1`、`10`）
`--slippage`	否	滑点容忍度，百分比（如 `0.5`）。默认自动
`--max-price-impact`	否	超过此价格影响百分比时中止（如 `5`）。非 JSON 模式下超过 5% 会自动显示警告
`--dry-run`	否	执行全部 API 步骤（含 `create_order`），但不广播任何交易

swap exec 自动处理 ERC-20 授权：检查链上 allowance，不足时广播 approve 交易并等待确认，再执行 swap。
广播后每 3 秒轮询订单状态，最多等待 60 秒。超时后可用 swap status 手动查询。

`serve` — A2A Agent 服务器

启动一个 HTTP 服务器，将所有钱包功能通过 A2A（Agent-to-Agent）协议（JSON-RPC 2.0）暴露给其他 AI Agent。其他 AI Agent（Claude、Gemini 等）可通过标准协议发现并调用钱包能力，无需了解 CLI 命令。

mathwallet serve                                  # 监听 127.0.0.1:3000
mathwallet serve --port 8080                      # 自定义端口
mathwallet serve --auth                           # 启用认证（自动生成 token）
mathwallet serve --auth my-secret-token           # 启用认证（指定 token）
mathwallet serve --host 0.0.0.0 --auth            # 监听所有网卡（带认证）
mathwallet serve --cors "http://localhost:5173"   # 允许指定 CORS 来源

参数	必填	说明
`--port`	否	监听端口，默认 `3000`
`--host`	否	绑定地址，默认 `127.0.0.1`
`--auth`	否	启用 Bearer Token 认证。不传值则自动生成，传值则使用指定 token
`--cors`	否	允许的 CORS 来源（逗号分隔）。默认仅允许同源

接口：

GET /.well-known/agent.json — Agent Card，包含 16 个 skill 定义（公开，无需认证）
POST / — JSON-RPC 2.0：tasks/send、tasks/get、tasks/cancel、tasks/sendSubscribe（SSE 流式）

使用示例：

# 启动服务（带认证）
mathwallet serve --auth
# stderr: [a2a] auth token: <generated-token>

# 查看所有 skill（无需认证）
curl http://localhost:3000/.well-known/agent.json | jq '.skills[].id'

# 调用 skill（需认证）
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"jsonrpc":"2.0","method":"tasks/send","params":{"id":"t1","message":{"role":"user","parts":[{"type":"data","data":{"skill":"check_balance","params":{"chain":"ethereum"}}}]}},"id":1}'

安全机制：

默认绑定 127.0.0.1（仅本地访问），绑定到其他地址时会打印警告。
使用 --auth 可要求所有 POST 请求携带 Bearer Token 认证。
CORS 默认仅允许同源请求，可通过 --cors 指定允许的来源。
所有敏感 skill（send_token、send_contract、swap_exec、sign_message、sign_typed_data、sign_transaction）执行前均需 input-required 确认。
频率限制：每 IP 每分钟最多 60 次请求。

完整 A2A Skill 文档：packages/mathwallet-cli/skills/SKILL.md

`x402` — x402 HTTP 支付协议

自动处理 HTTP 402 Payment Required，使用 EIP-3009 链下授权，不发链上交易。

mathwallet x402 pay --url "https://api.example.com/protected" --json
mathwallet x402 pay --url "https://api.example.com/data" --chain eip155:8453 --json
mathwallet x402 pay --url "https://api.example.com/data" --method POST --body '{"q":"hello"}' --json

参数	必填	说明
`--url`	是	目标 URL，CLI 自动处理 402 挑战后重试
`--chain`	否	首选支付链（CAIP-2 或别名），不传则从 402 响应自动检测
`--method`	否	HTTP 方法，默认 `GET`
`--body`	否	请求体 JSON 字符串（用于 POST）
`--header`	否	额外请求头，格式 `Key:Value`，可重复

`cache` — 管理本地缓存

mathwallet cache status
mathwallet cache status --json

mathwallet cache clear
mathwallet cache clear --type prices
mathwallet cache clear --type tokens --json

支持的链

EVM 链（共用同一个 `0x…` 地址）

EVM 链列表从 MathWallet API 动态加载（24 小时缓存）。执行 mathwallet chain list 查看完整列表。

CAIP-2	别名	原生代币
`eip155:1`	`ethereum`	ETH
`eip155:56`	`bsc`	BNB
`eip155:137`	`polygon`	POL
`eip155:42161`	`arbitrum`	ETH
`eip155:10`	`optimism`	ETH
`eip155:8453`	`base`	ETH
`eip155:43114`	`avalanche`	AVAX
（更多 — 执行 `mathwallet chain list`）

非 EVM 链（静态配置）

CAIP-2	别名	代币	地址格式
`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d`	`solana`	SOL	base58，约 44 字符
`bip122:000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`	`bitcoin`	BTC	`bc1q…` bech32
`tron`	`tron`	TRX	`T…` base58，34 字符
`sui`	`sui`	SUI	`0x…` 64 位 hex
`ton`	`ton`	TON	`UQ…` base64url

常见问题

错误	解决方案
`Wallet not initialized`	执行 `mathwallet init`
`Failed to read encryption key`	`chmod 0600 ~/.mathwallet/.encryption-key`，或重新执行 `mathwallet init`（原数据不可恢复）
`No confirmed UTXOs available`（Bitcoin）	充值后等待至少一个区块确认
启动时出现 `bigint: Failed to load bindings`	非阻塞警告，不影响功能，可忽略

安全说明

机器绑定加密 — .encryption-key 与本机绑定，迁移时必须同时拷贝 wallet.enc + .encryption-key
私钥不落盘 — 每次命令在内存中派生，使用后立即丢弃
文件权限 — ~/.mathwallet/ 为 0700，所有钱包文件为 0600
无需密码 — 专为 AI Agent 自动化设计，无交互提示
发送前先 dry-run — 广播任何交易前先用 --dry-run 确认手续费

项目结构

mathwallet-agent-skill/
├── packages/
│   └── mathwallet-cli/
│       ├── src/
│       │   ├── index.ts         # CLI 入口
│       │   ├── commands/        # 各命令实现（含 serve）
│       │   ├── chains/          # 各链适配器
│       │   ├── lib/             # 工具库（加密、配置、余额、价格、swap）
│       │   └── a2a/             # A2A 协议服务器（skill、JSON-RPC、任务存储）
│       ├── dist/                # 编译产物
│       └── skills/SKILL.md      # AI Agent Skill 参考文档
└── README.md

环境要求

安装

初始化钱包

链标识格式（CAIP-2）

命令参考

status — 检查钱包状态

export — 导出助记词

chain — 管理链配置

address — 查看钱包地址

balance — 查询余额（含 USD 估值）

send — 发送代币或调用合约

history — 查看交易记录

sign — 离线签名（不广播）

swap — 代币兑换（MathSwap）

serve — A2A Agent 服务器

x402 — x402 HTTP 支付协议

cache — 管理本地缓存