BlooBank API Documentation

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

{
  "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.
`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 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.

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.

The three balances

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

{
  "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.

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 for the full state machine.

Operational patterns

Operational dashboard

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.

Accounting reconciliation

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.

Pre-flight balance check

Before submitting an outbound PIX_CASH_OUT_* order, fetch GET /wallets/{wallet}/balance and compare available to the order amount. Fail fast if insufficient.

Multi-currency support

Each wallet is single-currency (asset.ccy). For multi-currency operation, create one wallet per currency and route incoming payments by currency.

Endpoints

List wallets

Page through accessible wallets.

Create wallet

Provision a new wallet with a DNS label name.

Get wallet

Fetch a wallet by id or name.

Get balance

Real-time balance snapshot (amount / locked / available).

Wallet lifecycle

The state machine — ACTIVE, DISABLED, transitions.

Payments overview

How payment orders flow through wallets.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Wallet overview

Why wallets exist

Anatomy of a wallet

Identifiers — `id` vs `name`

The three balances

Lifecycle states

Operational patterns

Endpoints

List wallets

Create wallet

Get wallet

Get balance

Next

Wallet lifecycle

Payments overview

​Why wallets exist

​Anatomy of a wallet

​Identifiers — id vs name

​The three balances

​Lifecycle states

​Operational patterns

​Endpoints

List wallets

Create wallet

Get wallet

Get balance

​Next

Wallet lifecycle

Payments overview

Why wallets exist

Anatomy of a wallet

Identifiers — `id` vs `name`

The three balances

Lifecycle states

Operational patterns

Endpoints

Next