> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporting

> Liability, redemption attribution, statements, and the journal audit trail

Scrip's reporting endpoints serve five kinds of work. Every number is computed in real time from the same double-entry ledger, so the reports always reconcile with each other.

| Goal                                    | Use                                                                         |
| --------------------------------------- | --------------------------------------------------------------------------- |
| Report what you owe and explain changes | [Liability](#liability) and [rollforward](#liability-rollforward)           |
| Reconcile cross-program redemptions     | [Redemption attribution](#redemption-attribution)                           |
| Trace a number to its source            | [Journal entries](#journal-entries) and [statements](#statements)           |
| Monitor program performance             | [Ledger summary](#ledger-summary) and [program activity](#program-activity) |
| Verify the ledger is tamper-free        | [Integrity attestation](#ledger-integrity)                                  |

Amounts in finance reports are always denominated per asset. Each row carries `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.

```bash theme={null}
GET /v1/reports/liability?as_of=2026-06-30T23:59:59Z
```

| 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` |

Because the ledger is immutable, `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.

```bash theme={null}
GET /v1/reports/liability-rollforward?from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z
```

For each asset and program, the response itemizes issued, issuance returns, redeemed, redemption receipts, redemption reversals, reversal clawbacks, forfeited, expired, debited, transfers, and bucket movements. The lines sum exactly to `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 shared `LOT`-mode assets, break gross redemptions down by the program that issued the consumed value and the program used as the redemption channel:

```bash theme={null}
GET /v1/reports/redemption-attribution?from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z
```

Each row is one asset, channel program, and issuer program cell. Diagonal cells are same-program redemptions. Off-diagonal cells are cross-program flows you can use for partner settlement. The response preserves rows with unknown issuer lineage under a null issuer so the matrix still reconciles to gross channel redemption totals.

Use `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](/guides/multi-program-balances#how-reporting-attributes-redemptions) for how this report differs from ordinary per-program liability and activity views.

## Expiration Schedule

For `LOT`-mode assets, project when outstanding value expires:

```bash theme={null}
GET /v1/reports/expiration-schedule?from=2026-07-01T00:00:00Z&to=2027-06-30T23:59:59Z&granularity=month
```

Each asset's response buckets outstanding lot value by expiry period, with separate `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](/guides/lots-and-expiration) for the underlying lifecycle.

## Ledger Integrity

Verify the ledger is internally consistent and tamper-free:

```bash theme={null}
GET /v1/reports/integrity
```

Four checks run in one snapshot: postings balance to zero, value conservation, hash-chain validity, and unsealed-entry count. The response includes the current `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](/guides/ledger#integrity) 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:

```bash theme={null}
# Participant statement
GET /v1/participants/{id}/statement?asset_id=asset-uuid

# Program wallet statement
GET /v1/programs/{id}/statement?asset_id=asset-uuid
```

Each row is a posting with the balance after it. The response includes opening and closing balances for the window. `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:

```bash theme={null}
GET /v1/reports/ledger-summary?program_id=program-uuid&asset_id=asset-uuid
```

| 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                                          |

Both filters are optional and combinable. Add `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.

<Note>
  The ledger summary's period view includes an `other_adjustments_net` residual. For audit work, prefer the [liability rollforward](#liability-rollforward), which decomposes every movement with no residual.
</Note>

## Program Activity

Compare programs, or fetch one program's scorecard:

```bash theme={null}
GET /v1/reports/program-activity?program_id=program-uuid
```

| 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 |

Use `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.

```bash theme={null}
GET /v1/journal-entries?program_id=program-uuid
```

List entries with `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](/guides/ledger#filtering).

## Common Queries

| Goal                                 | Endpoint                                               | Notes                                             |
| ------------------------------------ | ------------------------------------------------------ | ------------------------------------------------- |
| Balance-sheet liability at month end | [Liability](#liability)                                | `as_of` the period end                            |
| Explain the change in liability      | [Liability Rollforward](#liability-rollforward)        | Lines sum exactly to closing minus opening        |
| Settle issuer vs. redemption channel | [Redemption Attribution](#redemption-attribution)      | Gross LOT-mode matrix                             |
| Breakage / expiration forecast       | [Expiration Schedule](#expiration-schedule)            | `granularity=month`                               |
| Participant account statement        | [Statements](#statements)                              | Running balances, opening/closing                 |
| Prove the ledger is untampered       | [Ledger Integrity](#ledger-integrity)                  | Pin `chain_head` at each close                    |
| Per-asset dashboard tile             | [Ledger Summary](#ledger-summary)                      | `program_id` + `asset_id`                         |
| Program comparison                   | [Program Activity](#program-activity)                  | `since`, `by_asset`                               |
| Debug a specific event               | [Event Impact](/api-reference/events/get-event-impact) | Full causal chain: rules, postings, state changes |
| Trace any number to its entries      | [Journal Entries](#journal-entries)                    | The ground truth                                  |