{"uid":"cap_PrhK-KEPYV7uZdoxggf6j","slug":"nansen-ai-smart-money-historical-token-balances-13300bd1","name":"Nansen AI - Smart Money Historical Token Balances","description":"**Beta — subject to breaking changes.**\n\nPoint-in-time smart money token balance aggregates for a given date.\n\nReturns SM token holdings per (chain, token_address) pair filtered by SM labels,\ntoken type, and chain. Includes 24h balance change, holder counts, share of total\nSM holdings, and historical market cap.","url":"https://api.nansen.ai/api/v1beta1/smart-money/historical-token-balances","method":"GET","headers":{},"bodySchema":{"type":"object","title":"SmartMoneyHistoricalTokenBalancesRequest","required":["as_of_date"],"properties":{"chains":{"type":"array","items":{"enum":["all","arbitrum","avalanche","base","bnb","ethereum","hyperevm","iotaevm","linea","mantle","monad","optimism","plasma","polygon","ronin","scroll","sei","solana","sonic"],"type":"string","title":"SmartMoneyChain","description":"Chains supported in smart money analysis."},"title":"Chains","default":[],"examples":[["ethereum","base"]],"description":"Chains to include. Empty list returns all chains."},"filters":{"anyOf":[{"type":"object","title":"SmartMoneyHistoricalTokenBalancesFilters","properties":{"sm_filter":{"type":"array","items":{"enum":["Fund","Smart Trader","30D Smart Trader","90D Smart Trader","180D Smart Trader","Smart Dex Trader","30D Smart Dex Trader","90D Smart Dex Trader","180D Smart Dex Trader","Smart HL Perps Trader"],"type":"string","title":"HistoricalSmartMoneyFilterType","description":"Filter by smart money label type. Includes legacy label classes (e.g. Smart Dex Trader) that appear in historical data."},"title":"Sm Filter","default":[],"examples":[["Fund","Smart Trader"]],"description":"SM label filter. Empty list includes all SM labels."},"include_stablecoins":{"type":"boolean","title":"Include Stablecoins","default":true,"description":"Whether to include stablecoin tokens"},"include_native_tokens":{"type":"boolean","title":"Include Native Tokens","default":true,"description":"Whether to include native tokens and LSTs/LRTs"}},"description":"Filters for the historical SM token balances endpoint.","additionalProperties":false}],"description":"Optional filters for SM labels and token types"},"as_of_date":{"type":"string","title":"As Of Date","format":"date","examples":["2025-01-15"],"description":"Date to query balances for"},"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."},"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 SM token balances endpoint.\n\nReturns smart money token balance aggregates for a given date, filtered by\nchain, SM label, and token type.","additionalProperties":false},"responseSchema":{"type":"object","title":"SmartMoneyHistoricalTokenBalancesResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"SmartMoneyHistoricalTokenBalance","required":["chain","token_address","token_symbol"],"properties":{"chain":{"type":"string","title":"Chain","examples":["ethereum"],"description":"Blockchain chain"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","examples":[1500000],"description":"Total SM balance in USD"},"token_symbol":{"type":"string","title":"Token Symbol","examples":["PEPE"],"description":"Token symbol"},"holders_count":{"anyOf":[{"type":"integer"}],"title":"Holders Count","examples":[42],"description":"Number of SM holders with balance > $100"},"token_address":{"type":"string","title":"Token Address","examples":["0x6982508145454ce325ddbe47a25d4ec3d2311933"],"description":"Token contract address"},"token_sectors":{"type":"array","items":{"type":"string"},"title":"Token Sectors","examples":[["DeFi","DEX"]],"description":"Token sector classifications"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","examples":[50000000],"description":"Historical market cap on as_of_date (falls back to FDV)"},"token_age_days":{"anyOf":[{"type":"integer"}],"title":"Token Age Days","examples":[365],"description":"Days since token deployment as of as_of_date"},"share_of_holdings_percent":{"anyOf":[{"type":"number"}],"title":"Share Of Holdings Percent","examples":[0.003],"description":"This token's share of total SM holdings"},"balance_24h_percent_change":{"anyOf":[{"type":"number"}],"title":"Balance 24H Percent Change","examples":[0.05],"description":"24-hour percentage change in token balance amount"}},"description":"Single SM token balance record for a given date."},"title":"Data","description":"List of SM token balance 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 SM token balances 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_nR2Kubv_1nPtzxX9tjDRk","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":"Retrieves historical token balance data for smart money addresses tracked by Nansen's 500M+ labeled address dataset","exampleAgentPrompt":"Show me the historical token balances for Ethereum address 0xabc123 over the past 90 days — I want to see how their holdings in USDC and ETH changed over time using Nansen's smart money data.","exampleUseCases":null,"resultDescription":"Returns time-series snapshots of token balances held by the queried address, including token amounts, asset identifiers, and timestamps — sourced from Nansen's dataset of 500M+ labeled smart money addresses.","failureModes":["Invalid or unrecognized wallet address returns 400 error","Address not found in Nansen's labeled dataset returns empty results","Unsupported chain or token returns 404 or empty response","Date range too large may result in timeout or partial data","Missing required query parameters returns 422 validation error","Rate limiting or insufficient payment returns 402 or 429 error"],"whenToPreferThis":"Use this endpoint when you need on-chain historical token balance data specifically filtered through or attributed to Nansen's smart money address labels. Ideal for understanding how sophisticated or institutional wallets have changed their holdings over time, rather than just current positions. Prefer this over generic blockchain explorers when smart money context and label enrichment matter.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T06:40:27.246Z","isFirstParty":false}