> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-platform-1/xyb-ledger/getting-started/quickstart.md).

# Ledger Setup and Operations - Overview

Setting up and running the ledger for a given institution happens across three distinct layers, each responsible for a different part of how it actually functions: the **service** layer defines what's possible and enforced universally, the **product** layer decides how a specific product's accounts and wallets are structured and which ledger provider(s) they use, and the **operator** layer is where day-to-day visibility and manual intervention happen. This article walks through each layer in turn.

### Service Layer: Predefined Rules

At the service level (`cac-ledger-svc`), the ledger exposes a catalog of **predefined rules** — pre-configured behavior available for immediate use without writing custom code. Each rule is a simple toggle, and some expose a single parameter (a numeric threshold); the scripting underneath is hidden from the person configuring it.

The available rules fall into a few natural groups:

**Balance limits**

* Minimum wallet balance limit: prevents a wallet's available balance from falling negative
* Maximum wallet balance limit: prevents a wallet's available balance from exceeding a specified limit
* Minimum wallet balance limit (advanced): the same idea with additional logic for movement states, wallet types, and fee handling
* Maximum account balance limit: prevents an account's balance from exceeding a threshold defined by account type and currency

**Currency and status guards**

* Currency match check: blocks a transaction if the source and target wallet currencies don't match
* Wallet currency restriction: restricts which currencies a wallet can even be created in
* A family of status-based rejections: pending, suspended, suspended-in, suspended-out, terminated, and closed: each blocking transactions against a wallet in that state unless an explicit override is present

**Restriction-type guards**

* Block all / block incoming / block outgoing: reject transactions against a wallet carrying that specific restriction type

**Utility**

* Echo movement data: surfaces key movement attributes (group ID, payment ID, execution ID, command) for visibility

Because these are toggle-driven, an institution can compose its own ledger governance — which limits apply, which wallet states block activity, which currencies are even allowed — without needing engineering involvement for the common cases.

### Product Layer: Wiring Charts, Wallets, and Ledger Providers

Below the service layer, each **product** wires up its own ledger configuration — under Product configuration → Products → *\[product]*, on a tab named for whichever ledger provider it connects to (for example, "XYB ledger"). This is where a product's chart, wallets, and customer-group mappings actually get defined:

* **Chart configuration:** the chart's name, and account configuration (account reference, account tags)
* **Wallet configuration:** wallet name, accounting type (for example, Asset), wallet currency, and any wallet attributes, plus wallet codes broken out by currency
* **Group configuration:** mapping customer groups to the wallets they should use

Critically, a product isn't limited to a single ledger provider. One observed product carried both an **"XYB ledger" tab and a "Fiserv adapter" tab**, each independently configured — a concrete example of a single product routing through more than one connected ledger at once, rather than being locked to XYB's own ledger exclusively.

### Operator Layer: Day-to-Day Ledger Operations

Once a product is live, ongoing ledger operations happen from Console, under **Ledger**:

* **Chart management:** a full, searchable list of every chart in the system (one environment alone held over 26,000), each showing its account count and creation date. New charts can be created directly or uploaded in bulk via CSV.
* **Balances:** balances can be searched and browsed either by chart or by group, in list or grid view, and looked up directly by account or wallet.
* **Postings:** a browsable history of every ledger posting, with quick shortcuts for common ranges (last 7/30/90 days, this month) and filters for currency, metadata, value date, and status. This is also where a **manual journal entry** can be created, posting directly between two wallets.

One detail worth getting right when reading postings: each entry has both a **Type** (for example, "Res. credit" or "Res. debit") and a separate **Side** (Debit or Credit) — these are two distinct fields, not the same concept represented twice, and a posting's type and side don't always align in the direction you might expect.

### How the Layers Fit Together

The three layers are deliberately separate concerns. The service layer sets universal guardrails once, so every product built on it inherits the same baseline governance without needing to reimplement it. The product layer is where an institution's specific structure — its charts, wallets, currencies, and which external ledgers (if any) it also needs to stay in sync with — actually takes shape. The operator layer is the ongoing, day-to-day surface where that structure is monitored and, when needed, manually corrected. Together, this is what lets one ledger platform serve very different institutions and products without requiring a different system for each.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xyb.co/xyb-platform-1/xyb-ledger/getting-started/quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.