# Nansen AI - Smart Money Historical Token Balances > Nansen AI - Smart Money Historical Token Balances is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.25/call, status unknown (last checked 2026-09-14). Retrieves historical token balance data for smart money addresses tracked by Nansen's 500M+ labeled address dataset ## Facts - Endpoint: GET https://api.nansen.ai/api/v1beta1/smart-money/historical-token-balances - Price: $0.25/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-smart-money-historical-token-balances-13300bd1 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_PrhK-KEPYV7uZdoxggf6j 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-smart-money-historical-token-balances-13300bd1 ``` Example prompt: 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. ## When to prefer this 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. ## Known failure modes - 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 ## How this service works **Beta — subject to breaking changes.** Point-in-time smart money token balance aggregates for a given date. Returns SM token holdings per (chain, token_address) pair filtered by SM labels, token type, and chain. Includes 24h balance change, holder counts, share of total SM holdings, and historical market cap. ## Output 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. ## Request schema (JSON Schema) ```json { "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" … (truncated) ``` ## Response schema (JSON Schema) ```json { "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": " … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-ai-smart-money-historical-token-balances-13300bd1/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)