钱包 & 财务 API

钱包 API 为 Agent 和开发者提供对链上 USDC 余额、消费历史、池分配和限额的编程访问 — 实现自主财务管理。

概览

你的 JarvisClaw 钱包由 HD（层级确定性）钱包支撑，在两条链上持有真实 USDC：

网络	资产	描述
Base (EIP-155:8453)	USDC	主结算链
Solana	USDC	备选链

所有支付通过 x402 协议链上结算。没有平台配额或预充值积分 — 你的余额始终是链上真实 USDC。

查询余额

curl

curl https://api.jarvisclaw.ai/v1/wallet/balance \
  -H "Authorization: Bearer sk-YOUR-KEY"

Python

from jarvisclaw import Agent

agent = Agent(api_key="sk-YOUR-KEY")
bal = agent.balance()
print(f"总计: ${bal['balance_usd']}")
print(f"Base: {bal['wallets']['base']['usdc']} USDC")
print(f"Solana: {bal['wallets']['solana']['usdc']} USDC")

Go

bal, _ := c.WalletBalance(ctx)
fmt.Printf("总计: %s USD\n", bal.TotalUSD)
fmt.Printf("Base: %s USDC\n", bal.HDWallet.BaseUSDC)
fmt.Printf("Solana: %s USDC\n", bal.HDWallet.SolanaUSDC)

响应

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

• balance_usd — 所有链上 USDC 余额总和
• wallets.base.usdc — Base 链上的 USDC 余额
• wallets.solana.usdc — Solana 链上的 USDC 余额

池分配（财务管理）

你的余额被逻辑性地分为多个池，用于自主预算管理：

池	默认比例	用途
运营	60%	日常 API 调用
保险	15%	上游失败重试缓冲
储蓄	15%	扩展预留
分红	10%	所有者提现

curl https://api.jarvisclaw.ai/v1/wallet/pools \
  -H "Authorization: Bearer sk-YOUR-KEY"

{
  "allocation": {
    "operations": 0.60,
    "insurance": 0.15,
    "savings": 0.15,
    "dividends": 0.10
  },
  "pool_balances": {
    "operations": "10.4640",
    "insurance": "2.6160",
    "savings": "2.6160",
    "dividends": "1.7440"
  }
}

消费限额

获取和设置自主消费限额：

# 获取当前限额
curl https://api.jarvisclaw.ai/v1/wallet/limits \
  -H "Authorization: Bearer sk-YOUR-KEY"

# 更新限额
curl -X PUT https://api.jarvisclaw.ai/v1/wallet/limits \
  -H "Authorization: Bearer sk-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_max_usd": 30.0,
    "per_request_max_usd": 0.5,
    "monthly_max_usd": 200.0,
    "auto_pause_below_usd": 5.0
  }'

交易历史

curl "https://api.jarvisclaw.ai/v1/wallet/history?page=1&page_size=20" \
  -H "Authorization: Bearer sk-YOUR-KEY"

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

Treasury SDK (Go)

为需要完全财务自主的 Agent 设计 — 多池管理、规则引擎、熔断器：

go get github.com/api-jarvisclaw/agent-treasury-go

import "github.com/api-jarvisclaw/agent-treasury-go/treasury"

provider := treasury.NewJarvisClawProvider("https://api.jarvisclaw.ai", "sk-YOUR-KEY")
t := treasury.New(treasury.Config{
    AgentID: "my-trading-bot",
    Allocation: treasury.PoolAllocation{
        Operations: 0.70,
        Insurance:  0.10,
        Savings:    0.10,
        Dividends:  0.10,
    },
}, provider)

// 消费前检查预算
ok, _ := t.ApproveSpend(0.003, "inference")
if ok {
    // 发起 API 调用
    t.Spend(0.003, "inference", "deepseek-chat")
}

// 自动驾驶：成功率下降时熔断器暂停消费
snapshot := t.Snapshot()
fmt.Printf("运营池: $%.4f\n", snapshot.Pools["operations"])

API 参考

方法	路径	认证	描述
GET	/v1/wallet/balance	必须	链上 USDC 余额（Base + Solana）
GET	/v1/wallet/history	必须	分页交易记录
GET	/v1/wallet/limits	必须	当前消费限额
PUT	/v1/wallet/limits	必须	更新消费限额
GET	/v1/wallet/pools	必须	池分配 + 余额