# Historical balances

Source: https://docs.settlemint.com/docs/operators/token-features/historical-balances
How the historical-balances token feature records timestamped holder and supply checkpoints, and how operators use those snapshots for reporting, voting, and audit reads.



The historical-balances token feature records timestamped checkpoints when holder balances or total supply change. Reports, voting snapshots, dividend record-date reads, and audit reconciliation queries use those checkpoints to answer "what did each holder own at time T" without scanning the full event log.

Use this page when you operate an issued asset. For the canonical architecture explanation and lookup rules, see [Historical balances architecture](/docs/architects/components/token-features/historical-balances). For endpoint details, see the [historical-balances API reference](/docs/api-reference/token-features/historical-balances).

## When it attaches [#when-it-attaches]

Historical-balances appears as a required feature on almost every system template. The asset designer attaches it during deployment with no operator input. The [system templates catalog](/docs/operators/asset-creation/system-templates) names every template that includes it.

## What you configure [#what-you-configure]

Nothing during asset creation. The feature has no operator-configurable parameters. The Asset Designer marks it as self-contained.

## What you operate [#what-you-operate]

After deployment, the feature runs automatically:

* Every mint, burn, redemption, and transfer writes timestamped checkpoints for the affected holders and, when supply changes, total supply.
* The asset detail workspace's holders tab reads from the checkpoint table for the holders list and holder-balance history.
* Reports and integrations read historical balances through the [holders and transfers API](/docs/api-reference/tokens/token-holders-transfers).
* Voting snapshots (where voting-power is also attached) use the historical-balances checkpoint for the selected record-date timepoint.

## Operating considerations [#operating-considerations]

* The feature stores checkpoints, not a full event replay. Feature-level historical-balance reads use Unix timestamp timepoints; indexer-backed as-of holder reads use block numbers resolved by the UI or integration.
* The feature does not retain pre-deployment history. Snapshots start at the asset deployment block.
* Checkpoints persist for the asset's lifetime. Burning or redeeming a holder's full balance writes a zero checkpoint; later mints to the same wallet write new checkpoints starting from zero.

## Troubleshooting [#troubleshooting]

| What you see                                 | What to check                                                                                                                                                         |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Historical balance returns zero unexpectedly | Confirm the queried timepoint is after the asset deployment timestamp and the holder had a non-zero balance at that point.                                            |
| Voting snapshot returns wrong weights        | Confirm the selected record-date timepoint matches the intended record date and that voting-power attached during deployment.                                         |
| Reporting integration returns stale data     | The historical-balances feature writes to the indexer; the indexer must be caught up. See [Blockchain monitoring](/docs/developers/operations/blockchain-monitoring). |

## Read next [#read-next]

* [Historical balances architecture](/docs/architects/components/token-features/historical-balances)
* [Token holders and transfers API](/docs/api-reference/tokens/token-holders-transfers)
* [System templates catalog](/docs/operators/asset-creation/system-templates)