# Nansen AI Token Screener Historical > Nansen AI Token Screener Historical is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-14). Returns historical token screener data filtered by chain, timeframe, trader type, and smart money flows for a given date window ## Facts - Endpoint: GET https://api.nansen.ai/api/v1beta1/token-screener/historical - Price: $0.05/call - Payment: x402 - Status: unknown - Last checked: 2026-09-14 - Activations on Zero: 0 - Tags: x402, finance - Canonical page: https://www.zero.xyz/c/nansen-ai-token-screener-historical-5213ad27 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_MDHFlTJirZlQUQawOWw6c Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently. ## How to call it through Zero Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`): ```sh zero fetch --capability nansen-ai-token-screener-historical-5213ad27 ``` Example prompt: 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. ## When to prefer this 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. ## Known failure modes - 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 ## How this service works **Beta — subject to breaking changes.** Historical token screener data anchored to `to_date` over a `timeframe_days` window. Output columns match the production token screener API response shape exactly. When `trader_type='sm'` (or the deprecated `only_smart_money=True`), volume/netflow/nof_traders fields reflect smart money flows only. `sm_label_filter` is applied only in SM mode. `trader_type` overrides `only_smart_money` when both are set; only `all` and `sm` are supported. Use `exclude_sectors` to drop tokens whose sector tags include any of the listed sectors (e.g. `["Stablecoin"]`). ## Output 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. ## Request schema (JSON Schema) ```json { "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 ], … (truncated) ``` ## Response schema (JSON Schema) ```json { "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", … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-ai-token-screener-historical-5213ad27/health.json - [Zero catalog index](https://www.zero.xyz/llms.txt) - [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)