Multiple balances
A single account can hold several balances, each identified by a unique key. This allows institutions to segment funds without creating multiple accounts for the same customer.
External accounts cannot have multiple balances. Each external account is limited to a single balance.
- Investment reserves
- Credit limits
- Collateral (blocked) funds
- Day-to-day operational funds
If no
balanceKey is provided in a transaction, Midaz automatically uses the account’s default balance.Usage examples
- User Wallet (BRL): A digital wallet showing an available balance of R$500.
- Use case: Show balance in a mobile banking app and validate funds before authorizing a payment.
- Settlement Account (USD): A liquidity provider account with a USD balance of $120,000.
- Use case: Ensure daily treasury operations maintain enough buffer for FX settlements.
- Blocked Balance (BRL): An account balance reserved as collateral.
- Use case: Prevent the use of funds until a loan is closed or conditions are met.
Balance structure
- Balance > Account: Each Balance belongs to an Account, which holds and moves value.
- Balance > Asset: Each Balance is associated with a specific Asset, such as BRL or BTC.
- Balance > Ledger: Balances exist within a Ledger, enabling multi-book environments.
- Balance > Key: Each Balance has a unique key within the account (e.g.,
default,credit,collateral).
Key characteristics
- Real-time tracking: Balances are updated with every confirmed operation.
- Multiple balances per account: Accounts can hold several balances, each with its own rules.
- Single source of truth: Balances reflect the net sum of all operations on the account.
- Query by context: Balances can be listed by organization, ledger, asset, account, or balance key.
- Supports external accounts: Balances can be retrieved for internal or external accounts, including liquidity pools or partners.
Using balances in transactions
The balanceKey field has been added to the following transaction endpoints to specify which balance to use:
- Create a Transaction using JSON
- Create an Inflow Transaction
- Create an Outflow Transaction
- Create a Transaction Annotation
balanceKey is provided, the system defaults to the account’s primary balance.
New fields in responses
balanceKey— Returned in Transactions and Operations, indicating which balance was used.key— Returned in Balances, uniquely identifying each balance.
Always use the balanceKey consistently across requests and responses to avoid mismatches when accounts hold multiple balances.
Managing Balances
You can retrieve your Balances using the API. Balances are read-only and automatically managed by the Midaz ledger engine.
- Create a Balance — Create a new balance for an account by defining a unique key.
- List Balances — Retrieve all balances by organization and ledger.
- Retrieve a Balance — Get the balance of a specific account by its unique ID.
- Retrieve Balances by Account — Get the balance for a specific account.
- Retrieve a Balance by Account Alias — Get the balance using a human-readable account alias (e.g., @user123).
- Retrieve a Balance of an External Account — Retrieve the balance of an external account (e.g.,
@external/BRL). - Update a Balance — Manually adjust a balance for operational or testing purposes.
- Delete a Balance (deprecated) — Delete a balance entry from the system.
Want to trace how a balance was formed? Use the Operations API to inspect the ledger history that impacted that account.
Cache key changes (Valkey)
Balances stored in cache (Valkey) now include the
balanceKey.
Previous format
New format
Any integration that reads balances directly from Valkey must be updated to include the balanceKey. Otherwise, only the default balance will be available.
Next steps
- Use the Operations API to trace transactions involving multiple balances.
- Combine multiple balances with Transaction Routing to create flexible and scalable financial flows.