| Goal | Use |
|---|---|
| Report what you owe and explain changes | Liability and rollforward |
| Reconcile cross-program redemptions | Redemption attribution |
| Trace a number to its source | Journal entries and statements |
| Monitor program performance | Ledger summary and program activity |
| Verify the ledger is tamper-free | Integrity attestation |
asset_id, asset_symbol, and scale, and Scrip never sums values across assets.
Liability
Outstanding liability is the value participants and groups currently hold. This is the number that belongs on a balance sheet.| Parameter | Description |
|---|---|
as_of | Point in time to report on (RFC 3339). Defaults to now |
program_id / asset_id | Optional scope filters, combinable |
by_bucket | Split each row into AVAILABLE, HELD, and DEFERRED |
as_of queries are stable: ask for June 30 in July, or in December, and get the same answer. Close your books against this number and every other report reconciles back to it.
Liability Rollforward
The rollforward explains a period: opening balance, every movement decomposed into named categories, closing balance.closing - opening. There is no residual bucket, and unclassifiable activity fails the request rather than misstating the report.
A typical close: run liability at from and to, run the rollforward for the window, and verify that opening plus the itemized lines equals closing for each asset. This is the artifact to hand an auditor.
Redemption Attribution
For sharedLOT-mode assets, break gross redemptions down by the program that issued the consumed value and the program used as the redemption channel:
program_id to filter by redemption channel or asset_id to select one LOT-mode asset. The report is gross and does not net reversals. It does not allocate reversals back to issuer/channel cells. Use liability rollforward, ledger summary, redemption records, or journal entries for reversal-aware financial reporting. SIMPLE-mode assets do not carry the lot lineage required for issuer attribution.
See Multi-Program Balances for how this report differs from ordinary per-program liability and activity views.
Expiration Schedule
ForLOT-mode assets, project when outstanding value expires:
never_expiring, expiring_before_window (past expires_at but not yet swept, still liability), and expiring_after_window figures. Together they sum exactly to total_outstanding. Held and deferred lots are included, since they still expire.
Use this for breakage estimation and forecasting how much value expires in the next 30, 60, or 90 days. See Lots & Expiration for the underlying lifecycle.
Ledger Integrity
Verify the ledger is internally consistent and tamper-free:chain_head hash. Pin that hash externally at each close; because every entry’s hash depends on all prior entries, any later alteration of history becomes detectable against your pinned value. See the Ledger guide for how the hash chain works.
Statements
Statements give a bank-statement view with running balances, for support tooling, end-user receipts, or per-account audits:asset_id is required, since a running balance is only meaningful within one asset, and bucket optionally scopes the view to AVAILABLE, HELD, or DEFERRED.
from/to control which rows are returned, but balances are always computed over the account’s full history. A windowed statement’s closing balance equals the account’s balance as of to, and pagination never desyncs the running balance.
For raw movement lists without running balances, the activity endpoints remain available: GET /v1/participants/{id}/activity/history and GET /v1/programs/{id}/history, including dual time filters (from/to on record time, event_from/event_to on event time).
Ledger Summary
Per-asset totals and flows for dashboards:| Field | Description |
|---|---|
total_issued | Cumulative credits to participants (all time) |
total_redeemed | Cumulative value redeemed, net of reversals (all time) |
total_expired | Cumulative value expired via lot expiration (all time) |
total_forfeited | Cumulative value forfeited via explicit forfeit actions (all time) |
current_balance | Net outstanding liability |
participant_count | Distinct participants holding this asset |
scale | The asset’s decimal scale |
from/to for a per-asset period rollforward (opening, flows, closing). Period redemption figures are gross, so a reversal after the window closes doesn’t rewrite history; all-time figures are net of reversals.
The ledger summary’s period view includes an
other_adjustments_net residual. For audit work, prefer the liability rollforward, which decomposes every movement with no residual.Program Activity
Compare programs, or fetch one program’s scorecard:| Field | Window |
|---|---|
event_count, total_issued, total_redeemed | from/to when provided, otherwise all time |
journal_count, unique_participants, last_activity_at | Always all time |
by_asset[] | Issued/redeemed per asset with scale, same window as the totals |
since to exclude dormant programs. Prefer the by_asset rows over the top-level totals for any program with more than one asset, since the top-level figures sum across assets.
Journal Entries
The journal is the full audit trail. Every aggregate above traces down to these rows. Each entry is an atomic set of postings (debits and credits) that balance to zero.GET /v1/journal-entries, and fetch one entry with all its postings and its entry_hash with GET /v1/journal-entries/{id}. For the full filter reference (program, entity, asset, bucket, action_type, reference_id, time and amount ranges) and entry detail semantics, see the Ledger guide.
Common Queries
| Goal | Endpoint | Notes |
|---|---|---|
| Balance-sheet liability at month end | Liability | as_of the period end |
| Explain the change in liability | Liability Rollforward | Lines sum exactly to closing minus opening |
| Settle issuer vs. redemption channel | Redemption Attribution | Gross LOT-mode matrix |
| Breakage / expiration forecast | Expiration Schedule | granularity=month |
| Participant account statement | Statements | Running balances, opening/closing |
| Prove the ledger is untampered | Ledger Integrity | Pin chain_head at each close |
| Per-asset dashboard tile | Ledger Summary | program_id + asset_id |
| Program comparison | Program Activity | since, by_asset |
| Debug a specific event | Event Impact | Full causal chain: rules, postings, state changes |
| Trace any number to its entries | Journal Entries | The ground truth |