{"uid":"cap_I8r0nouQtQO2Q0efRwZEJ","slug":"nansen-historical-holdings-4b1f8b7c","name":"Nansen Smart Money Historical Holdings","description":"Retrieve historical snapshots of aggregated token balances held by smart traders and funds. This endpoint provides time-series data for trend analysis, backtesting, and performance attribution.\n\nKey Features:\n\n- Daily snapshots of smart money holdings\n- Date range filtering (max 4 years lookback)\n- Point-in-time pricing and market cap data\n- Balance change tracking between snapshots\n- Same filtering options as current holdings endpoint\n\nUse Cases:\n\n- Trend Analysis: Track how smart money rotates between assets over time\n- Performance Attribution: Combine with price data to estimate ROI\n- Backtesting: Validate trading strategies based on historical smart money behavior","url":"https://api.nansen.ai/api/v1/smart-money/historical-holdings?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"SmartMoneyHistoricalHoldingsRequest","required":["date_range","chains"],"properties":{"chains":{"type":"array","items":{"enum":["arc","base","bnb","ethereum","monad","robinhood","solana"],"type":"string","title":"SmartMoneyHistoricalHoldingsChain","description":"Chains supported for smart money historical holdings endpoint."},"title":"Chains","examples":[["ethereum"],["base"],["bnb"],["monad"],["robinhood"],["arc"],["solana"]],"description":"Chains to include in the analysis. Supports ethereum, base, bnb, monad, robinhood, arc, 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":"SmartMoneyHistoricalHoldingsSortOrder","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":["arc","base","bnb","ethereum","monad","robinhood","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":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.01","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.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"}]},"paymentMethods":[{"uid":"pm_rSIgPzs29evg6IisRji9t","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Retrieve time-series daily snapshots of aggregated token balances held by smart traders and funds across multiple blockchains.","exampleAgentPrompt":"Pull Nansen's historical smart money holdings snapshots for Ethereum and Solana from January 1 2024 to December 31 2024, filtered to tokens with at least $10,000 USD value held, so I can see how smart traders rotated between assets over the year.","exampleUseCases":null,"resultDescription":"An array of daily snapshot records, each containing the date, chain, token address, token symbol, token sectors, smart money labels present, number of smart money holders, token balance, USD value held, market cap at snapshot date, token age in days, share of smart money total holdings, and balance percent changes between snapshots — plus pagination metadata.","failureModes":["Invalid or unsupported chain returns validation error","Date range exceeding 4-year lookback returns 400 error","Missing required fields (chains or date_range) returns 422 validation error","No data found for the specified filters returns empty data array","Authentication failure or missing API key returns 401 unauthorized","Rate limit exceeded returns 429 too many requests"],"whenToPreferThis":"Use this endpoint when you need historical time-series data on smart money token holdings — for backtesting trading strategies, analyzing trend rotations, or performing performance attribution. Prefer this over current holdings when temporal context and snapshot history are needed rather than a single point-in-time view.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:40:48.192Z","isFirstParty":false,"canonicalSlug":"api-nansen-ai-64f4d732"}