---
title: "Get historical \"Token God Mode\" (TGM) top holders (Beta)"
method: POST
path: "/api/v1beta1/tgm/historical-top-holders"
tags: ["Token God Mode"]
---

# Get historical "Token God Mode" (TGM) top holders (Beta)

`POST /api/v1beta1/tgm/historical-top-holders`

**Beta — subject to breaking changes.**

Top token holders at a historical `as_of_date` with temporally-correct labels.
Labels are resolved from label history tables to avoid forward-looking bias.

**Key differences from `/tgm/holders`:**
- Accepts an explicit `as_of_date` (Date) instead of returning current state
- Labels resolved at `as_of_date`, not from current-state dictionaries
- `value_usd` priced at the historical median price for `as_of_date`
- The `filters.include_sm_labels` field only sub-restricts the `smart_money` bucket;
  to switch buckets use the top-level `label_type` field
- No dust-filter default — set filters at the caller side if needed

**Performance:** Can be slow for high-volume tokens (USDC, native ETH, etc.).

## Request body

- TGMHistoricalTopHoldersRequest — Request model for the historical top holders endpoint. Returns the top holders of a token at a historical `as_of_date` with temporally-correct labels resolved from label history tables to avoid forward-looking bias. Can be slow for high-volume tokens (e.g. USDC, ETH).
  - `chain` 'base' | 'bnb' | 'ethereum' | 'solana', required — Chains supported for the TGM historical endpoints (pnl-leaderboard, who-bought-sold, top-holders, token-flow-summary).
  - `token_address` string, required — Token contract address
  - `as_of_date` string, required — Historical date (YYYY-MM-DD) to compute holder balances at.
  - `label_type` 'all_holders' | 'whale' | 'public_figure' | 'exchange' | 'smart_money' — Holder label-type filter for the historical top holders endpoint.
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` TGMHistoricalTopHoldersFilters — Filters for the historical top holders endpoint. Use `label_type` (top-level field) to choose the holder bucket; this filter only sub-restricts the smart_money bucket.
    - `include_sm_labels` HistoricalLabelType[] — When label_type is 'smart_money', restrict to these specific smart-money labels (e.g. ['Fund']). Empty = all smart-money labels.
  - `order_by` SortOrderTGMHistoricalTopHoldersSortField[] — Sort order. Defaults to token_amount DESC. Only the first element is used.
    - `field` 'token_amount' | 'value_usd' | 'total_outflow' | 'total_inflow' | 'balance_change_24h' | 'balance_change_7d' | 'balance_change_30d' | 'ownership_percentage', required — Sortable fields for the historical top holders endpoint.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.
  - `apply_blacklist_filter` boolean — When True, exclude blacklisted addresses from the results. Defaults to True.

## Response `200`

Historical TGM top holders data

- TGMHistoricalTopHoldersResponse — Response model for the historical top holders endpoint.
  - `data` TGMHistoricalTopHolder[], required — List of historical top-holder records
    - `token_symbol` string — Token symbol resolved at the queried date
    - `address` string — Holder wallet address
    - `address_label` string — Temporally-correct label resolved at as_of_date
    - `token_amount` number — Holder's cumulative token balance at as_of_date
    - `total_outflow` number — Cumulative tokens sent by the holder up to as_of_date
    - `total_inflow` number — Cumulative tokens received by the holder up to as_of_date
    - `balance_change_24h` number — Net token balance change on as_of_date
    - `balance_change_7d` number — Net token balance change over the 7 days ending at as_of_date
    - `balance_change_30d` number — Net token balance change over the 30 days ending at as_of_date
    - `ownership_percentage` number — Fraction of total supply held by this address (0-1)
    - `value_usd` number — USD value of the holder's balance at the historical price for as_of_date
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)