Historical balances API
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; for the canonical architecture model, strict versus non-strict lookup behaviour, and failure modes, see Historical balances architecture.
Configuration
No featureConfigs entry required. The feature is self-contained and attaches when the selected template lists it in requiredFeatures.
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 endpoint.
For live balances and transfer history, see Token holders and transfers. The historical-balances endpoints return checkpointed data only; use the holder and transfer routes when you need current state.
Related
- Voting power: uses historical-balances for snapshot weights.
- Feature constraints
Token features API
Reference index for the eleven DALP token features and the Platform API endpoints that configure and operate them during asset creation and servicing.
Historical balance at-block snapshot API
Reconstruct holder and total-supply balances as of a specific block across one or more tokens in the active DALP system, for audit and point-in-time reporting.