> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet

> Check wallet balance and top up with the Machine Payments Protocol

Check wallet balance and top up funds using the Machine Payments Protocol (MPP). All requests
require the `X-API-Key` header unless noted otherwise. See [Authentication](https://docs.tinyfish.ai/authentication.md).

## Endpoints

| Endpoint | Method | Purpose |
| - | - | - |
| `/v1/wallet` | `GET` | Get balance, currency, auto-reload state, and rates |
| `/v1/wallet/top-up` | `POST` | Top up the wallet, paid by the agent over MPP |

## Get Wallet Balance

`GET /v1/wallet`

Get the caller's wallet: current balance, auto-reload configuration, per-product contract rates,
and any in-flight top-up. Returns `404` with `FEATURE_NOT_AVAILABLE` on legacy (non-wallet) accounts.

**available\_balance** `string`

Current spendable balance in `currency`. Negative means overdrawn.

**currency** `string`

**auto\_reload** `object | null`

`null` means the auto-reload contract read failed, not that it's unconfigured.

**pending\_top\_up** `object | null`

`null` means no in-flight top-up, or the ledger read failed.

**rates** `object | null`

`null` means the rates read failed, or the wallet has no rate contract yet.

**agent\_top\_up\_url** `string`

Present when an agent can add funds itself: `POST` here and pay the `402` MPP challenge.

## Top Up the Wallet

`POST /v1/wallet/top-up`

Add money to the wallet, paid by the calling agent over the Machine Payments Protocol (MPP). The
first call answers `402` with a payment challenge in `WWW-Authenticate`; retry with a
`Payment-Authorization` credential to settle the charge and credit the wallet. Full handshake
walkthrough: [TinyAgent Payments](https://docs.tinyfish.ai/agent-payments.md).

**amount** `string` *required*

USD amount to add, from `10.00` to `500.00`.

Response (`200` settled or `202` pending):

**status** `string`

**amount** `string`

**currency** `string`

**payment\_reference** `string`

The Stripe PaymentIntent that settled this top-up.

**ledger\_entry\_id** `string`

**available\_balance** `string | null`

`null` when pending or unreadable.

**hint** `string`

On a `202`: don't pay again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.