> 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/integrate-with-xyb-ledger/understanding-the-ledger-structure-charts-accounts-wallets/understanding-and-creating-accounts-in-the-ledger.md).
# Understanding and Creating Accounts in the Ledger
Accounts in the ledger serve as entities for tracking balances and movements. They enable effective management of institutional operations or customer-specific activities. This article delves into the types of accounts, their characteristics, and step-by-step instructions for creating them.
***
### **What are Accounts in the Ledger?**
Accounts are financial entities that:
* **Track Balances:** Manage funds through associated wallets.
* **Record Movements:** Serve as a container for movements and postings.
* **Organize Data:** Aggregate financial information under parent structures.
#### **Key Features of Accounts**
1. **Parent Structures:** Accounts belong to **Charts** or **Groups**, defining their operational or customer-centric roles.
2. **Associated Wallets:** Accounts hold wallets that manage funds across various currencies and accounting types.
3. **Metadata Support:** Accounts can include tags and attributes for enhanced categorization and reporting.
***
### **Types of Accounts**
#### **1. Chart Accounts**
**Chart Accounts** represent institutional or operational activities, focusing on internal financial management.
**Characteristics:**
* Linked to **Charts**, which structure accounts for organizational reporting.
* Typically used for company operations like payroll, budgets, or general ledger activities.
* Support multiple wallets for segregating funds by purpose or currency.
**Use Cases:**
* **Department Budgets:** Manage and track funds for specific departments.
* **Corporate Funds:** Centralize operational funds for company-wide activities.
***
#### **2. Group Accounts**
**Group Accounts** manage balances and transactions specific to customers or groups, focusing on customer-centric operations.
**Characteristics:**
* Linked to **Groups**, allowing aggregation of multiple customer or segment accounts.
* Ideal for managing individual customer balances or segment-specific funds.
* Supports flexible wallet configurations for customer needs.
**Use Cases:**
* **Individual Customer Balances:** Track payments, loans, refunds, or rewards.
* **Customer Segments:** Manage funds for premium users, regional customers, or business clients.
***
### **Steps to Create Accounts**
#### **A. Chart Accounts**
**Step 1: Prepare the Parent Chart**
* Create a chart to group related accounts.
* Example:
```bash
./luca create-chart company
```
**Step 2: Create the Account**
* Assign a reference name and define account-specific metadata.
* Example:
```bash
./luca create-chart-account company operational-account --t:finance --a:owner=finance-dept
```
**Step 3: Add Wallets to the Account**
* Define wallets for the account to manage specific currencies or accounting types.
* Example:
./luca create-chart-wallet company operational-account default USD ASSET --decimal-places=2
**Step 4: Transition the Account and Wallets to `OPEN`**
* Enable the account and its wallets for transactions.
* Example:
```bash
./luca transition /chart/company/operational-account OPEN
```
***
#### **B. Group Accounts**
**Step 1: Prepare the Parent Group**
* Create a group to house customer-specific or segment-specific accounts.
* Example:
```bash
./luca create-group customers
```
**Step 2: Create the Account**
* Assign a reference name and metadata specific to the customer or group.
* Example:
```bash
./luca create-group-account customers ACCT2938 --t:customer --a:customer-id=J12345
```
**Step 3: Add Wallets to the Account**
* Configure wallets to manage balances for the customer or group.
* Example:
```bash
./luca create-group-wallet customers ACCT2938 savings USD LIABILITY --decimal-places=2
```
**Step 4: Transition the Account and Wallets to `OPEN`**
* Enable the account and wallets for transactions.
* Example:
```bash
./luca transition /group/customers/ACCT2938 OPEN
```
***
### **Account Metadata**
Accounts support metadata for enhanced categorization and integration:
* **Tags:** Short descriptors for quick classification (e.g., `premium`, `finance`).
* **Attributes:** Key-value pairs for detailed metadata (e.g., `owner=finance-dept`, `customer-id=J12345`).
**Example Command to Add Metadata:**
```bash
./luca create-group-account customers ACCT2938 --t:premium --a:customer-id=J67890
```
***
### **Managing Account States**
Accounts can transition between states to control their activity:
* **OPEN:** Fully operational.
* **SUSPENDED:** Temporarily restricted from new movements.
* **FROZEN:** Requires manual intervention for reactivation.
* **CLOSED:** Final state, prohibiting further transactions.
**Example Command to Transition Account States:**
```bash
./luca transition /group/customers/ACCT2938 SUSPENDED
```
***
### **Best Practices for Creating Accounts**
1. **Use Clear References and avoid including personal information:**
* Example: `operational-account`, `ACCT2938`.
2. **Plan Wallet Configurations:**
* Predefine currencies and accounting types for each wallet.
3. **Organize Metadata:**
* Leverage tags and attributes to classify accounts for reporting and integration.
***
---
# 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/integrate-with-xyb-ledger/understanding-the-ledger-structure-charts-accounts-wallets/understanding-and-creating-accounts-in-the-ledger.md?ask=&goal=
```
`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.