Historical Top Holders

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

post

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

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

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

chainstring · enumRequired

Blockchain chain

Example: ethereumPossible values:

token_addressstringRequired

Token contract address

Example: 0x6982508145454ce325ddbe47a25d4ec3d2311933

as_of_datestringRequired

Historical date (YYYY-MM-DD) to compute holder balances at.

Example: 2025-06-15

label_typestring · enumOptional

Holder filter bucket. 'all_holders' returns everyone; the others restrict to a specific label class.

Default: all_holdersExample: all_holdersPossible values:

filtersany ofOptional

Optional filters applied server-side

order_byany ofOptional

Sort order. Defaults to token_amount DESC. Only the first element is used.

apply_blacklist_filterbooleanOptional

When True, exclude blacklisted addresses from the results. Defaults to True.

Default: trueExample: true

Responses

200

Historical TGM top holders data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

402

Payment Required

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /api/v1beta1/tgm/historical-top-holders HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 314

{
  "chain": "ethereum",
  "token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "as_of_date": "2025-06-15",
  "label_type": "all_holders",
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "include_sm_labels": [
      "Fund",
      "Smart Trader"
    ]
  },
  "order_by": [
    {
      "field": "token_amount",
      "direction": "ASC"
    }
  ],
  "apply_blacklist_filter": true
}

{
  "data": [
    {
      "token_symbol": "PEPE",
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "address_label": "Whale",
      "token_amount": 1000000,
      "total_outflow": 50000,
      "total_inflow": 1050000,
      "balance_change_24h": 1000,
      "balance_change_7d": 5000,
      "balance_change_30d": 15000,
      "ownership_percentage": 0.025,
      "value_usd": 50000
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}