{"uid":"cap_8ZKFnkdc5zPiubX5siLNi","slug":"api-nansen-ai-64f4d732","name":"Nansen Smart Money Historical Holdings","description":"Get Smart Money Historical Holdings Data","url":"https://api.nansen.ai/api/v1/smart-money/historical-holdings","method":"GET","headers":{},"bodySchema":{"type":"object","title":"SmartMoneyHistoricalHoldingsRequest","required":["date_range","chains"],"properties":{"chains":{"type":"array","items":{"enum":["base","bnb","ethereum","monad","solana"],"type":"string","title":"SmartMoneyHistoricalHoldingsChain","description":"Chains supported for smart money historical holdings endpoint."},"title":"Chains","examples":[["ethereum"],["base"],["bnb"],["monad"],["solana"]],"description":"Chains to include in the analysis. Supports ethereum, base, bnb, monad, and solana."},"filters":{"anyOf":[{"type":"object","title":"SmartMoneyHistoricalHoldingsFilters","properties":{"balance":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":10000,"min":100}],"description":"Token balance range filter in human-readable units"},"value_usd":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":100000,"min":1000}],"description":"Value range filter in USD"},"token_symbol":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Token Symbol","examples":["USDC"],"description":"Token symbol filter"},"holders_count":{"anyOf":[{"type":"object","title":"IntegerRangeFilter","properties":{"max":{"anyOf":[{"type":"integer"}],"title":"Max","examples":[100,1000,10000],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"integer"}],"title":"Min","examples":[10,100,1000],"description":"Minimum value (inclusive)"}},"description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"}],"examples":[{"max":1000,"min":10}],"description":"Number of holders range filter"},"token_address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Token Address","examples":["0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"],"description":"Token address filter"},"market_cap_usd":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":10000000,"min":1000000}],"description":"Market cap range filter in USD"},"token_age_days":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":365,"min":1}],"description":"Token age range filter in days"},"include_stablecoins":{"anyOf":[{"type":"boolean"}],"title":"Include Stablecoins","default":false,"description":"Whether to include stablecoins in the results"},"include_native_tokens":{"anyOf":[{"type":"boolean"}],"title":"Include Native Tokens","default":false,"description":"Whether to include native tokens (e.g., ETH, SOL) in the results"},"share_of_holdings_percent":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":0.1,"min":0.01}],"description":"Share of holdings percentage range filter"},"balance_24h_percent_change":{"anyOf":[{"type":"object","title":"NumericRangeFilter","properties":{"max":{"anyOf":[{"type":"number"}],"title":"Max","examples":[50000,10000000,100],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"number"}],"title":"Min","examples":[1000,1000000,-50,0],"description":"Minimum value (inclusive)"}},"description":"Filter for numeric values (floats) with optional min/max bounds.\nUse for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":0.5,"min":-0.5}],"description":"24-hour balance change percentage range filter"},"exclude_smart_money_labels":{"anyOf":[{"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":"Exclude Smart Money Labels","examples":[["30D Smart Trader"]],"description":"Smart money category filters"},"include_smart_money_labels":{"anyOf":[{"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":"Include Smart Money Labels","examples":[["Fund","Smart Trader"]],"description":"Smart money category filters"}},"description":"Filters for smart money historical holdings endpoint.","additionalProperties":false}],"examples":[{"value_usd":{"max":100000,"min":1000},"token_age_days":{"max":30},"include_stablecoins":false,"include_native_tokens":false,"balance_24h_percent_change":{"max":0.1,"min":-0.1},"exclude_smart_money_labels":["30D Smart Trader"],"include_smart_money_labels":["Fund","Smart Trader"]}],"description":"Additional filters to apply"},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[SmartMoneyHistoricalHoldingsSortField]","required":["field","direction"],"properties":{"field":{"enum":["date","chain","token_address","token_symbol","balance","value_usd","balance_24h_percent_change","holders_count","share_of_holdings_percent","token_age_days","market_cap_usd"],"type":"string","title":"SmartMoneyHistoricalHoldingsSortField","description":"Enum for sortable fields in smart money historical holdings."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Custom sort order. Defaults to sorting by date DESC, value_usd DESC, token_address ASC, chain ASC for stable pagination."},"date_range":{"type":"object","title":"DateOnlyRange","properties":{"to":{"anyOf":[{"type":"string"}],"title":"To","examples":["2025-01-31"],"description":"End date in YYYY-MM-DD format"},"from":{"anyOf":[{"type":"string"}],"title":"From","examples":["2025-01-01"],"description":"Start date in YYYY-MM-DD format"}},"description":"Date range model that only accepts YYYY-MM-DD format (no time components)."},"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."}},"description":"Request model for smart money historical holdings endpoint.","additionalProperties":false},"responseSchema":{"type":"object","title":"SmartMoneyHistoricalHoldingsResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"SmartMoneyHistoricalHolding","required":["date","chain","token_address","token_symbol","token_sectors","smart_money_labels","holders_count","token_age_days"],"properties":{"date":{"type":"string","title":"Date","description":"Snapshot date (YYYY-MM-DD)"},"chain":{"enum":["base","bnb","ethereum","monad","solana"],"type":"string","title":"SmartMoneyHistoricalHoldingsChain","description":"Chains supported for smart money historical holdings endpoint."},"balance":{"anyOf":[{"type":"number"}],"title":"Balance","description":"Token balance in human-readable units (accounting for decimals)"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","description":"Value of token held by Smart Money at snapshot date"},"token_symbol":{"type":"string","title":"Token Symbol","description":"Token symbol"},"holders_count":{"type":"integer","title":"Holders Count","description":"Number of Smart Money holders of token at snapshot date"},"token_address":{"type":"string","title":"Token Address","description":"Address of token"},"token_sectors":{"type":"array","items":{"type":"string"},"title":"Token Sectors","description":"Token sectors"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","description":"Market cap of token at snapshot date"},"token_age_days":{"type":"integer","title":"Token Age Days","description":"Number of days since token was deployed, relative to snapshot date"},"smart_money_labels":{"type":"array","items":{"type":"string"},"title":"Smart Money Labels","description":"Array of unique smart money labels present in the aggregated holdings for this token"},"share_of_holdings_percent":{"anyOf":[{"type":"number"}],"title":"Share Of Holdings Percent","description":"Share of Smart Money total USD balance at snapshot date"},"balance_24h_percent_change":{"anyOf":[{"type":"number"}],"title":"Balance 24H Percent Change","description":"Balance change of Smart Money for token during the 24 hours prior to snapshot"}},"description":"Individual smart money historical holding record."},"title":"Data","description":"List of smart money historical holding 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 smart money historical holdings endpoint."},"example":{"request":{"chains":["ethereum"],"order_by":[{"field":"value_usd","direction":"DESC"}],"date_range":{"to":"2024-01-31","from":"2024-01-01"},"pagination":{"page":1,"per_page":10}},"response":{"data":[{"date":"2024-01-02","chain":"ethereum","balance":183280123.94,"value_usd":673571835.4728858,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":169,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.1478695987494078,"balance_24h_percent_change":0.02196861268223353},{"date":"2024-01-01","chain":"ethereum","balance":183280123.94,"value_usd":659092487.8847755,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":168,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.14793428384972554,"balance_24h_percent_change":0},{"date":"2024-01-03","chain":"ethereum","balance":183280123.94,"value_usd":656995815.3286018,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":170,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.146786186231934,"balance_24h_percent_change":-0.024609134870739804},{"date":"2024-01-04","chain":"ethereum","balance":183280123.94,"value_usd":574160522.6692232,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":171,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.13406407952655613,"balance_24h_percent_change":-0.12608191822035866},{"date":"2024-01-05","chain":"ethereum","balance":183280123.94,"value_usd":558480863.5896502,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":172,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.13339618966376093,"balance_24h_percent_change":-0.027308842145189017},{"date":"2024-01-12","chain":"ethereum","balance":183280123.94,"value_usd":524292245.30713516,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":179,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.11689083428415994,"balance_24h_percent_change":0.037541525770371745},{"date":"2024-01-13","chain":"ethereum","balance":183280123.94,"value_usd":520424917.8370193,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":180,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.11923431862671766,"balance_24h_percent_change":-0.00737628203493707},{"date":"2024-01-14","chain":"ethereum","balance":183280123.94,"value_usd":518295127.6395783,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":181,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.11867400506167555,"balance_24h_percent_change":-0.004092406271192466},{"date":"2024-01-06","chain":"ethereum","balance":183280123.94,"value_usd":512477603.1968178,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":173,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.12446261992940812,"balance_24h_percent_change":-0.08237213375073445},{"date":"2024-01-16","chain":"ethereum","balance":183280123.94,"value_usd":507459455.8807649,"token_symbol":"WLD","holders_count":25,"token_address":"0x163f8c2467924be0ae7b5347228cabf260318753","token_sectors":[],"market_cap_usd":null,"token_age_days":183,"smart_money_labels":["Fund"],"share_of_holdings_percent":0.11564372253486317,"balance_24h_percent_change":0.003887863187883524}],"pagination":{"page":1,"per_page":10,"is_last_page":false}}},"exampleRequest":{"chains":["ethereum"],"order_by":[{"field":"value_usd","direction":"DESC"}],"date_range":{"to":"2024-01-31","from":"2024-01-01"},"pagination":{"page":1,"per_page":10}},"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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.01/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_a49cQ0HXp3HSbsZvbJGX8","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_xI1L_A_7MInilmScLb56u","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves historical token holdings data for smart money wallets tracked by Nansen","exampleAgentPrompt":"Pull Nansen's smart money historical holdings for the wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 over the past 90 days so I can see which tokens those smart money wallets were holding before the recent market move.","exampleUseCases":null,"resultDescription":"Returns a historical record of token holdings for the specified smart money wallet(s) or entity, including token identifiers, quantities held, timestamps, and portfolio composition snapshots over the requested time period.","failureModes":["Invalid or unrecognized wallet address returns an error or empty result","Entity name not found in Nansen's label database","Time range out of bounds or too large returns a 400 or truncated response","Missing required body parameters causes a 422 validation error","Rate limiting or insufficient credits returns a 402 or 429 error","Unsupported blockchain or token address format causes a lookup failure"],"whenToPreferThis":"Use this endpoint when you need to analyze what tokens smart money wallets held at specific points in the past, particularly to identify patterns before major price movements or to audit the historical composition of labeled whale/smart money portfolios. Prefer this over current-holdings endpoints when temporal context or trend analysis is required.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T18:43:26.152Z","isFirstParty":false}