# 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 read holders as of a past date for reporting, voting, and audit.



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.
* The holders tab includes an **As of date** picker that switches the list from live balances to a point-in-time snapshot. See [View holders as of a past date](#view-holders-as-of-a-past-date).
* 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.

## View holders as of a past date [#view-holders-as-of-a-past-date]

On the asset detail workspace's holders tab, use the **As of date** picker to read the holder list as it stood at a chosen point in time instead of the live balances.

1. Open the asset, then open the **Holders** tab.
2. Pick a date and time in the **As of date** field. The picker does not allow a future date.
3. The holders table reloads to show each holder's balance as of that timepoint. The address bar updates so the dated view is shareable as a link.
4. Clear the date with the control next to the picker to return to the live holders view.

A few rules keep the view honest:

* You cannot select a future date. The picker caps selection at the current time.
* Opening a shared link with a future or invalid date shows the live holders view rather than an empty table.
* A date before the asset was created also shows the live view, because the asset had no holders before it existed.
* An early in-range date with no recorded balances shows the holders table's empty state, not an error.

## 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).                        |
| Shared as-of link shows live holders, not the snapshot | The link carried a future, invalid, or pre-creation date, so the holders tab fell back to the live view. Re-pick a valid past date in the **As of date** field and share the refreshed link. |

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