{"uid":"cap_MDHFlTJirZlQUQawOWw6c","slug":"nansen-ai-token-screener-historical-5213ad27","name":"Nansen AI Token Screener Historical","description":"**Beta — subject to breaking changes.**\n\nHistorical token screener data anchored to `to_date` over a `timeframe_days` window.\n\nOutput columns match the production token screener API response shape exactly.\n\nWhen `trader_type='sm'` (or the deprecated `only_smart_money=True`),\nvolume/netflow/nof_traders fields reflect smart money flows only.\n`sm_label_filter` is applied only in SM mode. `trader_type` overrides\n`only_smart_money` when both are set; only `all` and `sm` are supported.\n\nUse `exclude_sectors` to drop tokens whose sector tags include any of the\nlisted sectors (e.g. `[\"Stablecoin\"]`).","url":"https://api.nansen.ai/api/v1beta1/token-screener/historical","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TokenScreenerHistoricalRequest","required":["to_date","timeframe_days","chains"],"properties":{"chains":{"type":"array","items":{"enum":["arbitrum","avalanche","base","bitcoin","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":"TokenScreenerChain","description":"Chains supported for Token Screener endpoint."},"title":"Chains","examples":[["ethereum"]],"minItems":1,"description":"Chains to include (required, must be non-empty)"},"filters":{"anyOf":[{"type":"object","title":"TokenScreenerHistoricalFilters","properties":{"fdv_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":[{"min":1000000}],"description":"FDV range filter in USD"},"nof_buys":{"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":[{"min":10}],"description":"Number of buy transactions range filter"},"nof_sells":{"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":[{"min":10}],"description":"Number of sell transactions range filter"},"nof_buyers":{"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":[{"min":5}],"description":"Number of buyers range filter"},"volume_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":"Total volume range filter in USD"},"netflow_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":-100000}],"description":"Netflow range filter in USD (can be negative)"},"nof_sellers":{"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":[{"min":5}],"description":"Number of sellers range filter"},"nof_traders":{"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":[{"min":10}],"description":"Number of traders range filter"},"fdv_mc_ratio":{"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":5,"min":1}],"description":"FDV/MC ratio range filter"},"liquidity_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":[{"min":100000}],"description":"On-chain liquidity range filter in USD"},"buy_volume_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":[{"min":1000}],"description":"Buy volume range filter in USD"},"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":[{"min":1000000}],"description":"Market cap range filter in USD"},"token_age_days":{"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":365,"min":30}],"description":"Token age range filter in days"},"sell_volume_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":[{"min":1000}],"description":"Sell volume range filter in USD"},"sm_label_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 Label Filter","default":[],"examples":[["Smart Trader"]],"description":"Filter by SM label (only applied when only_smart_money=True). Empty list includes all SM labels."},"inflow_fdv_ratio":{"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":[{"min":0.01}],"description":"Inflow/FDV ratio range filter"},"outflow_fdv_ratio":{"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":[{"min":0.01}],"description":"Outflow/FDV ratio range filter"}},"description":"Filters for the historical token screener endpoint.\n\nWhen only_smart_money=True, sm_label_filter restricts results to specific SM label types.","additionalProperties":false}],"description":"Optional filters applied server-side"},"to_date":{"type":"string","title":"To Date","format":"date","examples":["2025-06-01"],"description":"End date of the screener window"},"order_by":{"type":"array","items":{"type":"object","title":"SortOrder[TokenScreenerHistoricalSortField]","required":["field","direction"],"properties":{"field":{"enum":["volume","buy_volume","sell_volume","netflow","price_change","market_cap_usd","fdv","liquidity","price_usd","nof_traders","nof_buyers","nof_sellers","nof_buys","nof_sells","token_age_days"],"type":"string","title":"TokenScreenerHistoricalSortField","description":"Sortable fields for the historical token screener endpoint.\n\nValues match the view's order_by parameter."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}},"title":"Order By","description":"Sort order. Defaults to netflow DESC. Only the first element is used."},"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."},"trader_type":{"anyOf":[{"enum":["all","sm","whale","public_figure"],"type":"string","title":"TraderType","description":"Trader type filter for token screener."}],"examples":["sm"],"description":"Filter by trader type. Overrides only_smart_money when provided. Only `all` and `sm` are supported on the historical surface."},"sectors_filter":{"type":"array","items":{"type":"string"},"title":"Sectors Filter","examples":[["DeFi"]],"description":"Sector filter. Empty list includes all sectors."},"timeframe_days":{"type":"integer","title":"Timeframe Days","maximum":365,"minimum":1,"examples":[7],"description":"Number of days in the screener window"},"exclude_sectors":{"type":"array","items":{"type":"string"},"title":"Exclude Sectors","examples":[["Stablecoin"]],"description":"Sectors to exclude. Empty list excludes nothing."},"only_smart_money":{"type":"boolean","title":"Only Smart Money","default":false,"deprecated":true,"description":"Deprecated: use trader_type instead. When True, aggregate smart money flows only. Volume/netflow/nof_traders fields reflect SM flows. Ignored when trader_type is provided."},"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 token screener endpoint.\n\nReturns token screener data anchored to to_date over a timeframe_days window.\nOutput columns match the production token screener API response shape exactly.\n\nWhen only_smart_money=True, volume/netflow/nof_traders fields reflect SM flows only.\nsm_label_filter is only applied when only_smart_money=True.","additionalProperties":false},"responseSchema":{"type":"object","title":"TokenScreenerHistoricalResponse","required":["pagination","data"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TokenScreenerHistoricalItem","required":["token_address","token_symbol","chain"],"properties":{"fdv":{"anyOf":[{"type":"number"}],"title":"Fdv","examples":[1500000000],"description":"Fully diluted valuation in USD"},"chain":{"type":"string","title":"Chain","examples":["ethereum"],"description":"Blockchain chain"},"volume":{"anyOf":[{"type":"number"}],"title":"Volume","examples":[50000000],"description":"Total DEX volume (buy + sell) in USD over the timeframe"},"netflow":{"anyOf":[{"type":"number"}],"title":"Netflow","examples":[6000000],"description":"Net flow (buy - sell) in USD over the timeframe"},"sectors":{"type":"array","items":{"type":"string"},"title":"Sectors","examples":[["DeFi","Lending"]],"description":"Token sector classifications"},"liquidity":{"anyOf":[{"type":"number"}],"title":"Liquidity","examples":[8000000],"description":"Total on-chain liquidity in USD at to_date"},"price_usd":{"anyOf":[{"type":"number"}],"title":"Price Usd","examples":[85.5],"description":"Token price in USD at to_date"},"buy_volume":{"anyOf":[{"type":"number"}],"title":"Buy Volume","examples":[28000000],"description":"Buy volume in USD over the timeframe"},"sell_volume":{"anyOf":[{"type":"number"}],"title":"Sell Volume","examples":[22000000],"description":"Sell volume in USD over the timeframe"},"fdv_mc_ratio":{"anyOf":[{"type":"number"}],"title":"Fdv Mc Ratio","examples":[1.25],"description":"FDV / market cap ratio"},"price_change":{"anyOf":[{"type":"number"}],"title":"Price Change","examples":[0.12],"description":"Price change over the timeframe as a ratio"},"token_symbol":{"type":"string","title":"Token Symbol","examples":["AAVE"],"description":"Token symbol"},"token_address":{"type":"string","title":"Token Address","examples":["0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9"],"description":"Token contract address"},"market_cap_usd":{"anyOf":[{"type":"number"}],"title":"Market Cap Usd","examples":[1200000000],"description":"Market cap in USD (falls back to FDV if zero)"},"token_age_days":{"anyOf":[{"type":"integer"}],"title":"Token Age Days","examples":[1460],"description":"Days since token deployment as of to_date"},"inflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Inflow Fdv Ratio","examples":[0.019],"description":"Buy volume / FDV ratio"},"outflow_fdv_ratio":{"anyOf":[{"type":"number"}],"title":"Outflow Fdv Ratio","examples":[0.015],"description":"Sell volume / FDV ratio"}},"description":"Single token screener record for a historical date window."},"title":"Data","description":"List of token screener 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 token screener endpoint."},"example":null,"exampleRequest":null,"tags":["x402","finance"],"displayCostAmount":"0.05","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.05/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_9eW059WCPFl5iZ5xcMHND","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns historical token screener data filtered by chain, timeframe, trader type, and smart money flows for a given date window","exampleAgentPrompt":"Using Nansen's token screener, show me which tokens had the highest smart money netflow on Ethereum over the last 14 days ending today, excluding blacklisted addresses and filtering to smart money traders only.","exampleUseCases":null,"resultDescription":"A ranked list of tokens with historical smart money flow metrics, netflow figures, and associated metadata for the specified chains and date window, paginated and sorted by netflow descending by default.","failureModes":["Empty or missing 'chains' array returns a 400 validation error","Invalid 'to_date' format causes a parsing error","Unsupported chain identifier returns an empty result or error","Conflicting trader_type and only_smart_money fields may produce unexpected filtering","Overly broad queries with no filters may time out or return large paginated datasets","Payment not fulfilled returns 402 Payment Required"],"whenToPreferThis":"Use this endpoint when you need historical (not real-time) token screener data filtered by smart money or labeled wallet activity across one or more blockchains. Prefer this over real-time endpoints when analyzing past windows or backtesting token selection based on Nansen's 500M+ labeled address intelligence.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T20:13:43.244Z","isFirstParty":false}