A wallet represents the balance of an operational account on Bloobank. Each wallet is identified by a uniqueDocumentation Index
Fetch the complete documentation index at: https://docs.bloobank.com/llms.txt
Use this file to discover all available pages before exploring further.
walletId and operates in a specific currency.
Every financial operation — receiving, sending, reconciliation, balance lookup — happens in the context of a wallet. Other entities (Pix-In, Pix-Out, etc.) reference the source or destination wallet.
Key concepts
Identity
Each wallet has a unique, persistent
walletId generated by Bloobank at creation time.Balance
The balance is split into three views: total, available, and locked.
Multi-currency
Each wallet operates in a specific currency (
ccy). To move more than one
currency, use distinct wallets.Versioning
The
walVersion field enables optimistic concurrency control on balance-dependent operations.Wallet structure
| Field | Type | Description |
|---|---|---|
id | string | Unique wallet identifier. |
name | string | Human-readable internal name for operational use. |
kind | string | Wallet type (e.g. operational, escrow). |
status | string | Current wallet state (e.g. active, suspended). |
walVersion | integer | Current wallet version, incremented on every movement. |
createdAt | string | Creation date in UTC ISO 8601. |
updatedAt | string | Last update in UTC ISO 8601. |
TODO (needs to be filled manually): Internal documentation does not yet
enumerate the possible values of
kind and status on the wallet. The
fields exist on the model, but the constants must be confirmed with the
product team before publishing the list of accepted values.Wallet balance
A wallet’s balance is broken down into three complementary views:| Field | Description |
|---|---|
amount | Total balance recorded on the wallet, summing all positions. |
available | Balance effectively available to start new operations. |
locked | Balance held by in-flight operations (e.g. Pix-Out in processing). |
available and enters locked until final confirmation. On completion, the balance returns to the correct state: released on failure, or definitively debited on success.
All balance values are represented as integers, in the smallest unit of
the currency (cents for
BRL). To convert to a human-readable value, divide
by the number of decimal places indicated in decimals (2 for BRL).Money structure
Theamount, available, and locked fields are objects of type Money:
| Field | Description |
|---|---|
ccy | ISO currency code (e.g. BRL, USD). |
decimals | Currency decimal places (2 for BRL). |
value | Integer value in the smallest unit. 15000 = BRL 150.00. |
Use cases
Operational dashboard
Operational dashboard
Display the wallet balance in real time for the operator, separating what is available for immediate use from what is held by in-flight transactions.
Accounting reconciliation
Accounting reconciliation
Compare
amount, available, and locked at end of day to ensure all
movements were reconciled correctly.Transfer gating
Transfer gating
Before initiating a Pix-Out, validate that
available covers the transfer
amount. This avoids rejections due to insufficient funds.Flow monitoring
Flow monitoring
Track variations of
available throughout the day to detect anomalous activity or unexpected holds.Next steps
Wallet Balance
Endpoint to fetch the current balance of a wallet.
Pix - Cash-in
Receive funds via Pix into a wallet.
Pix - Cash-out
Send funds via Pix from a wallet.