Skip to main content

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.

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 casePattern
Single operational treasuryOne wallet (e.g., production-main).
Per-business-line separationMultiple wallets (e.g., marketplace, subscriptions, payroll).
Per-customer escrow accountsOne wallet per customer-facing entity.
Multi-currency operationOne 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"
}
FieldNotes
idServer-assigned, immutable (wal_…). Safe as a database key.
kindAlways Tenant.Wallet. Useful in mixed event streams.
walVersionSnapshot version. Increments on every mutation.
statusLifecycle: ACTIVE or DISABLED. See Wallet lifecycle.
nameCaller-supplied RFC 1035 DNS label (1–63 lowercase chars). Immutable. Globally unique.
selfNameCanonical relative path (wallets/<name>).
createdAt / updatedAtUTC ISO 8601 timestamps.
etagContent 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:
IdentifierSourceUse for
id (wal_2NhVqRtYbHmRdZ4vG6qAeL)Server-assigned at creationDatabase foreign keys, audit logs, machine-to-machine references
name (production-main)Caller-supplied at creationURL 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"
  }
}
FieldMeaning
amountTotal balance, including funds reserved for in-flight outbound orders.
lockedFunds reserved for outbound orders currently in PENDING or PROCESSING. Not spendable.
availableFunds 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:
StatusMeaningMutability
ACTIVENormal operation. Can create payment orders, query balance.Default at creation.
DISABLEDOperationally 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

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.
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.
Before submitting an outbound PIX_CASH_OUT_* order, fetch GET /wallets/{wallet}/balance and compare available to the order amount. Fail fast if insufficient.
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).

​
Next

Wallet lifecycle

The state machine — ACTIVE, DISABLED, transitions.

Payments overview

How payment orders flow through wallets.