Ledgers

A Ledger acts as the Organization’s financial backbone, maintaining a precise record of all Transactions and Operations. Every financial event—deposits, withdrawals, transfers, fees—is tracked within a Ledger, ensuring complete traceability and control. Organizations can use multiple Ledgers to segregate financial operations. For example, a bank may maintain separate Ledgers for different business lines, geographies, or regulatory requirements. Alternatively, a single Ledger can handle all operations for a streamlined approach.

​

Ledger structure

---

• Ledger > Organization: Each Organization can own multiple Ledgers, but each Ledger belongs to only one Organization. This ensures financial separation and accountability.
  • Multiple Ledgers should only be used when data or operational segregation is required—for example, for internal treasury operations versus customer accounts.

​

How to orchestrate cross-Ledger transactions

To move funds between two Ledgers, you’ll need to create an orchestrated workflow that breaks the transfer into two separate transactions:

1. Debit from the source Ledger: Start by transferring the desired amount from an account in Ledger 1 to an External Account. This account acts as a bridge and is always linked to a specific Asset.
2. Credit to the destination Ledger: Then, create a second transaction that moves the same amount from the External Account into the target account in Ledger 2.

This two-step process ensures that each Ledger processes a valid and independent transaction, while the External Account maintains consistency across the ecosystem.

​

Key characteristics

---

• Ledgers ensure financial integrity and operational transparency.
• All Accounts and Transactions exist within a Ledger, forming a complete financial system.
• Each Ledger maintains a balanced set of Accounts.
• Multiple Ledgers can be used for segmentation, but cross-ledger transactions require explicit handling.

​

Multiple Ledgers

---

Midaz provides the capability to create multiple Ledgers for each organization, offering enhanced flexibility and control. This feature is particularly beneficial for companies with diverse operational needs, such as separating financial records by country, department, or specific 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

By using separate Ledgers, the company can maintain region-specific transaction records, tax considerations, and currency settings while retaining a unified oversight of all operations.

​

Customizing Ledgers

---

One of the standout features of Ledgers in Midaz is the ability to tailor configurations based on individual requirements. For example, the same asset can be configured differently in separate Ledgers: Example To represent Bitcoin (BTC) with unique settings across Ledgers:

• Ledger 1: BTC with 10 decimal places.
• Ledger 2: BTC with 20 decimal places.

In this case, you simply create the BTC asset independently in each Ledger, applying the necessary configuration. This approach enables granular control over asset management, aligning with specific operational or regulatory needs.

​

Benefits of using Ledgers in Midaz

---

• Enhanced Organization: Maintain clear and distinct financial records tailored to various aspects of your business.
• Custom Configurations: Adjust asset settings, currencies, or other parameters per Ledger to meet localized or departmental needs.
• Scalability: Easily add or modify Ledgers as your organization grows or diversifies.
• Transparency: Gain comprehensive insights across all financial activities, with each Ledger contributing to a cohesive operational picture.

​

Ledger settings

---

Each Ledger has configurable settings that control how transactions are validated. For example, you can enforce that every transaction follows a predefined route, or that account types match your business rules — so the ledger rejects invalid movements before they are recorded. These settings can be changed at any time through the API, with no service restart or code changes required.

​

Available settings

The following settings are available:

​

How settings affect transactions

When validateRoutes is enabled for a Ledger:

1. Every transaction submitted to that Ledger must reference a valid transaction route.
2. Each operation within the transaction is validated against the corresponding operation route rules.
3. Transactions that don’t comply are rejected before recording — protecting your ledger integrity.

When validateAccountType is enabled:

1. Each operation’s account is checked against the account type rules defined in the operation route.
2. If the account type doesn’t match the expected rule, the transaction is rejected.

​

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 using a partial update (deep merge).

​

Managing Ledgers

---

You can manage your Ledgers either via API or through 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

All Ledger management actions, including viewing, creating, editing, and deleting, can be done through the Ledgers page in the Midaz Module of Lerian Console. Learn more in the Managing Ledgers guide.