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

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