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. 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. 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. |
See Token holders and transfers for the broader token holder and transfer contract.
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.
Voting Power
API reference for the DALP Voting Power token feature, including delegation mutations, delegation history, and current distribution reads.