Accounts

Accounts are the core of Ledger's model. Each account has a class, one or more currencies, and an optional parent — forming a hierarchy you can roll balances up. Every operation is scoped to your tenant, resolved from your signing credential.

Create an account

POST /api/v1/ledger/accounts

Body fields: class (required), currencies (required array), optional parent, liquidity_policy, overdraft_limits, and metadata. Returns the created account with status 201.

List and read

• GET /accounts — all accounts for your tenant
• GET /accounts/{id} — one account
• GET /accounts/{id}/children — direct children of an account
• GET /accounts/{id}/balances — balances, optionally filtered by ?currency=
• GET /accounts/{id}/entries — entry history, with ?currency= and ?limit=
• GET /accounts/{id}/subtree-balance — rolled-up balance across the subtree

Currencies

POST /api/v1/ledger/accounts/{id}/currencies

Add a currency to an existing account, with an optional overdraft_limit. Returns the updated account.

Update metadata

PATCH /api/v1/ledger/accounts/{id}

Pass { "metadata": { ... } }. Merge semantics: existing keys are preserved, and a key set to null is cleared. The body's metadata must be a plain object.

Lifecycle

• PATCH /accounts/{id}/suspend — suspend an account
• PATCH /accounts/{id}/unsuspend — restore a suspended account
• PATCH /accounts/{id}/close — close an account

Each returns the updated account.

Holds on an account

POST /api/v1/ledger/accounts/{id}/holds

Place a hold reserving available balance: body takes currency, amount (integer string), and optional metadata. Returns the hold with status 201.

GET /accounts/{id}/holds lists holds, filterable by ?currency= and ?state=active.

Next

• Transactions — posting balanced entries.
• Holds — releasing a hold.