---
title: "GET /wallets — List Wallets"
url: https://lumean.app/en/developers/docs/api/get-wallets
locale: en
description: "List Wallets"
generated: 2026-10-18
operationId: billing.wallets
method: GET
path: /wallets
scopes: [billing.read]
spec_version: 1.0.0
---

# GET /wallets

**List Wallets**

The key owner's wallets: asset, available balance and funds locked against running
orders. There may be several — one per asset.

Amounts are in the asset's minor units and come with its `precision`: the real value
is `amount / 10^precision`. A display-ready `*_formatted` field sits next to each.

This endpoint exists only while the wallet feature is enabled; in the
subscription-only model it is absent (`404`) and the remaining allowance is read from
`GET /subscriptions`.

**Required key permission:** `billing.read`.

- Required scope: `billing.read`

## Request

```bash
curl -X GET 'https://api.lumean.app/api/public/wallets' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

## Parameters

| Field | In | Type | Req. | Description |
| --- | --- | --- | --- | --- |
| `page` | query | `integer` — ≥ 1 | — | Page number, starting at `1`. |
| `per_page` | query | `integer` — 1..100 | — | Wallets per page. Defaults to 20; there are usually only a few, so this is rarely needed. |
| `X-Locale` | header | `string` | — | Language of the localised texts in the response (`message`, labels, failure reasons), an ISO-639-1 code. Optional; without it — the key owner’s account language, then `Accept-Language`, then the default language. An unknown or unsupported code is skipped as if it were absent. |
| `X-Timezone` | header | `string` | — | IANA time zone (`Europe/Moscow`) in which the response shows moments in time — ISO-8601 with an offset. Optional; without it dates come in UTC. An invalid zone is ignored. The server returns the applied zone in the response header of the same name. |

## Request body

No body.

## Responses

### 200 — Success. The payload is in `data`.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all. |
| `message` | `string` | required | A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code. |
| `data` | `WalletList` | required | The response payload. |
| `data.items` | `array<Wallet>` | required | Records on the current page, in the list’s sort order. |
| `data.items[].id` | `integer` | required | Wallet ID. Use it to filter the history: `GET /ledger-transactions?wallet_id=`. |
| `data.items[].user_id` | `integer` — nullable | required | ID of the wallet owner — always the key owner. |
| `data.items[].asset_id` | `integer` — nullable | required | ID of the asset the wallet is kept in; the asset itself is in `asset`. |
| `data.items[].purpose` | `string` | required | Wallet purpose: `main` is the main balance, `referral` holds referral earnings. |
| `data.items[].balance` | `integer` | required | Balance in the asset’s minor units: amount = `balance / 10^asset.precision`. An integer, not a fraction. |
| `data.items[].locked_balance` | `integer` | required | Locked part of the balance in the asset’s minor units — reserved for orders in progress and payout requests, so it cannot be spent. |
| `data.items[].balance_formatted` | `number` — nullable | — | Balance as a decimal number by `asset.precision` (`balance / 10^precision`), ready to display. |
| `data.items[].locked_balance_formatted` | `number` — nullable | — | Locked part of the balance as a decimal number by `asset.precision`. |
| `data.items[].balance_converted` | `object` — nullable | required | Informational conversion of the balance into the account’s display currency. `null` for non-LUMC wallets and when no rate is available; use `balance` for calculations. |
| `data.items[].balance_converted.currency` | `string` | required | Display currency code (ISO 4217). |
| `data.items[].balance_converted.amount` | `number` | required | Amount in the display currency, rounded to its `precision`. |
| `data.items[].balance_converted.symbol` | `string` | required | Currency symbol for display; `null` if the currency has none. |
| `data.items[].balance_converted.precision` | `integer` | required | Number of decimal places of the display currency. |
| `data.items[].asset` | `Asset` | — | The wallet asset: code, kind and the `precision` that turns `balance` into an amount. |
| `data.items[].asset.id` | `integer` | required | Internal identifier of the asset. |
| `data.items[].asset.code` | `string` | required | Asset code: `LUMC` is the internal currency, `TOKEN` the generation tokens. |
| `data.items[].asset.kind` | `AssetKind` — `money` · `unit` | required | Kind of asset: money or consumable units. It decides whether an amount counts as a payment or as quota consumption. |
| `data.items[].asset.precision` | `integer` | required | Number of decimal places. **The load-bearing field:** every integer amount in this asset is divided by `10^precision` to obtain the real value. Do not assume the divisor is 100. |
| `data.items[].asset.name` | `string` | required | Display name of the asset, in the account language. |
| `data.items[].asset.deleted_at` | `string` — date-time — nullable | required | When the asset was retired, ISO 8601. `null` while it is in use. |
| `data.items[].asset.created_at` | `string` — date-time — nullable | required | When the asset was created, ISO 8601. |
| `data.items[].asset.updated_at` | `string` — date-time — nullable | required | When the asset last changed, ISO 8601. |
| `data.items[].deleted_at` | `string` — date-time — nullable | required | When the wallet was deleted; `null` for wallets in this list. |
| `data.items[].created_at` | `string` — date-time — nullable | required | When the wallet was created. |
| `data.items[].updated_at` | `string` — date-time — nullable | required | When the wallet last changed, balance included. |
| `data.current_page` | `integer` | required | Current page number, starting from one. |
| `data.last_page` | `integer` | required | Number of the last page. The walk is over once `current_page` equals `last_page`. |
| `data.per_page` | `integer` | required | Page size the server applied. |
| `data.total` | `integer` | required | Total number of records matching the filter. |

**Example**

```json
{
  "success": true,
  "message": "string",
  "data": {
    "items": [
      {
        "id": 1,
        "user_id": 1,
        "asset_id": 1,
        "purpose": "string",
        "balance": 1,
        "locked_balance": 1,
        "balance_formatted": 1,
        "locked_balance_formatted": 1,
        "balance_converted": {
          "currency": "string",
          "amount": 1,
          "symbol": "string",
          "precision": 1
        },
        "asset": {
          "id": 1,
          "code": "string",
          "kind": null,
          "precision": 1,
          "name": null,
          "is_active": true,
          "is_default": true,
          "default_balance": 1,
          "deleted_at": "2026-07-17T12:34:56+00:00",
          "created_at": "2026-07-17T12:34:56+00:00",
          "updated_at": "2026-07-17T12:34:56+00:00"
        },
        "user": {
          "id": 1,
          "email": "string",
          "lang_code": "string",
          "timezone": "string",
          "display_currency": "string",
          "has_telegram": true,
          "created_at": "2026-07-17T12:34:56+00:00",
          "updated_at": "2026-07-17T12:34:56+00:00",
          "referral_code": "string",
          "referral": {
            "kind": null,
            "code": null,
            "program_id": null,
            "commission_rate": null
          },
          "preferred_domain": "string",
          "email_verified_at": "string",
          "is_admin": true,
          "is_beta_tester": true,
          "allowed_models": "string",
          "referrer_id": 1,
          "deleted_at": "2026-07-17T12:34:56+00:00",
          "blocked_at": "2026-07-17T12:34:56+00:00",
          "is_blocked": true,
          "tickets_banned_at": "string",
          "is_tickets_banned": true,
          "tickets_ban_reason": "string",
          "voice_clone_banned_at": "string",
          "is_voice_clone_banned": true,
          "voice_clone_ban_reason": "string",
          "is_super_admin": true,
          "admin_permissions": [
            null
          ],
          "admin_roles": [
            null
          ],
          "referrer": null,
          "referral_link": "string",
          "active_referral_program": null,
          "wallets": [
            null
          ],
          "telegram": null,
          "subscriptions": [
            null
          ],
          "order_settings": null,
          "entitlements": [
            null
          ]
        },
        "deleted_at": "2026-07-17T12:34:56+00:00",
        "created_at": "2026-07-17T12:34:56+00:00",
        "updated_at": "2026-07-17T12:34:56+00:00",
        "system_key": "string"
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 1,
    "total": 1
  }
}
```

### 401 — The key is missing, unknown, disabled or expired.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | required | Always `null` when the request is rejected before processing. |

**Example**

```json
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
```

### 403 — The key lacks the required permission, or the object belongs to another user.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). |

**Example**

```json
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
```

### 422 — Validation error. Offending fields are listed in `errors`.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | A summary of the validation errors in words, in the response language (`X-Locale`). |
| `errors` | `object` | required | A per-field breakdown: the key names a request field, the value lists the complaints about it. |
| `errors.*` | `array<string>` — arbitrary keys | — |  |

**Example**

```json
{
  "success": true,
  "message": "string",
  "errors": {}
}
```

---

- This page in the browser: https://lumean.app/en/developers/docs/api/get-wallets
- Full machine-readable reference: https://api.lumean.app/docs/llm.md