LLM Wallet — 加密货币钱包与 x402 微支付

使用 llm-wallet 命令管理加密货币钱包，并在 Polygon 区块链上使用 USDC 稳定币向付费 API 发起微支付。

默认网络：Polygon 测试网（polygon-amoy）—— 适用于安全测试 协调器（Facilitator）：https://x402-amoy.polygon.technology

快速开始

# 创建钱包
llm-wallet create

# 查询余额
llm-wallet balance

# 设置支出限额（推荐）
llm-wallet set-limit --per-tx 0.10 --daily 5.00

# 查看交易历史
llm-wallet history

钱包管理

创建钱包

llm-wallet create [--label ]

创建一个带加密功能的 HD 钱包，返回钱包地址。

示例：

llm-wallet create --label "agent-wallet"

导入钱包

llm-wallet import --private-key  [--label ]

通过私钥导入已有钱包。

查询余额

llm-wallet balance

显示当前网络下的 USDC 余额及原生代币余额。

交易历史

llm-wallet history

查看该钱包发起的所有交易与支付记录。

支出限额

设置限额

llm-wallet set-limit --per-tx  --daily 

以 USDC 为单位设置单笔交易与每日支出上限。

示例：

llm-wallet set-limit --per-tx 0.10 --daily 5.00

查看限额

llm-wallet get-limits

查看当前支出限额及当日已用额度。

x402 支付

发起支付

llm-wallet pay  [--method GET|POST] [--body ]

向付费 API 接口发起 x402 微支付。

⚠️ 重要提示：发起任何支付前，必须获得用户明确授权！

示例：

# 向用户确认："我需要向 https://api.example.com/weather 发起支付，费用为 $0.001 USDC。是否批准？"
llm-wallet pay "https://api.example.com/weather?location=London"

标准流程：

1. 预检是否需支付：llm-wallet check-payment
2. 向用户展示：URL、预估费用、当前限额
3. 等待用户确认授权
4. 执行支付：llm-wallet pay
5. 支付完成后确认结果，并显示交易 ID

支付预检（Check Payment）

llm-wallet check-payment 

在不实际执行支付的前提下，检查钱包余额是否足以完成该笔支付。

动态 API 注册

注册 API

llm-wallet register-api  --name 

将一个付费 API 接口注册为可复用的工具。

示例：

llm-wallet register-api "https://api.example.com/weather" --name weather_api

列出已注册 API

llm-wallet list-apis

列出所有已注册的 API 工具。

调用已注册 API

llm-wallet call-api  [--params ]

执行已注册的 API 工具；若涉及支付，则仍需用户授权。

示例：

# 若费用大于 0，须先向用户请求授权
llm-wallet call-api weather_api --params '{"location": "London"}'

注销 API

llm-wallet unregister-api 

移除一个已注册的 API 工具。

卖家工具（高级）

验证支付

llm-wallet verify-payment --header  --requirements 

（卖家侧）验证来自买家的付款凭证。

生成支付要求

llm-wallet create-requirements --price  --pay-to 
 --url 

为受保护资源生成支付要求（Payment Requirements）。

安全规则

1. 网络默认值：除非另行配置，否则始终使用 polygon-amoy（测试网）
2. 强制授权：发起任何支付前均须获得用户明确授权
3. 限额校验：支付前必须检查当前支出限额
4. 交易日志：所有支付操作均按时间戳记录
5. 加密机制：钱包使用 AES-256-GCM 加密

配置

环境变量

• WALLET_ENCRYPTION_KEY — 钱包加密密钥（长度 ≥32 字符；如未提供则自动生成）
• WALLET_NETWORK — 网络选择（默认：polygon-amoy 或 polygon）
• FACILITATOR_URL — 自定义协调器 URL（自动配置）
• WALLET_MAX_TX_AMOUNT — 单笔交易限额覆盖值
• WALLET_DAILY_LIMIT — 每日限额覆盖值

网络信息

• Polygon 测试网（Amoy）：链 ID 80002，协调器：https://x402-amoy.polygon.technology
• Polygon 主网：链 ID 137，协调器：https://x402.polygon.technology

常见工作流

首次初始化

# 1. 创建钱包
llm-wallet create --label "my-agent"

# 2. 设置支出限额
llm-wallet set-limit --per-tx 0.10 --daily 5.00

# 3. 查询余额（初始为 0）
llm-wallet balance

# 4. 为钱包充值测试网 USDC
# 用户需访问：https://faucet.polygon.technology/

发起一笔支付

# 1. 支付前预检
llm-wallet check-payment "https://api.example.com/weather?location=London"

# 2. 向用户展示：URL、费用预估、当前限额
# 3. 向用户确认："是否批准向 https://api.example.com/weather 支付 $0.001 USDC？"

# 4. 若获批准，则执行支付
llm-wallet pay "https://api.example.com/weather?location=London"

# 5. 支付完成后确认，并显示交易 ID
llm-wallet history

注册一个付费 API

# 1. 注册 API
llm-wallet register-api "https://api.example.com/translate" --name translate_api

# 2. 列出所有可用 API
llm-wallet list-apis

# 3. 调用 API（需用户授权）
llm-wallet call-api translate_api --params '{"text": "hello", "to": "es"}'

# 4. 在交易历史中查看本次支付
llm-wallet history

错误处理

• 余额不足：显示错误信息，并引导用户前往测试网水龙头（faucet）或主网充值说明
• 支付被拒绝：交易回滚，依据错误消息排查具体原因
• 超出限额：显示当前限额与当日已用额度，建议用户调整限额
• 网络超时：采用指数退避策略重试（最多 3 次）

参考资料

详见 references/ 目录下文件：

• x402-protocol.md — x402 支付协议概述
• wallet-setup.md — 钱包详细配置指南
• examples.md — 更多使用示例

注意事项

• 所有金额单位均为 USDC（精度为 6 位小数）
• 默认网络为测试网，以保障安全性
• 测试网 USDC 不具备真实价值
• 切换至主网前务必再次确认网络配置
• 请妥善保管加密密钥（切勿泄露或提交至代码仓库）