Skip to main content

​
What are ledgers?

Ledgers are containers that organize and group related balances in your Blnk implementation. Think of a ledger as a financial book that holds multiple account balances. Each ledger represents a logical grouping of balances, such as all customer wallets, merchant accounts, or internal operational accounts. Ledgers help you:
  • Organize balances by business function, customer segment, or product type
  • Isolate financial operations for different parts of your application
  • Track and report on specific groups of balances
  • Apply different rules or configurations to different balance groups

​
Ledger structure

The Ledger model in Blnk contains the following fields:
​
ledger_id
string
Unique identifier for the ledger (auto-generated)
​
name
string
required
Human-readable name for the ledger
​
created_at
timestamp
When the ledger was created
​
meta_data
object
Custom metadata for storing additional information about the ledger

​
Example ledger object

{
  "ledger_id": "ldg_abc123def456",
  "name": "Customer Wallets",
  "created_at": "2024-03-04T10:30:00Z",
  "meta_data": {
    "project_id": "proj_123",
    "region": "us-east",
    "environment": "production"
  }
}

​
Creating a ledger

You can create a ledger by sending a POST request to the /ledgers endpoint: 
curl -X POST http://localhost:5001/ledgers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Wallets",
    "meta_data": {
      "project_id": "proj_123"
    }
  }'

{
  "ledger_id": "ldg_abc123def456",
  "name": "Customer Wallets",
  "created_at": "2024-03-04T10:30:00Z",
  "meta_data": {
    "project_id": "proj_123"
  }
}

​
Organizing balances with ledgers

Once you have a ledger, you can create balances within it. Each balance must belong to exactly one ledger. This relationship helps you organize your financial structure.

​
Common ledger patterns

Customer ledger

Group all customer wallet balances for easy tracking and reporting

Merchant ledger

Separate merchant settlement accounts from customer balances

Internal ledger

Track operational accounts like fees, escrow, or reserves

Currency ledger

Organize balances by currency for multi-currency operations

​
Example: Multi-ledger setup

# Create customer wallet ledger
curl -X POST http://localhost:5001/ledgers \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Wallets"}'

# Create merchant ledger
curl -X POST http://localhost:5001/ledgers \
  -H "Content-Type: application/json" \
  -d '{"name": "Merchant Accounts"}'

# Create internal operations ledger
curl -X POST http://localhost:5001/ledgers \
  -H "Content-Type: application/json" \
  -d '{"name": "Platform Operations"}'
Now you can create balances in each ledger: 
# Create a customer balance
curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "ldg_customer123",
    "currency": "USD"
  }'

# Create a merchant balance
curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "ldg_merchant456",
    "currency": "USD"
  }'

​
Managing ledgers

​
Retrieve a ledger

curl http://localhost:5001/ledgers/ldg_abc123def456

​
List all ledgers

# Get ledgers with pagination
curl "http://localhost:5001/ledgers?limit=20&offset=0"

​
Update a ledger

You can update the name of an existing ledger: 
curl -X PUT http://localhost:5001/ledgers/ldg_abc123def456 \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Customer Wallets"}'

​
Filter ledgers

You can filter ledgers using query parameters: 
# Filter by name
curl "http://localhost:5001/ledgers?name_eq=Customer%20Wallets"

# Filter by creation date
curl "http://localhost:5001/ledgers?created_at_gte=2024-01-01"

# Filter by metadata
curl "http://localhost:5001/ledgers?meta_data.project_id_eq=proj_123"
Ledgers cannot be deleted once created. This ensures data integrity and maintains a complete audit trail of your financial operations.

​
Best practices

Choose clear, descriptive names that indicate the purpose of the ledger. Avoid generic names like “Ledger 1” or “Main”.Good examples:
  • “Customer USD Wallets”
  • “Merchant Settlement Accounts”
  • “Platform Fee Revenue”
Use the meta_data field to store additional context about your ledgers. This can include:
  • Project or tenant identifiers
  • Geographic regions
  • Environment tags (production, staging)
  • Business unit information
Think about how you’ll need to query and report on your data. Create ledgers that align with your business structure and reporting requirements.Consider organizing by:
  • Customer type (retail, business, premium)
  • Product or service line
  • Currency or region
  • Operational function (trading, settlement, fees)
While you can create many ledgers, keeping the number reasonable makes your system easier to understand and maintain. Aim for logical groupings rather than creating a ledger for every individual use case.

​
Next steps

Balances

Learn how to create and manage balances within ledgers

Transactions

Record financial movements between balances

Build docs developers (and LLMs) love

Get started for freeTalk to us