# Nansen AI Historical Top Holders > Nansen AI Historical Top Holders is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.25/call, status unknown (last checked 2026-09-16). Returns the top token holders for a specific token contract at a historical date, with optional label-type filtering and blacklist exclusion. ## Facts - Endpoint: GET https://api.nansen.ai/api/v1beta1/tgm/historical-top-holders - Price: $0.25/call - Payment: x402 - Status: unknown - Last checked: 2026-09-16 - Activations on Zero: 0 - Tags: x402, finance - Canonical page: https://www.zero.xyz/c/nansen-ai-historical-top-holders-4ce20f7f - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_WI0JaX6z6uZ1EQrPRrUF9 Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently. ## How to call it through Zero Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`): ```sh zero fetch --capability nansen-ai-historical-top-holders-4ce20f7f ``` Example prompt: Show me the top holders of the token at address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on the Ethereum chain as of 2024-06-30, filtering to only smart money label types and excluding blacklisted addresses. ## When to prefer this Use this endpoint when you need a point-in-time historical snapshot of top token holders, particularly when you want to identify labeled entities (smart money, funds, exchanges) that held a token on a specific past date. Prefer this over current-holder endpoints when historical analysis, backtesting, or trend comparison is needed. ## Known failure modes - Invalid or unsupported chain identifier returns an error - Token address not found or not indexed returns empty results - as_of_date in the future or too far in the past may return no data - Invalid label_type filter returns an error or empty set - Malformed pagination parameters cause a 400 error - Payment not attached or insufficient causes a 402 response ## How this service works **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.). ## Output A ranked list of the top token holders for the specified token contract at the given historical date, including holder addresses, their labeled types (e.g. smart money, fund, exchange), token balances, and sort order by token amount. Blacklisted addresses are excluded by default. ## Request schema (JSON Schema) ```json { "type": "object", "title": "TGMHistoricalTopHoldersRequest", "required": [ "chain", "token_address", "as_of_date" ], "properties": { "chain": { "enum": [ "arbitrum", "avalanche", "base", "bnb", "ethereum", "hyperevm", "injective", "iotaevm", "linea", "mantle", "mantra", "monad", "near", "optimism", "plasma", "polygon", "ronin", "scroll", "sei", "solana", "sonic", "starknet", "sui", "ton", "tron" ], "type": "string", "title": "TGMChain", "description": "Chains supported in TGM (Token God Mode) endpoints." }, "filters": { "anyOf": [ { "type": "object", "title": "TGMHistoricalTopHoldersFilters", "properties": { "include_sm_labels": { "anyOf": [ { "type": "array", "items": { "enum": [ "30D Smart Trader", "90D Smart Trader", "180D Smart Trader", "Fund", "Smart Trader", "Smart Dex Trader", "30D Smart Dex Trader", "90D Smart Dex Trader", "180D Smart Dex Trader", "Public Figure", "Exchange", "Whale", "BananaGun Bot User", "Top Maestro Bot User", "Top BananaGun Bot User", "Maestro Bot User", "Early MAGIC Miner", "First Mover LP", "First Mover Staking", "Profitable LP", "Smart HL Perps Trader" ], "type": "string", "title": "HistoricalLabelType", "description": "Filter by entity label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data." } } ], "title": "Include Sm Labels", "examples": [ [ "Fund", "Smart Trader" ] ], "description": "When label_type is 'smart_money', restrict to these specific smart-money labels (e.g. ['Fund']). Empty = all smart-money labels." } }, "description": "Filters for the historical top holders endpoint.\n\nUse `label_type` (top-level field) to choose the holder bucket; this filter only\nsub-restricts the smart_money bucket.", "additionalProperties": false } ], "description": "Optional filters applied server-side" }, "order_by": { "anyOf": [ { "type": "array", "items": { "type": "object", " … (truncated) ``` ## Response schema (JSON Schema) ```json { "type": "object", "title": "TGMHistoricalTopHoldersResponse", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "title": "TGMHistoricalTopHolder", "properties": { "address": { "anyOf": [ { "type": "string" } ], "title": "Address", "examples": [ "0x28c6c06298d514db089934071355e5743bf21d60" ], "description": "Holder wallet address" }, "value_usd": { "anyOf": [ { "type": "number" } ], "title": "Value Usd", "examples": [ 50000 ], "description": "USD value of the holder's balance at the historical price for as_of_date" }, "token_amount": { "anyOf": [ { "type": "number" } ], "title": "Token Amount", "examples": [ 1000000 ], "description": "Holder's cumulative token balance at as_of_date" }, "token_symbol": { "anyOf": [ { "type": "string" } ], "title": "Token Symbol", "examples": [ "PEPE" ], "description": "Token symbol resolved at the queried date" }, "total_inflow": { "anyOf": [ { "type": "number" } ], "title": "Total Inflow", "examples": [ 1050000 ], "description": "Cumulative tokens received by the holder up to as_of_date" }, "address_label": { "anyOf": [ { "type": "string" } ], "title": "Address Label", "examples": [ "Whale" ], "description": "Temporally-correct label resolved at as_of_date" }, "total_outflow": { "anyOf": [ { "type": "number" } ], "title": "Total Outflow", "examples": [ 50000 ], "description": "Cumulative tokens sent by the holder up to as_of_date" }, "balance_change_7d": { "anyOf": [ { "type": "number" } ], "title": "Balance Change 7D", "examples": [ 5000 ], "description": "Net token balance change over the 7 days ending at as_of_date" }, "balance_change_24h": { "anyOf": [ { "type": "number" } ], "title": "Balance Change 24H", "examples": [ 1000 ], "description": "Net token balance change on as … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-ai-historical-top-holders-4ce20f7f/health.json - [Zero catalog index](https://www.zero.xyz/llms.txt) - [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)