All endpoints
Every operation in the ledger contract, in one list. Read Reaching the ledger first: this service is not on the public gateway.
Ledgers
A consumer's own ledgers; each carries its own vocabulary, periods, and event sequence.
List the caller's ledgers
Every ledger this consumer owns. Ledgers owned by anyone else are not listed and are not reachable: ownership is the only scope the API has.
Create a ledger owned by the caller
Creates a ledger owned by the calling consumer.
Read one ledger
Reads one ledger the caller owns. A ledger id belonging to another consumer answers ledger_not_found (404), byte for byte the same answer as an id that was never minted, so ownership never leaks th...
Vocabulary
The transaction types, account purposes, and commodities a ledger will accept, registered per ledger and enforced by foreign keys.
Read the registered vocabulary
Everything this ledger has registered: transaction types, purposes with their sharded flag, and commodities.
Register vocabulary (idempotent, grows only)
Registers the transaction types, account purposes and commodities this ledger will accept.
Accounts
Opening accounts on their natural key, their credit limit and lifecycle, and what one account is worth now, then, or over a range.
Create an account
Opens an account on the natural key (ledger, owner_type, owner_id, purpose, commodity, shard).
Look up an owner's account by its natural key
The natural key includes commodity. When the owner holds the purpose in a single commodity, commodity may be omitted; if several match, the lookup refuses as a conflict rather than returning an arb...
Read one account
Reads one account: its natural key, status, credit limit, version and current balance.
Set the account's credit limit (absolute, audited by the caller)
Sets the account's credit limit to an absolute value, not a delta, so a retry of the same request lands on the same limit.
Current balance, reservations, and available funds
The account's current balance, the total still reserved by active pendings, and the available figure a caller should spend against: balance minus reservations, plus the credit limit.
Balance at a moment in effective time
Reconstructs the balance as of a moment in *effective* time, not wall-clock insert time.
Opening balance, movements, closing balance over a range
Opening balance, the movements in between, and closing balance over a range of effective time.
Freeze an account (no postings, no new reservations)
Freezes an account: no new postings touch it and no new funds may be reserved against it.
Return a frozen account to service
Returns a frozen account to service. Closure is terminal, so a closed account cannot be unfrozen: that refuses with account_closed.
Close an account (terminal; requires zero balance, nothing reserved)
Closes an account for good. Terminal, and deliberately strict: the balance must be exactly zero and no pending may still be active, otherwise the request is refused as invalid with the offending fi...
System accounts
Sharded fee, float, and settlement accounts, provisioned as a set and read in aggregate.
Provision the shard set of a sharded-purpose system account (idempotent)
Provisions the full shard set for a system account whose purpose is registered as sharded.
One shard of a system account; random, or stable per seed
Returns one shard of a system account. Without seed the shard is chosen at random, which is what a fresh posting wants.
Total balance across a system account's shards
The total across every shard of a system account, summed under a lock so the figure is a real instant rather than a drifting scan.
Postings
Balanced money movement; one transaction, an atomic batch, or a dry run against live state.
Post one balanced transaction
Posts one balanced transaction: legs in integer minor units that sum to zero per commodity, or nothing is written at all.
Post many transactions atomically, in order
Posts many transactions as one atomic unit, in request order: every transaction commits or none does, under a single Idempotency-Key whose stored result covers the whole batch.
Validate a posting against live state without committing
Walks the entire posting path against live state - vocabulary, account locks, floors, owner floors, preconditions, limit claims, closed periods - and then rolls everything back.
Pending postings
The reserve half of a two-phase posting; hold with a TTL, then post bounded by the reservation, or void.
Reserve funds (the pending phase of a two-phase posting)
The reserve half of a two-phase posting.
Read one pending, whatever its state
Reads one pending in any state - pending, posted, voided or expired.
Cancel a reservation without postings
Cancels an active reservation and releases the funds, writing no entries at all: a voided pending leaves no trace in the books beyond its own record, because nothing ever moved.
Exchanges
Cross-commodity groups posted atomically with the rate stored on the transaction; per-commodity zero-sum is never relaxed.
Post a cross-commodity exchange group atomically
Posts a cross-commodity exchange as one atomic group.
Read one exchange with its transaction ids
Reads one exchange group: the commodities, the stored rate, and the ids of every transaction created with it.
Transactions
Reading what was posted, with legs and linkage, and reversing it by posting the linked mirror.
Page transactions newest-first with resolved legs
Pages the ledger's transactions newest-first with their legs already resolved, optionally filtered by transaction type.
Read one transaction with legs and linkage
Reads one transaction with its legs and its linkage: which transaction it reverses, which reversed it, and the exchange group it belongs to, if any.
Post the exact mirror, linked and once-only
Posts the exact mirror of a transaction - same accounts, same amounts, opposite directions - and links the two, so the original stays in the books and the correction is visible as a correction.
Periods
Period close with per-account checkpoints, the closed-period ladder, and trial balance export.
List closed periods oldest-first
The ledger's closed periods oldest-first - the ladder a close appends to.
Close a period through an effective moment
Closes a period through an effective moment: it checkpoints every account's balance in effective time, raises the ledger's closed-through mark, and from then on refuses any posting whose effective_...
Opening, movement, and closing per account for one period
Opening balance, movement and closing balance per account for one closed period, computed from that period's checkpoints.
Scheduled postings
Postings the service executes itself at their effective moment, with an inspectable end state.
Store a posting the service executes at its effective moment
Stores a posting the service will execute itself at post_at, rather than asking the caller to stay alive until then.
Read one schedule, whatever its state
Reads one schedule in any state - scheduled, posted, failed or cancelled - with txn_id once it has posted and last_error when it failed.
Cancel a schedule that has not executed
Cancels a schedule that has not run yet.
Read views
The owner-scoped and ledger-wide read views consumers build their own screens and reconciliation from.
Every balance one owner holds, across purposes and commodities
Every balance one owner holds in this ledger, across every purpose and commodity, each row already carrying what is reserved against it and what is available (balance minus reservations, plus the c...
Page one owner's entries across all its accounts, newest first
limit counts transactions, not entries: every entry of a transaction is returned on the same page, so a page boundary can never split a transaction and the txn-id cursor never skips entries.
One account's entries since a moment, newest first
A full page means more may remain; pass the last entry_id as cursor to continue.
Balance and account count per owner type, purpose, and commodity
Balance and account count rolled up by owner type, purpose and commodity - the whole ledger in a few rows.
Event feed
The per-ledger sequenced feed, served in (xact, seq) order for read models and consumer-side reconciliation.
Idempotency
The stored-result probe a caller repairs from after losing its own commit.
Service
Unauthenticated liveness and build identity, for probes and deployment checks.
Liveness probe
Liveness only. The handler answers as soon as the process is serving and touches neither the database nor any consumer state, so a degraded dependency does not take the container down.
Build identity
Name and version of the running build, so a deployment can be identified without credentials.