钱包 API

管理你的 HD 钱包余额、查看交易历史和配置消费限额。每个用户账户都有一个自动配置的 HD（层级确定性）钱包用于 x402 支付。

基础 URL： https://api.jarvisclaw.ai/v1

认证

钱包端点接受三种凭证之一 —— API Key、仪表盘会话，或 x402 支付签名。

Authorization: Bearer sk-your-api-key

读取钱包状态本身不计费。

端点

GET /v1/wallet/balance

获取所有支持链上的当前钱包余额。返回真实链上 USDC 余额。

响应：

{
  "balance_usd": "9.001396",
  "wallets": {
    "base": {
      "usdc": "9.001396",
      "address": "0xYourBaseDepositAddress"
    },
    "solana": {
      "usdc": "0.000000",
      "address": "YourSolanaDepositAddress"
    }
  }
}

• balance_usd — 所有链上 USDC 余额总和
• wallets.base.usdc — Base 链（EIP-155:8453）上的 USDC 余额
• wallets.solana.usdc — Solana 链上的 USDC 余额

GET /v1/wallet/history

获取钱包的交易历史。

查询参数：

参数	类型	默认值	描述
page	integer	1	页码
page_size	integer	20	每页条数（最大 100）

响应：

{
  "transactions": [
    {
      "id": 12345,
      "amount_quota": -300,
      "category": "inference",
      "model": "deepseek/deepseek-chat",
      "use_time_seconds": 2,
      "created_at": 1718700000
    }
  ],
  "total": 1234,
  "page": 1
}

字段	说明
id	数字日志条目 ID
amount_quota	带符号的额度变动。负数为扣费。500,000 额度 = $1
category	inference、topup、refund、marketplace 或 other
model	产生该条目的模型或服务
use_time_seconds	上游处理耗时
created_at	Unix 时间戳（秒）

没有链过滤，也没有交易哈希

不支持 chain 参数，条目也不带 tx_hash、asset 或 ISO 时间戳 —— 这是平台的记账日志， 不是链上交易索引。链上历史请用区块浏览器查询你的钱包地址。另外参数名是 page_size 而非 per_page，响应中也不会回显 per_page。

GET /v1/wallet/limits

获取当前消费限额。直接返回限额记录 —— 没有 limits 包装层，也没有 usage 块。

响应：

{
  "user_id": 42,
  "daily_max_usd": 50,
  "per_request_max_usd": 1,
  "monthly_max_usd": 500,
  "auto_pause_below_usd": 2,
  "pool_allocation": "{\"operations\":0.60,\"insurance\":0.15,\"savings\":0.15,\"dividends\":0.10}",
  "updated_at": 1718700000
}

从未设置过限额时的默认值：daily_max_usd 50、per_request_max_usd 1、monthly_max_usd 500、 auto_pause_below_usd 2。

PUT /v1/wallet/limits

更新消费限额。

请求：

{
  "daily_max_usd": 100.00,
  "per_request_max_usd": 10.00,
  "monthly_max_usd": 1000.00,
  "auto_pause_below_usd": 5.00
}

响应： {"success": true}

校验规则 —— 违反时返回 400 及 {"error": "<原因>"}：

规则	限制
所有 USD 字段	必须 ≥ 0
daily_max_usd	≤ 100,000
monthly_max_usd	≤ 3,100,000（100,000 × 31）
per_request_max_usd	≤ 100,000
pool_allocation	合法 JSON 对象，且各值之和为 1.0（±0.01）

字段名是 per_request_max_usd

不是 per_call_max_usd。写错字段名不会报错，但限额也不会生效。

GET /v1/wallet/pools

获取资金池分配比例及各池对应的余额。资金池是你实际链上余额的比例切片，不是独立账户。

响应：

{
  "allocation": {
    "operations": 0.60,
    "insurance": 0.15,
    "savings": 0.15,
    "dividends": 0.10
  },
  "pool_balances": {
    "operations": "5.4008",
    "insurance": "1.3502",
    "savings": "1.3502",
    "dividends": "0.9001"
  }
}

调整比例请向 PUT /v1/wallet/limits 发送 pool_allocation。资金库工作流详见 钱包与资金库。

没有 /v1/wallet/address 端点

该路由不存在。充值地址已包含在 GET /v1/wallet/balance 的 wallets.base.address / wallets.solana.address 中。