---
title: "Get wallet"
method: GET
path: "/v1/wallet"
tags: ["Wallet"]
---

# Get wallet

`GET /v1/wallet`

## Request

- Base URL: `https://agent.tinyfish.ai`
- URL: `https://agent.tinyfish.ai/v1/wallet`
- Auth: API key in header `X-API-Key`

Get the caller's wallet: current balance, auto-reload configuration, per-product contract rates, and any in-flight top-up.

## Response `200`

Wallet details

- object: Wallet balance, auto-reload, per-product rates, and any in-flight top-up.
  - `available_balance` string, required: Current spendable balance, denominated in `currency`. A negative value means the wallet is overdrawn.
  - `currency` 'USD', required
  - `as_of` string, date-time, required
  - `auto_reload` union, required: null means the auto-reload contract read failed, not that it is unconfigured.
    - object: Auto-reload has never been configured for this wallet.
      - `state` 'unconfigured', required
    - object: Auto-reload is configured, current state "on".
      - `state` 'on', required
      - `threshold` string, required: Balance floor that triggers a reload, denominated in the response's `currency`.
      - `recharge_to` string, required: Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.
    - object: Auto-reload is configured, current state "off".
      - `state` 'off', required
      - `threshold` string, required: Balance floor that triggers a reload, denominated in the response's `currency`.
      - `recharge_to` string, required: Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.
    - object: Auto-reload is configured, current state "paused_payment_failed".
      - `state` 'paused_payment_failed', required
      - `threshold` string, required: Balance floor that triggers a reload, denominated in the response's `currency`.
      - `recharge_to` string, required: Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.
    - object: Auto-reload is configured, current state "needs_payment_method".
      - `state` 'needs_payment_method', required
      - `threshold` string, required: Balance floor that triggers a reload, denominated in the response's `currency`.
      - `recharge_to` string, required: Balance the wallet is topped up to when a reload triggers, denominated in the response's `currency`.
    - unknown
  - `pending_top_up` object, nullable, required: null means no in-flight top-up, or the ledger read failed.
    - `amount` string, required: Amount of the in-flight top-up, denominated in the response's `currency`.
    - `started_at` string, date-time, required
  - `rates` object, nullable, required: null means the rates read failed, or the wallet has no rate contract yet.
    - `meters` object[], required
      - `label` string, required: Human-readable meter label.
      - `unit_amount` string, required: Per-unit rate, decimal USD string.
      - `currency` 'USD', required
      - `per` string: Billable unit this meter charges per (e.g. "step"). Absent when unlabeled.
    - `as_of` string, date-time, required
  - `agent_top_up_url` string, uri: Present when an agent can add funds itself: POST here and pay the 402 MPP challenge.

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - Wallet isn't available for organizations yet.
- `404`: The account is not assigned to wallet billing (error code FEATURE_NOT_AVAILABLE).
- `500`: Internal server error
- `503`: Organization could not be resolved (organization_unresolved). Retry later.

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/6c73a54df35c?raw)