# 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. It attaches without operator input on almost every instrument template.

Use this page as 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.  |

See [Token holders and transfers](/docs/api-reference/tokens/token-holders-transfers) for the broader token holder and transfer contract.

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