Balance snapshot at a block

Use the at-block snapshot endpoint when an auditor or integration needs to reconstruct what a holder owned, or what a token's supply was, as of a specific block. It reads the same checkpoint history as the per-token historical-balances reads, but answers a different question: balances at or before one block number. You address the query by token or by holder across the active system, rather than one token at a time.

Reach for this endpoint when you need point-in-time evidence: a balance proof for a dispute, a holder position for a regulatory snapshot, or a total supply figure tied to an exact block.

Endpoint

The endpoint reads checkpoint data for the caller's active system. It requires historical-balances read access. Results never cross system boundaries: a token or holder outside the active system returns no rows rather than an error, so the response cannot reveal whether an address exists in another tenant.

Required parameters

Every request needs two things:

• A block query parameter: the non-negative block number to read balances at or before.
• At least one discriminator filter: filter[tokenAddress][eq] or filter[account][eq]. A request with neither is rejected.

The block, tokenAddress, account, and kind inputs are exact-match selectors. They accept the eq operator only. Any other operator is rejected at the request boundary, so a query cannot silently match the wrong rows.

Read one holder across a token

Pass both a token and an account to read that holder's balance in that token as of the block.

curl --globoff "$DALP_API_URL/api/v2/historical-balances/at-block?block=8154000&filter[tokenAddress][eq]=0x00000000000000000000000000000000000000aa&filter[account][eq]=0xabcdef0000000000000000000000000000000001" \
  --header "X-Api-Key: $DALP_API_TOKEN"

The response is a paginated collection envelope with data, meta, and links:

{
  "data": [
    {
      "tokenAddress": "0x00000000000000000000000000000000000000aa",
      "account": "0xabcdef0000000000000000000000000000000001",
      "kind": "account",
      "balance": "1000",
      "balanceExact": "1000000000000000000000",
      "asOfBlockNumber": "8153120",
      "asOfBlockTimestamp": "2026-01-01T00:00:00.000Z",
      "asOfTxHash": "0x0000000000000000000000000000000000000000000000000000000000000045",
      "asOfLogIndex": 0
    }
  ],
  "meta": { "total": 1, "facets": {} },
  "links": {
    "self": "/v2/historical-balances/at-block?block=8154000&filter[tokenAddress][eq]=0x00000000000000000000000000000000000000aa&filter[account][eq]=0xabcdef0000000000000000000000000000000001&page[limit]=50&page[offset]=0&sort=account",
    "first": "/v2/historical-balances/at-block?block=8154000&filter[tokenAddress][eq]=0x00000000000000000000000000000000000000aa&filter[account][eq]=0xabcdef0000000000000000000000000000000001&page[limit]=50&page[offset]=0&sort=account",
    "prev": null,
    "next": null,
    "last": "/v2/historical-balances/at-block?block=8154000&filter[tokenAddress][eq]=0x00000000000000000000000000000000000000aa&filter[account][eq]=0xabcdef0000000000000000000000000000000001&page[limit]=50&page[offset]=0&sort=account"
  }
}

Each row reports the balance from the latest checkpoint at or before the requested block. The asOf fields point to the checkpoint that produced the balance, so you can cite the exact block, timestamp, and transaction the figure came from.

Read every holder of a token

Pass only a token to read all of its holders as of the block. Total-supply rows use the zero address as the account.

curl --globoff "$DALP_API_URL/api/v2/historical-balances/at-block?block=8154000&filter[tokenAddress][eq]=0x00000000000000000000000000000000000000aa&page[limit]=50" \
  --header "X-Api-Key: $DALP_API_TOKEN"

To narrow the result to holders only or to the total-supply row, add filter[kind][eq]=account or filter[kind][eq]=totalSupply. Results sort by account, and equal-key rows stay in a stable order so offset pages do not shift between requests.

Pagination and sorting

The endpoint returns at most 50 rows per page by default and 200 at most. Set page[limit] and page[offset] to walk a large holder set, and follow the links in each response. Every pagination link carries the original block through, so following next or last reads the same point in time as the first page. Sort by account with sort=account or sort=-account.

The meta.facets object is always present but currently returns an empty map. Facet counts for the kind field are not computed by this endpoint, so callers cannot rely on it to size holder versus total-supply segments before paging.

Response fields

Reading balances before activity

When you request a holder and token together and no checkpoint exists at or before the block, the response still returns a row. If the holder already held a balance during the window between the feature's enable block and their first recorded activity, the row reports that seeded pre-activity balance. If no balance applied, the row reports a no-checkpoint kind with a zero balance and null checkpoint fields.

This keeps a known holder and token from disappearing from the result just because the block falls before their first transfer. A no-checkpoint zero row means the holder owned nothing at that block, not that the query failed.

Troubleshooting

Related

• Historical balances API: per-token checkpoint and as-of reads.
• Token holders and transfers: current holder state and transfer history.
• API reference