A Balance represents the value held by a specific account in Midaz. It reflects the result of all operations (debits and credits) executed over time, and is always tied to a specific Asset, such as BRL, USD, or BTC.

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.

❗️

Important

External accounts cannot have multiple balances. Each external account is limited to a single balance.

Typical use cases include:

• Investment reserves
• Credit limits
• Collateral (blocked) funds
• Day-to-day operational funds

This approach increases flexibility while keeping the double-entry model (debit and credit) intact, ensuring accounting consistency, traceability, and transparency.

📘

Note

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

A balance is more than just a number. It includes metadata about the state of funds, such as pending operations and effective availability.

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

If no 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.

❗️

Important

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.

👍

Tip

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

<org_id>:<ledger_id>:<account_alias>

New format

<org_id>:<ledger_id>:<account_alias>:<balance_key>

🚧

Attention

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.