{"uid":"cap_jzA7G7_MjXhsdcRZZcqrR","slug":"nansen-historical-token-flow-summary-d8a95b61","name":"Nansen Historical Token Flow Summary","description":"Get historical \"Token God Mode\" (TGM) token flow summary (Beta)","url":"https://api.nansen.ai/api/v1beta1/tgm/historical-token-flow-summary?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"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},"responseSchema":{"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":"Exchange Net Flow Usd","examples":[3000000.75],"description":"Net exchange flow in USD (direction inverted: deposit-to-exchange is positive). Combines CEX transfers and DEX trades."},"exchange_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Exchange Wallet Count","examples":[0],"description":"Always 0 (matching production flow-intelligence — exchange wallet count is not tracked)."},"smart_trader_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Avg Flow Usd","examples":[75000.25],"description":"Geometric mean of absolute flow for Smart Trader addresses."},"smart_trader_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Smart Trader Net Flow Usd","examples":[1500000.5],"description":"Net flow (USD) for addresses labeled as Smart Trader at date_to. Available from 2020+; before 2025-03-11 covers DEX trades only."},"smart_trader_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Smart Trader Wallet Count","examples":[20],"description":"Unique wallet count for Smart Trader addresses in the period."},"fresh_wallets_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Fresh Wallets Avg Flow Usd","examples":[25000.75],"description":"7-day daily-average fresh-wallet inflow (USD) from the snapshot."},"fresh_wallets_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Fresh Wallets Net Flow Usd","examples":[500000.25],"description":"24h fresh-wallet inflow (USD) from the most recent snapshot taken on or before date_to."},"fresh_wallets_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Fresh Wallets Wallet Count","examples":[0],"description":"Always 0 (matching production — fresh wallet count is not tracked separately)."},"public_figure_avg_flow_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Avg Flow Usd","examples":[50000.25],"description":"Geometric mean of absolute flow for Public Figure addresses."},"public_figure_net_flow_usd":{"anyOf":[{"type":"number"}],"title":"Public Figure Net Flow Usd","examples":[1000000.5],"description":"Net flow (USD) for addresses labeled as Public Figure at date_to."},"public_figure_wallet_count":{"anyOf":[{"type":"integer"}],"title":"Public Figure Wallet Count","examples":[10],"description":"Unique wallet count for Public Figure addresses in the period."}},"description":"Single historical token flow summary record.\n\nOutput schema mirrors `/tgm/flow-intelligence` (TGMFlowIntelligence) plus\na `token_symbol` convenience column. All segment columns are Nullable —\nNULL means the segment's temporal label data is not available for the\nqueried `date_to` (e.g. before 2025-03-11 for whale/public_figure/top_pnl/\nexchange), distinct from a zero net flow."},"title":"Data","description":"List of historical token flow summary records. The underlying view returns a single aggregated row per (token_address, date_to)."},"warnings":{"anyOf":[{"type":"array","items":{"type":"string"}}],"title":"Warnings","description":"Optional warnings about the query results, e.g. when segment fields are NULL because temporal label data does not yet cover the requested date_to."}},"description":"Response for the historical token flow summary endpoint."},"example":null,"exampleRequest":null,"tags":["x402"],"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":{"p10Cents":"5.0000","medianCents":"5.0000","p90Cents":"5.0000","minCents":"5.0000","maxCents":"5.0000","p95Cents":"5.0000","sampleCount":1,"varies":false,"failureChargeRate":1},"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_UxSZ96FJAHwOXFAZH6LSA","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 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.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-13T06:55:39.274Z","isFirstParty":false,"canonicalSlug":"nansen-historical-token-flow-summary-d8a95b61"}