Skip to main content
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.
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 (Figure 1) increases flexibility while keeping the double-entry model (debit and credit) intact, ensuring accounting consistency, traceability, and transparency.
Account Multiple Balances Jp
If no balanceKey is provided in a transaction, Midaz automatically uses the account’s default balance.

​
Balance key

Each balance is identified by a key field that uniquely identifies it within the account.
  • Maximum length: 100 characters — whitespace is not allowed.
  • Default key: "default" — automatically assigned when an account is first used in a transaction.
  • Uniqueness: Keys must be unique per account. Attempting to create a balance with a key that already exists on the same account returns an error.
  • In transactions: If no balanceKey is specified in a transaction, Midaz automatically uses the balance with key "default".
The key is set at creation time and cannot be changed. Choose descriptive keys like "credit", "collateral", or "savings" to make your balance model self-documenting.

​
Permission flags

Each balance has two independent permission flags that control whether it can participate in transactions:
FlagTypeDescription
allowSendingbooleanWhether funds can be sent from this balance
allowReceivingbooleanWhether funds can be received into this balance
These are per-balance flags — they apply to a specific balance, not to the account as a whole. Both default to true when not specified. Common use cases:
  • Freeze a balance: Set both allowSending and allowReceiving to false to prevent any movement.
  • Receive-only balance: Set allowSending to false to block outbound transfers while still accepting inflows.
  • Send-only balance: Set allowReceiving to false to prevent new funds from entering this balance.
Both flags can be set when creating a balance and updated independently via the Update a Balance endpoint. Omitting a flag in an update request leaves its current value unchanged.
Permission flags are evaluated at transaction time. Changing a flag affects only future transactions — it has no effect on operations already processed.

​
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).
In Figure 2, you can find an example of the structure.
Balance Structure Relationships Jp
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: 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.
Always use the balanceKey consistently across requests and responses to avoid mismatches when accounts hold multiple balances.

​
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>
Any integration that reads balances directly from Valkey must be updated to include the balanceKey. Otherwise, only the default balance will be available.

​
Balance history

Midaz provides point-in-time queries for balances, so you can retrieve the exact state of a balance at any moment in the past. This is essential for auditing, reconciliation, and historical reporting.

​
How it works

When you query balance history, Midaz reconstructs the balance state as it existed at the specified date and time. The response includes all the same fields as a regular balance — except for allowSending and allowReceiving. These fields reflect current operational permissions rather than historical state, so they are not included in point-in-time snapshots.
Why are permission flags excluded from history?allowSending and allowReceiving are mutable operational settings — they can be toggled at any time without creating a ledger entry. Unlike balance amounts (available, onHold), which change only as a result of recorded transactions, permission flags represent the current operational state of a balance, not a fact about its past.Historical audits and reconciliation are concerned with amounts at a point in time. Whether sending or receiving was enabled at a given moment is not meaningful for audit or reconciliation purposes, and including mutable permission state in immutable snapshots would introduce ambiguity without value.

​
Use cases

  • Regulatory auditing: Prove the exact balance of an account at a specific compliance checkpoint.
  • Reconciliation: Compare balance snapshots across systems at matching timestamps.
  • Dispute resolution: Retrieve the precise account state at the time of a contested transaction.
  • End-of-day reporting: Capture balance positions at market close for treasury operations.
The date parameter is required and must follow the format yyyy-mm-dd hh:mm:ss (e.g., 2026-01-15 10:30:00). If no balance data exists for the specified timestamp, a 404 error is returned.

​
Querying balance history

You can query history for a single balance or for all balances of an account:

​
Managing Balances

You can retrieve your Balances using the API. Balances are read-only and automatically managed by the Midaz ledger engine.
Want to trace how a balance was formed? Use the Operations API to inspect the ledger history that impacted that account.

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