Ledgers

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. 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.
  • Use multiple Ledgers only when you need to segregate data or operations, for example internal treasury operations versus customer accounts.

​

How to orchestrate cross-Ledger transactions

When every Ledger involved enables crossLedger.enabled, send one direct or hold transaction through the v2 API. Each leg names the organizationId and ledgerId of its account. Midaz splits the transfer into one balanced transaction per Ledger:

1. Debit from the source Ledger: The account in Ledger 1 sends the amount to the External Account of Ledger 1 (@external/<asset>).
2. Credit to the destination Ledger: The External Account of Ledger 2 sends the amount to the target account.

The transactions share one groupId. In a direct transaction, they succeed or fail together.

​

Key characteristics

---

• All Accounts and Transactions exist within a Ledger.
• 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. For example, a company 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. Every movement between Ledgers passes through the External Account of each Ledger (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: 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.

​

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

​

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.

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.

​

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

​

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.

​

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.