Wallet API

Manage your HD wallet balance, view transaction history, and configure spending limits. Each user account has an automatically-provisioned HD (Hierarchical Deterministic) wallet for x402 payments.

Base URL: https://api.jarvisclaw.ai/v1

Authentication

Wallet endpoints accept any of three credentials — API key, dashboard session, or an x402 payment signature.

Authorization: Bearer sk-your-api-key

Reading wallet state is not itself a paid operation.

Endpoints

GET /v1/wallet/balance

Get current wallet balance across all supported chains. Returns real on-chain USDC balances.

Response:

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

• balance_usd — total USDC balance across all chains
• wallets.base.usdc — on-chain USDC balance on Base (EIP-155:8453)
• wallets.solana.usdc — on-chain USDC balance on Solana

GET /v1/wallet/history

Get transaction history for your wallet.

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	20	Items per page (max 100)

Response:

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

Field	Description
id	Numeric log entry ID
amount_quota	Signed quota delta. Negative is a charge. 500,000 quota = $1
category	inference, topup, refund, marketplace, or other
model	Model or service that generated the entry
use_time_seconds	Upstream processing time
created_at	Unix timestamp (seconds)

No chain filter, no tx hashes

There is no chain parameter and entries do not carry tx_hash, asset, or ISO timestamps — this is the platform's accounting log, not an on-chain transaction index. Use a block explorer against your wallet address for on-chain history. Note the parameter is page_size, not per_page, and the response has no per_page echo.

GET /v1/wallet/limits

Get current spending limits. Returns the limits record directly — there is no limits wrapper and no usage block.

Response:

{
  "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
}

Defaults when you have never set limits: daily_max_usd 50, per_request_max_usd 1, monthly_max_usd 500, auto_pause_below_usd 2.

PUT /v1/wallet/limits

Update spending limits.

Request:

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

Response: {"success": true}

Validation rules — a violation returns 400 with {"error": "<reason>"}:

Rule	Limit
All USD fields	Must be ≥ 0
daily_max_usd	≤ 100,000
monthly_max_usd	≤ 3,100,000 (100,000 × 31)
per_request_max_usd	≤ 100,000
pool_allocation	Valid JSON object whose values sum to 1.0 (±0.01)

The field is per_request_max_usd

Not per_call_max_usd. Sending the wrong name silently leaves the limit unchanged.

GET /v1/wallet/pools

Get treasury pool allocation and the balance behind each pool. Pools are proportional slices of your actual on-chain balance, not separate accounts.

Response:

{
  "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"
  }
}

Change the ratios by sending pool_allocation to PUT /v1/wallet/limits. See Wallet & Treasury for the treasury workflow.

Integration with x402

Your HD wallet is automatically used for x402 payments when you call any paid endpoint with an API key. The flow:

1. You call /v1/chat/completions with Authorization: Bearer sk-...
2. Platform calculates cost based on token usage
3. Platform signs x402 payment from your HD wallet
4. Settlement happens on-chain (Base USDC or Solana USDC)
5. Transaction appears in /v1/wallet/history

For agents that want to sign payments directly (without API key), see Agent Payments (x402).