> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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: | 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](/en/reference/midaz/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: * [Create a Transaction using JSON](/en/reference/midaz/create-a-transaction-using-json) * [Create an Inflow Transaction](/en/reference/midaz/create-an-inflow-transaction) * [Create an Outflow Transaction](/en/reference/midaz/create-an-outflow-transaction) * [Create a Transaction Annotation](/en/reference/midaz/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 ```json theme={null} :: ``` ### New format ```json theme={null} ::: ``` 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](/en/midaz/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](/en/reference/midaz/retrieve-balance-history) - Get the state of a specific balance at a given point in time. * [Retrieve Balance History by Account](/en/reference/midaz/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](/en/reference/midaz/create-a-balance) - Create a new balance for an account by defining a unique key. * [List Balances](/en/reference/midaz/list-balances) - Retrieve all balances by organization and ledger. * [Retrieve a Balance](/en/reference/midaz/retrieve-a-balance) - Get the balance of a specific account by its unique ID. * [Retrieve Balances by Account](/en/reference/midaz/retrieve-balances-by-account) - Get the balance for a specific account. * [Retrieve a Balance by Account Alias](/en/reference/midaz/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](/en/reference/midaz/retrieve-a-balance-of-an-external-account) - Retrieve the balance of an external account (e.g., `@external/BRL`). * [Update a Balance](/en/reference/midaz/update-a-balance) - Manually adjust a balance for operational or testing purposes. * [Delete a Balance](/en/reference/midaz/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](/en/midaz/operations) to trace transactions involving multiple balances. * Combine multiple balances with [Transaction Routing](/en/midaz/transaction-routing-entities) to create flexible and scalable financial flows.