{"uid":"cap_WI0JaX6z6uZ1EQrPRrUF9","slug":"nansen-ai-historical-top-holders-4ce20f7f","name":"Nansen AI Historical Top Holders","description":"**Beta — subject to breaking changes.**\n\nTop token holders at a historical `as_of_date` with temporally-correct labels.\nLabels are resolved from label history tables to avoid forward-looking bias.\n\n**Key differences from `/tgm/holders`:**\n- Accepts an explicit `as_of_date` (Date) instead of returning current state\n- Labels resolved at `as_of_date`, not from current-state dictionaries\n- `value_usd` priced at the historical median price for `as_of_date`\n- The `filters.include_sm_labels` field only sub-restricts the `smart_money` bucket;\n  to switch buckets use the top-level `label_type` field\n- No dust-filter default — set filters at the caller side if needed\n\n**Performance:** Can be slow for high-volume tokens (USDC, native ETH, etc.).","url":"https://api.nansen.ai/api/v1beta1/tgm/historical-top-holders","method":"GET","headers":{},"bodySchema":{"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","title":"SortOrder[TGMHistoricalTopHoldersSortField]","required":["field","direction"],"properties":{"field":{"enum":["token_amount","value_usd","total_outflow","total_inflow","balance_change_24h","balance_change_7d","balance_change_30d","ownership_percentage"],"type":"string","title":"TGMHistoricalTopHoldersSortField","description":"Sortable fields for the historical top holders endpoint."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Sort order. Defaults to token_amount DESC. Only the first element is used."},"as_of_date":{"type":"string","title":"As Of Date","examples":["2025-06-15"],"description":"Historical date (YYYY-MM-DD) to compute holder balances at."},"label_type":{"enum":["all_holders","whale","public_figure","exchange","smart_money"],"type":"string","title":"TGMHistoricalTopHoldersLabel","description":"Holder label-type filter for the historical top holders endpoint."},"pagination":{"type":"object","title":"PaginationRequest","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Page number (1-based)"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page (max 1000)"}},"description":"Pagination parameters for API requests."},"token_address":{"type":"string","title":"Token Address","examples":["0x6982508145454ce325ddbe47a25d4ec3d2311933"],"description":"Token contract address"},"apply_blacklist_filter":{"type":"boolean","title":"Apply Blacklist Filter","default":true,"examples":[true],"description":"When True, exclude blacklisted addresses from the results. Defaults to True."}},"description":"Request model for the historical top holders endpoint.\n\nReturns the top holders of a token at a historical `as_of_date` with\ntemporally-correct labels resolved from label history tables to avoid\nforward-looking bias.\n\nCan be slow for high-volume tokens (e.g. USDC, ETH).","additionalProperties":false},"responseSchema":{"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_of_date"},"balance_change_30d":{"anyOf":[{"type":"number"}],"title":"Balance Change 30D","examples":[15000],"description":"Net token balance change over the 30 days ending at as_of_date"},"ownership_percentage":{"anyOf":[{"type":"number"}],"title":"Ownership Percentage","examples":[0.025],"description":"Fraction of total supply held by this address (0-1)"}},"description":"Single historical top-holder record.\n\nBalances and labels are resolved at `as_of_date` using label history tables\nto avoid forward-looking bias. Mirrors the `/tgm/holders` response where\nthey overlap, and adds `token_symbol`."},"title":"Data","description":"List of historical top-holder records"},"pagination":{"type":"object","title":"PaginationInfo","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Current page number"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page"},"is_last_page":{"type":"boolean","title":"Is Last Page","default":true,"description":"Whether this is the last page"}},"description":"Pagination information for API responses."}},"description":"Response model for the historical top holders endpoint."},"example":null,"exampleRequest":null,"tags":["x402","finance"],"displayCostAmount":"0.25","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.25/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.25","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.25","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_zYB4ZfG87VOfnOofu3vid","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.25","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the top token holders for a specific token contract at a historical date, with optional label-type filtering and blacklist exclusion.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-16T12:32:55.258Z","isFirstParty":false}