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

# Wallets

> The Wallet resource — tenant-scoped balance containers.

A **Wallet** is the BlooBank platform's unit of balance and the isolation boundary for every payment order, ledger entry, and webhook event. This page documents the resource model; for the operational mental model, see [Wallet overview](/get-started/wallets/overview).

## Resource

```json theme={"dark"}
{
  "id":         "wal_2NhVqRtYbHmRdZ4vG6qAeL",
  "kind":       "Tenant.Wallet",
  "walVersion": 1,
  "status":     "ACTIVE",
  "name":       "production-main",
  "selfName":   "wallets/production-main",
  "createdAt":  "2026-01-15T10:30:00.000Z",
  "updatedAt":  "2026-01-15T10:30:00.000Z",
  "etag":       "9f3b2c1d8a7e6f5b4a3c2d1e0f9e8d7c6b5a493827160504e3d2c1b0a9f8e7d6"
}
```

| Field                     | Type         | Notes                                                                           |
| ------------------------- | ------------ | ------------------------------------------------------------------------------- |
| `id`                      | string       | Server-assigned, immutable (`wal_…`). Use as database key.                      |
| `kind`                    | string       | Always `Tenant.Wallet`.                                                         |
| `walVersion`              | integer      | Snapshot version. Increments on each mutation.                                  |
| `status`                  | enum         | `ACTIVE` or `DISABLED`. See [Wallet lifecycle](/get-started/wallets/lifecycle). |
| `name`                    | string       | RFC 1035 DNS label. 1–63 lowercase chars. Globally unique. **Immutable.**       |
| `selfName`                | string       | `wallets/<name>` — portable, base-URL-free reference.                           |
| `createdAt` / `updatedAt` | string       | UTC ISO 8601 with millisecond precision.                                        |
| `etag`                    | string (hex) | Content fingerprint. Reserved for optimistic concurrency.                       |

## Endpoints

| Operation                                         | Method | Path                        |        Idempotent?        |
| ------------------------------------------------- | ------ | --------------------------- | :-----------------------: |
| [List wallets](/api-reference/wallets/list)       | `GET`  | `/wallets`                  |             ✅             |
| [Create wallet](/api-reference/wallets/create)    | `POST` | `/wallets`                  | ❌ (uniqueness via `name`) |
| [Get wallet](/api-reference/wallets/get)          | `GET`  | `/wallets/{wallet}`         |             ✅             |
| [Update wallet](/api-reference/wallets/update)    | `PUT`  | `/wallets/{wallet}`         |             ✅             |
| [Get balance](/api-reference/wallets/get-balance) | `GET`  | `/wallets/{wallet}/balance` |             ✅             |

## Path parameter — `{wallet}`

All sub-resource endpoints accept the wallet in the path as either its `id` (`wal_…`) or its `name` (`production-main`). Both resolve to the same wallet.

## Related concepts

<CardGroup cols={2}>
  <Card title="Wallet overview" icon="wallet" href="/get-started/wallets/overview">
    Mental model, balance breakdown, use cases.
  </Card>

  <Card title="Wallet lifecycle" icon="recycle" href="/get-started/wallets/lifecycle">
    State machine — ACTIVE, DISABLED, transitions.
  </Card>

  <Card title="Resources & naming" icon="tags" href="/get-started/concepts/resources-and-naming">
    id, selfName, etag, walVersion across all resources.
  </Card>

  <Card title="Amounts & currency" icon="coins" href="/get-started/concepts/amounts-and-currency">
    How balance is represented.
  </Card>
</CardGroup>