Balances

Track multiple Balances per Account to segment funds — investment reserves, credit limits, and operational funds without extra Accounts.

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.

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:

Flag	Type	Description
allowSending	boolean	Whether funds can be sent from this balance
allowReceiving	boolean	Whether 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.

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.

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

Overdraft

---

Balances support overdraft — the ability to be debited beyond available funds. When overdraft is enabled, the deficit is tracked as OverdraftUsed and Midaz automatically handles the operation split and repayment.

Two fields support this feature:

• direction — Defines whether a balance behaves as an asset (credit, default) or a liability (debit). Set at creation, immutable.
• settings — Controls overdraft behavior: allowOverdraft, overdraftLimitEnabled, and overdraftLimit.

The key "overdraft" is reserved for the system-managed companion balance that records the liability side. Attempting to create a balance with this key returns an error.

Balances are also distinguished by scope via settings.balanceScope. Transactional balances (default) are user-managed and participate in regular transactions. Internal balances are operated exclusively by the system — like the overdraft companion — and cannot be targeted by user transactions, modified, or deleted through the public API.

For full details on configuration modes, operation splits, automatic repayment, events, and use cases, see Balance Overdraft.

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:

• Retrieve Balance History - Get the state of a specific balance at a given point in time.
• Retrieve Balance History by Account - Get the state of all balances for an account at a given point in time.

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

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.