Ledgers

Use Ledgers as the financial backbone of each Organization, tracking Transactions and Operations and enabling orchestrated cross-ledger transfers via bridges.

A Ledger is the Organization’s financial backbone. It keeps a precise record of all Transactions and Operations. A Ledger tracks every financial event: deposits, withdrawals, transfers, and fees. This gives you complete traceability and control.

Organizations can use multiple Ledgers to segregate financial operations. For example, a bank keeps separate Ledgers for different business lines, regions, or regulatory requirements. A single Ledger can also handle all operations for a simpler setup.

Ledger structure

---

• Ledger > Organization: Each Organization can own multiple Ledgers, but each Ledger belongs to only one Organization. This gives you financial separation and accountability.
  • Use multiple Ledgers only when you need to segregate data or operations — for example, internal treasury operations versus customer accounts.

Transactions cannot move directly between Ledgers. To move funds across Ledgers, orchestrate the transfer through a workflow that keeps both sides consistent.

How to orchestrate cross-Ledger transactions

To move funds between two Ledgers, create an orchestrated workflow. The workflow breaks the transfer into two separate transactions:

1. Debit from the source Ledger: Transfer the amount from an account in Ledger 1 to an External Account. This account bridges the two Ledgers and always belongs to one Asset.
2. Credit to the destination Ledger: Create a second transaction. It moves the same amount from the External Account into the target account in Ledger 2.

In this two-step process, each Ledger processes a valid, independent transaction. The External Account keeps both sides consistent.

You can use Flowker to automate this orchestration. Flowker can add validations, conditions, and rollback logic if you need them.

Key characteristics

---

• Ledgers ensure financial integrity and operational transparency.
• All Accounts and Transactions exist within a Ledger and form a complete financial system.
• Each Ledger keeps a balanced set of Accounts.
• You can use multiple Ledgers for segmentation, but cross-ledger transactions need explicit handling.

Multiple Ledgers

---

Midaz lets you create multiple Ledgers for each organization, with more flexibility and control. This helps companies with diverse operational needs. For example, they can separate financial records by country, department, or business function.

Example use case

Consider a global enterprise with business in multiple regions:

• Ledger 1: US Business
• Ledger 2: EU Business
• Ledger 3: APAC Business

With separate Ledgers, the company keeps region-specific transaction records, tax rules, and currency settings. It still has unified oversight of all operations.

When to create a new Ledger

A Ledger is a hard boundary, not just a label. Accounts in different Ledgers cannot transact directly. You must orchestrate every cross-Ledger movement through an External Account (see How to orchestrate cross-Ledger transactions). This cost drives the decision. Create a new Ledger only when the segments rarely move money between each other.

Use this heuristic to pick the right level of separation:

Mechanism	What it separates	Reach for it when
Ledger	A complete, self-contained set of books — its own accounts, balances, and asset configuration	You need true isolation: a separate legal entity, country, or regulatory regime, where balances should never mix and cross-segment movements are rare.
Portfolio	A grouping of accounts within one Ledger	You want a consolidated view of a customer or business unit, but the accounts still transact freely with the rest of the Ledger.
Account / Account Type	An individual balance and its rules	A single balance needs its own truth — its own statement, nature, or restrictions.

In short: if two sets of balances often transact with each other, keep them in the same Ledger. Separate them with Portfolios or Accounts. Split into multiple Ledgers only when the isolation is worth the orchestration overhead.

Customizing Ledgers

---

In Midaz, you can tailor each Ledger’s configuration to your requirements. Assets are scoped to a Ledger, so the same code is an independent record in each Ledger with its own name, type, status, and metadata.

Example To represent Bitcoin (BTC) across Ledgers, create the BTC asset independently in each Ledger and set the name, status, and metadata each Ledger needs.

Amounts in Midaz are arbitrary-precision decimals. There is no per-asset or per-Ledger decimal-place setting — you do not configure a scale when you create an asset.

This approach gives you granular control over asset management for your operational or regulatory needs.

Benefits of using Ledgers in Midaz

---

• Clear organization: Keep clear, distinct financial records for each part of your business.
• Custom configurations: Adjust asset settings, currencies, or other parameters per Ledger for local or departmental needs.
• Scalability: Add or change Ledgers as your organization grows or diversifies.
• Transparency: Get a complete view across all financial activities. Each Ledger adds to one operational picture.

Ledger settings

---

Each Ledger has configurable settings that control how it validates transactions. For example, you can require every transaction to follow a predefined route. You can also require account types to match your business rules. The Ledger then rejects invalid movements before it records them.

You can change these settings at any time through the API. You do not need to restart the service or change code.

Available settings

The following settings are available:

Setting	Default	Description
validateAccountType	false	When enabled, each new account must use an account type registered for the Ledger. The Ledger rejects the account creation if the type is not registered.
validateRoutes	false	When enabled, every transaction must include an associated transaction route. Each operation is also validated against its operation route rules.

Start with both settings disabled while you configure your operation routes and transaction routes. Once your routing setup is complete, enable validation to enforce your business rules.

How settings affect transactions

When you enable validateRoutes for a Ledger:

1. Every transaction to that Ledger must reference a valid transaction route.
2. The Ledger validates each operation against the corresponding operation route rules.
3. The Ledger rejects any non-compliant transaction before it records the movement. This protects your ledger integrity.

When you enable validateAccountType:

1. The Ledger checks each new account against its registered account types.
2. If the account type is not registered, the Ledger rejects the account creation.

If you enable validation on a Ledger that already processes transactions, existing records do not change. Validation applies only to new transactions that you submit after you enable the setting.

Managing settings via API

Use the Ledger Settings endpoints to retrieve and update these configurations:

• Retrieve Ledger Settings — View the current settings for a Ledger.
• Update Ledger Settings — Change one or more settings with a partial update (deep merge).

Settings updates take effect immediately. Midaz applies changes with a deep merge and modifies only the fields you include in the request.

Managing Ledgers

---

You can manage your Ledgers through the API or Lerian Console.

View API

• List Ledgers - View the details of all Ledgers.
• Retrieve a Ledger - Get details of a specific Ledger.
• Create a Ledger - Register a new Ledger.
• Update a Ledger - Edit the details of an existing Ledger.
• Delete a Ledger - Mark a Ledger as deleted.

When you delete a Ledger, Midaz does not remove it permanently.

Instead, Midaz sets a deletedAt timestamp. The Ledger is then excluded from every read and can no longer be used. Its status.code is left unchanged. This preserves historical data for audit trails.

Via Lerian Console

You can view, create, edit, and delete Ledgers on the Ledgers page in the Midaz Module of Lerian Console.

Learn more in the Managing Ledgers guide.

If you create your first Ledger in Lerian Console, you do it as part of the onboarding flow. To learn more, see the Midaz Module onboarding guide.