Ledger Rail

Double-entry accounting and ledger management endpoints.

Overview

The Ledger rail provides:

• Double-entry bookkeeping
• Real-time balance tracking
• Account hierarchies
• Audit trails

Powered by our high-performance ledger engine for high-performance, strongly consistent transactions.

Endpoints

Create Account

POST /v1/ledger/accounts

const account = await iof.ledger.createAccount({
  name: "Customer Deposits",
  type: "liability",
  currency: "USD",
  parent: "acc_parent",
});

Response:

{
  "id": "acc_xyz",
  "name": "Customer Deposits",
  "type": "liability",
  "currency": "USD",
  "balance": 0,
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Balance

GET /v1/ledger/accounts/:id/balance

const balance = await iof.ledger.getBalance("acc_xyz");

Create Entry

POST /v1/ledger/entries

const entry = await iof.ledger.createEntry({
  description: "Murabaha payment received",
  lines: [
    { account: "acc_cash", debit: 5000 },
    { account: "acc_receivable", credit: 5000 },
  ],
  metadata: {
    contractId: "contract_123",
  },
});

Response:

{
  "id": "entry_abc",
  "status": "committed",
  "lines": [
    { "account": "acc_cash", "debit": 5000, "credit": 0 },
    { "account": "acc_receivable", "debit": 0, "credit": 5000 }
  ],
  "createdAt": "2024-01-15T10:30:00Z"
}

List Entries

GET /v1/ledger/entries

const entries = await iof.ledger.listEntries({
  account: "acc_xyz",
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  limit: 100,
});

Get Statement

GET /v1/ledger/accounts/:id/statement

const statement = await iof.ledger.getStatement("acc_xyz", {
  startDate: "2024-01-01",
  endDate: "2024-01-31",
});

Account Types

Type	Normal Balance	Description
asset	Debit	Resources owned
liability	Credit	Obligations owed
equity	Credit	Owner's stake
revenue	Credit	Income earned
expense	Debit	Costs incurred

Entry Status

Status	Description
pending	Awaiting commit
committed	Successfully recorded
voided	Entry voided

Consistency Guarantees

• All entries are ACID compliant
• Balances are strongly consistent
• No double-spending possible
• Complete audit trail

Webhooks

Event	Description
ledger.entry.created	Entry recorded
ledger.balance.changed	Balance updated

Next Steps

• Billing Rail - Usage metering
• Clearing Rail - Settlement