> ## 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.

# Wallet overview

> Tenant-scoped balance containers — the isolation boundary for payments and ledger.

A **wallet** is the BlooBank platform's unit of balance and the **isolation boundary** for every financial operation. Every payment order, every webhook event, every balance query happens in the context of a specific wallet.

## Why wallets exist

A tenant typically holds money for multiple distinct purposes — operational treasury, customer settlement accounts, escrow reserves. Mixing those in one balance makes reconciliation painful and rules ambiguous. Wallets give you **explicit, named ledger boundaries** so each purpose has its own bookkeeping.

| Use case                     | Pattern                                                             |
| ---------------------------- | ------------------------------------------------------------------- |
| Single operational treasury  | One wallet (e.g., `production-main`).                               |
| Per-business-line separation | Multiple wallets (e.g., `marketplace`, `subscriptions`, `payroll`). |
| Per-customer escrow accounts | One wallet per customer-facing entity.                              |
| Multi-currency operation     | One wallet per currency (each wallet is single-currency).           |

Pick the granularity that matches **how you reconcile**, not how you organize.

## Anatomy of a wallet

```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                     | Notes                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `id`                      | Server-assigned, immutable (`wal_…`). Safe as a database key.                              |
| `kind`                    | Always `Tenant.Wallet`. Useful in mixed event streams.                                     |
| `walVersion`              | Snapshot version. Increments on every mutation.                                            |
| `status`                  | Lifecycle: `ACTIVE` or `DISABLED`. See [Wallet lifecycle](/get-started/wallets/lifecycle). |
| `name`                    | Caller-supplied RFC 1035 DNS label (1–63 lowercase chars). Immutable. Globally unique.     |
| `selfName`                | Canonical relative path (`wallets/<name>`).                                                |
| `createdAt` / `updatedAt` | UTC ISO 8601 timestamps.                                                                   |
| `etag`                    | Content fingerprint, reserved for future optimistic concurrency via `If-Match`.            |

See [Resources & naming](/get-started/concepts/resources-and-naming) for the shared envelope shape.

## Identifiers — `id` vs `name`

Both identify the wallet, but they serve different purposes:

| Identifier                          | Source                      | Use for                                                          |
| ----------------------------------- | --------------------------- | ---------------------------------------------------------------- |
| `id` (`wal_2NhVqRtYbHmRdZ4vG6qAeL`) | Server-assigned at creation | Database foreign keys, audit logs, machine-to-machine references |
| `name` (`production-main`)          | Caller-supplied at creation | URL paths, human-facing flows, dashboard search                  |

Both are accepted in path parameters: `GET /wallets/wal_2NhVqRtYbHmRdZ4vG6qAeL` and `GET /wallets/production-main` resolve to the same wallet.

<Note>
  **Name rules.** RFC 1035 DNS label: 1–63 chars, lowercase `a-z`, digits, hyphen. Must start with a letter, end with alphanumeric. **Immutable** once created — `LABEL_IMMUTABLE` on attempts to change.
</Note>

## The three balances

A wallet's balance is split into **three** views — not one. Querying `GET /wallets/{wallet}/balance` returns:

```json theme={"dark"}
{
  "amount":    { "ccy": "BRL", "decimals": 2, "value": 1250075 },
  "locked":    { "ccy": "BRL", "decimals": 2, "value":   25000 },
  "available": { "ccy": "BRL", "decimals": 2, "value": 1225075 },
  "asset": {
    "ccy": "BRL", "type": "fiat", "symbol": "R$",
    "decimals": 2, "name": "Brazilian Real"
  }
}
```

| Field       | Meaning                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------- |
| `amount`    | Total balance, including funds reserved for in-flight outbound orders.                        |
| `locked`    | Funds reserved for outbound orders currently in `PENDING` or `PROCESSING`. **Not spendable.** |
| `available` | Funds you can immediately commit to a new outbound order. `available = amount - locked`.      |

**Before creating an outbound payment**, check `available`, not `amount`. An outbound order against insufficient `available` returns `INSUFFICIENT_FUNDS` (in the order's `errorCode`) and the order finalizes as `FAILED`.

Balance values are integers in **minor units** (cents for BRL). See [Amounts & currency](/get-started/concepts/amounts-and-currency).

## Lifecycle states

A wallet is in one of two states:

| Status     | Meaning                                                                        | Mutability                                                    |
| ---------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `ACTIVE`   | Normal operation. Can create payment orders, query balance.                    | Default at creation.                                          |
| `DISABLED` | Operationally frozen. Existing balance preserved; new payment orders rejected. | Set via `PUT /wallets/{wallet}` with `{"status":"DISABLED"}`. |

`DISABLED` is reversible — set back to `ACTIVE` via the same endpoint. See [Wallet lifecycle](/get-started/wallets/lifecycle) for the full state machine.

## Operational patterns

<AccordionGroup>
  <Accordion title="Operational dashboard" icon="chart-line">
    Display `amount`, `available`, `locked` side by side. Refresh on webhook events or at fixed intervals — the snapshot is read live from the underlying provider, not cached.
  </Accordion>

  <Accordion title="Accounting reconciliation" icon="scale-balanced">
    At end of day, compare your local ledger of completed payment orders with the wallet's `amount`. Any drift indicates a missed event — replay webhooks via the Dashboard.
  </Accordion>

  <Accordion title="Pre-flight balance check" icon="lock">
    Before submitting an outbound `PIX_CASH_OUT_*` order, fetch `GET /wallets/{wallet}/balance` and compare `available` to the order amount. Fail fast if insufficient.
  </Accordion>

  <Accordion title="Multi-currency support" icon="globe">
    Each wallet is single-currency (`asset.ccy`). For multi-currency operation, create one wallet per currency and route incoming payments by currency.
  </Accordion>
</AccordionGroup>

## Endpoints

<CardGroup cols={2}>
  <Card title="List wallets" icon="list" href="/api-reference/wallets/list">
    Page through accessible wallets.
  </Card>

  <Card title="Create wallet" icon="plus" href="/api-reference/wallets/create">
    Provision a new wallet with a DNS label name.
  </Card>

  <Card title="Get wallet" icon="magnifying-glass" href="/api-reference/wallets/get">
    Fetch a wallet by id or name.
  </Card>

  <Card title="Get balance" icon="scale-balanced" href="/api-reference/wallets/get-balance">
    Real-time balance snapshot (`amount` / `locked` / `available`).
  </Card>
</CardGroup>

## Next

<CardGroup cols={2}>
  <Card title="Wallet lifecycle" icon="recycle" href="/get-started/wallets/lifecycle">
    The state machine — ACTIVE, DISABLED, transitions.
  </Card>

  <Card title="Payments overview" icon="money-bill-transfer" href="/get-started/payments/overview">
    How payment orders flow through wallets.
  </Card>
</CardGroup>