# Historical balances

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



The historical-balances token feature records a balance checkpoint for every holder at every block where their balance changes. 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.

For the architecture reference, see [Historical balances](/docs/architects/components/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, and transfer writes a balance checkpoint for the affected holders.
* 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/developers/api-integration/tokens/token-holders-transfers).
* Voting snapshots (where voting-power is also attached) use the historical-balances checkpoint at the snapshot block.

## Operating considerations [#operating-considerations]

* The feature stores checkpoints, not a full event replay. Reading the balance at an exact block returns the checkpoint that applied at that block, which is the holder's correct balance for any block-range query.
* The feature does not retain pre-deployment history. Snapshots start at the asset deployment block.
* Checkpoints persist for the asset's lifetime. Burning 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 block is after the asset deployment block and the holder had a non-zero balance at that point.                                                    |
| Voting snapshot returns wrong weights        | Confirm the snapshot block 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/developers/api-integration/tokens/token-holders-transfers)
* [System templates catalog](/docs/operators/asset-creation/system-templates)