# Historical balances API

Source: https://docs.settlemint.com/docs/api-reference/token-features/historical-balances
API reference for reading DALP historical-balances checkpoints, including the timestamp timepoint model and the holder-history endpoints used by integrations.



The `historical-balances` token feature records timestamped holder-balance and total-supply checkpoints for every token it tracks. It attaches without operator input on almost every instrument template, so you can read checkpoint data without any extra configuration. Voting-power snapshots, yield-period boundary checks, and audit reads all depend on these checkpoints. This page is the integration reference: for the operator workflow, see [Historical balances how-to](/docs/operators/token-features/historical-balances); for the canonical architecture model, strict versus non-strict lookup behaviour, and failure modes, see [Historical balances architecture](/docs/architects/components/token-features/historical-balances).

## Configuration [#configuration]

No `featureConfigs` entry required. The feature is self-contained and attaches when the selected template lists it in `requiredFeatures`.

## Reading snapshot data [#reading-snapshot-data]

Use the token historical-balances endpoints to read checkpoint data.

Feature-level reads use Unix timestamp timepoints because the feature clock reports `mode=timestamp`. Indexer-backed as-of reads use block numbers when the caller is working from indexed chain history.

| Endpoint                                                                                                          | Returns                                                                              |
| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `GET /api/v2/tokens/{tokenAddress}/historical-balances`                                                           | Paginated checkpoint rows for a token, including account rows and total-supply rows. |
| `GET /api/v2/tokens/{tokenAddress}/historical-balances/balance-at-block?account={holder}&timepoint={unixSeconds}` | Feature-level holder balance and total supply at a timestamp timepoint.              |
| `GET /api/v2/tokens/{tokenAddress}/historical-balances/holders-at-block?timepoint={unixSeconds}`                  | Paginated holder balances at a timestamp timepoint.                                  |
| `GET /api/v2/tokens/{tokenAddress}/historical-balances/{holderAddress}?atBlock={block}`                           | Indexer-backed holder balance at the latest checkpoint at or before a block number.  |

To reconstruct balances at or before a single block across one or more tokens, for audit or point-in-time reporting, use the [balance snapshot at a block](/docs/api-reference/token-features/historical-balances-at-block) endpoint.

For live balances and transfer history, see [Token holders and transfers](/docs/api-reference/tokens/token-holders-transfers). The historical-balances endpoints return checkpointed data only; use the holder and transfer routes when you need current state.

## Related [#related]

* [Voting power](/docs/api-reference/token-features/voting-power): uses historical-balances for snapshot weights.
* [Feature constraints](/docs/architects/components/token-features/feature-constraints)