# Nansen Historical Token Flow Summary > Nansen Historical Token Flow Summary is a paid API for AI agents from api.nansen.ai, paid per call via x402, $0.05/call, status unknown (last checked 2026-10-13). Returns temporally-correct, segment-labeled token flow intelligence (whale, public figure, top PnL, smart trader, exchange) for a specified token over an explicit date range, resolving segment labels as of the end date to avoid forward-looking bias. ## Facts - Endpoint: GET https://api.nansen.ai/api/v1beta1/tgm/historical-token-flow-summary?utm_source=zero.xyz - Price: $0.05/call - Payment: x402 - Status: unknown - Last checked: 2026-10-13 - Activations on Zero: 0 - Tags: x402 - Canonical page: https://www.zero.xyz/c/nansen-historical-token-flow-summary-d8a95b61 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_jzA7G7_MjXhsdcRZZcqrR 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-historical-token-flow-summary-d8a95b61 ``` Example prompt: Pull the historical token flow summary for PEPE (0x6982508145454ce325ddbe47a25d4ec3d2311933) on Ethereum from January 1 2025 to January 31 2025 — I want to see how whales, top PnL traders, and exchanges were moving in and out during that period. ## When to prefer this Choose this endpoint over /tgm/flow-intelligence when you need historical, backtest-safe flow analysis for a specific date range. It is ideal when segment labels must reflect who held a label at the end date (not today), making it the correct choice for historical research, backtesting strategies, and as-of-date analysis. Use /tgm/flow-intelligence instead for real-time rolling window queries. ## Known failure modes - Missing required fields (chain, token_address, date_range) returns 422 validation error - Invalid chain enum value returns 422 - Invalid date format returns 422 - Token address not found on specified chain returns empty data array - Segment label columns (whale, public_figure, top_pnl) are NULL when date_to is before 2025-03-11 coverage start - Smart trader data only available from 2020+, returns NULL before that - Unauthorized or invalid API key returns 401 - Rate limit exceeded returns 429 ## How this service works Get historical "Token God Mode" (TGM) token flow summary (Beta) ## Output An array of records containing per-segment flow intelligence: token symbol, plus net flow (USD), average flow (USD), and wallet count for whale, top PnL, smart trader, public figure, and exchange segments — all segment labels resolved at the specified end date to prevent forward-looking bias. Segment columns are NULL when temporal label history does not yet cover the end date. ## Request schema (JSON Schema) ```json { "type": "object", "title": "TGMHistoricalTokenFlowSummaryRequest", "required": [ "chain", "token_address", "date_range" ], "properties": { "chain": { "enum": [ "arbitrum", "avalanche", "base", "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": "TGMChain", "description": "Chains supported in TGM (Token God Mode) endpoints." }, "date_range": { "type": "object", "title": "DateRange", "properties": { "to": { "anyOf": [ { "type": "string" } ], "title": "To", "examples": [ "2025-01-31T23:59:59Z" ], "description": "End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)" }, "from": { "anyOf": [ { "type": "string" } ], "title": "From", "examples": [ "2025-01-01T00:00:00Z" ], "description": "Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)" } }, "description": "Date range model matching the API schema." }, "token_address": { "type": "string", "title": "Token Address", "examples": [ "0x6982508145454ce325ddbe47a25d4ec3d2311933" ], "description": "Token contract address" }, "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 flow summary endpoint.\n\nReturns the same per-segment flow intelligence shape as\n`/tgm/flow-intelligence` but resolved against temporal label history so\nsegment classification reflects who held a label _at_ `date_to` rather\nthan today. Use this for backtests and as-of-date analysis.", "additionalProperties": false } ``` ## Response schema (JSON Schema) ```json { "type": "object", "title": "TGMHistoricalTokenFlowSummaryResponse", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "title": "TGMHistoricalTokenFlowSummary", "properties": { "token_symbol": { "anyOf": [ { "type": "string" } ], "title": "Token Symbol", "examples": [ "PEPE" ], "description": "Symbol of the queried token, resolved from on-chain metadata." }, "whale_avg_flow_usd": { "anyOf": [ { "type": "number" } ], "title": "Whale Avg Flow Usd", "examples": [ 250000.75 ], "description": "Geometric mean of absolute flow for Whale addresses." }, "whale_net_flow_usd": { "anyOf": [ { "type": "number" } ], "title": "Whale Net Flow Usd", "examples": [ 5000000.25 ], "description": "Net flow (USD) for addresses labeled as Whale at date_to." }, "whale_wallet_count": { "anyOf": [ { "type": "integer" } ], "title": "Whale Wallet Count", "examples": [ 25 ], "description": "Unique wallet count for Whale addresses in the period." }, "top_pnl_avg_flow_usd": { "anyOf": [ { "type": "number" } ], "title": "Top Pnl Avg Flow Usd", "examples": [ 100000.5 ], "description": "Geometric mean of absolute flow for Top PnL addresses." }, "top_pnl_net_flow_usd": { "anyOf": [ { "type": "number" } ], "title": "Top Pnl Net Flow Usd", "examples": [ 2000000.75 ], "description": "Net flow (USD) for addresses labeled as Top PnL at date_to." }, "top_pnl_wallet_count": { "anyOf": [ { "type": "integer" } ], "title": "Top Pnl Wallet Count", "examples": [ 15 ], "description": "Unique wallet count for Top PnL addresses in the period." }, "exchange_avg_flow_usd": { "anyOf": [ { "type": "number" } ], "title": "Exchange Avg Flow Usd", "examples": [ 150000.5 ], "description": "Geometric mean of absolute exchange flow sizes." }, "exchange_net_flow_usd": { "anyOf": [ { "type": "number" } ], "title" … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-historical-token-flow-summary-d8a95b61/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)