# Nansen TGM Flows > Nansen TGM Flows is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP or x402, $0.01/call, status unknown (last checked 2026-10-10). Returns hourly snapshots of token balances, inflows, and outflows for specific holder categories (smart money, whales, public figures, exchanges) over a given time range. ## Facts - Endpoint: POST https://api.nansen.ai/api/v1/tgm/flows?utm_source=zero.xyz - Price: $0.01/call - Payment: MPP, x402 - Status: unknown - Last checked: 2026-10-10 - Activations on Zero: 0 - Provider: Nansen - Docs: https://docs.nansen.ai - Website: https://nansen.ai - Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data - Canonical page: https://www.zero.xyz/c/nansen-flows-db50c4b7 - Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_74XBrB2V6iY1Py0dR8E63 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-flows-db50c4b7 -d '' ``` Example prompt: Show me the smart money inflows and outflows for the USDC token on Ethereum from January 1 to January 31 2025 — I want to see if smart money was accumulating or distributing. ## When to prefer this Use this endpoint when you need time-series analysis of token flows segmented by holder type (smart money, whales, public figures, exchanges). Ideal for understanding whether sophisticated investors are accumulating or distributing a token over time, or for comparing CEX vs DEX flow dynamics. Choose this over single-point holder snapshots when trend analysis over a date range is needed. ## Known failure modes - Missing required fields (chain, token_address, date) returns 400 validation error - Unsupported chain value returns enum validation error - Invalid date format returns parsing error - Token address not found on specified chain returns empty data array - Date range too wide may return paginated results requiring multiple calls - Filters with impossible ranges (min > max) may return empty results ## How this service works Analyze aggregated token flows by holder category over time. Shows hourly snapshots for ranges of seven days or less and daily snapshots for longer ranges. `date` and `bucket_end` are RFC 3339 UTC timestamps for the inclusive start and exclusive end of each aggregation bucket. The request `date.to` value is an inclusive cutoff. `is_complete` is `false` when that upper cutoff truncates a bucket or the bucket is still live. On Hyperliquid it is also `false` when `date.from` truncates the first bucket; on other chains the lower cutoff is aligned to the bucket start, so the full first bucket is returned. This flag describes request-window coverage, not whether the underlying data is final or will never be revised. Consumers should omit or visibly mark incomplete buckets in normal historical views. **Note:** the DEX/CEX breakdown fields (`total_inflows_dex`, `total_outflows_dex`, `total_inflows_cex`, `total_outflows_cex`) are only populated when `label=exchange` and are `null` for all other labels; a `warnings` entry is included in the response in that case. For net flow per holder segment (e.g. smart money), use the Flow Intelligence endpoint (`POST /api/v1/tgm/flow-intelligence`). ## Output An array of hourly TGM flow records for the requested token and holder category, each containing the date, token amount held, USD value, number of holders, total inflow/outflow counts, and (when label=exchange) CEX and DEX inflow/outflow breakdowns. Also includes pagination info. ## Request schema (JSON Schema) ```json { "type": "object", "title": "TGMFlowsRequest", "required": [ "chain", "token_address", "date" ], "properties": { "date": { "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." }, "chain": { "enum": [ "arbitrum", "arc", "avalanche", "base", "bnb", "ethereum", "hyperevm", "hyperliquid", "injective", "iotaevm", "linea", "mantle", "mantra", "monad", "near", "optimism", "plasma", "polygon", "robinhood", "sei", "solana", "sonic", "starknet", "sui", "ton", "tron" ], "type": "string", "title": "TGMFlowsChain", "description": "Chains supported for the TGM flows endpoint." }, "label": { "enum": [ "whale", "public_figure", "smart_money", "top_100_holders", "exchange" ], "type": "string", "title": "TGMFlowsLabel", "description": "TGM flow label types." }, "filters": { "anyOf": [ { "type": "object", "title": "TGMFlowsFilters", "properties": { "price_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 f … (truncated) ``` ## Response schema (JSON Schema) ```json { "type": "object", "title": "TGMFlowsResponse", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "title": "TGMFlows", "required": [ "date" ], "properties": { "date": { "type": "string", "title": "Date", "description": "Inclusive bucket start as an RFC 3339 UTC timestamp." }, "price_usd": { "anyOf": [ { "type": "number" } ], "title": "Price Usd", "description": "Daily median token price in USD. For the current day, uses the latest spot price." }, "value_usd": { "anyOf": [ { "type": "number" } ], "title": "Value Usd", "description": "Total token value in USD" }, "bucket_end": { "anyOf": [ { "type": "string" } ], "title": "Bucket End", "description": "Exclusive bucket end as an RFC 3339 UTC timestamp." }, "is_complete": { "anyOf": [ { "type": "boolean" } ], "title": "Is Complete", "description": "Whether the returned data covers the entire bucket under the endpoint's per-chain cutoff behavior. This describes request-window coverage, not whether the data is final." }, "token_amount": { "anyOf": [ { "type": "number" } ], "title": "Token Amount", "description": "Total token amount" }, "holders_count": { "anyOf": [ { "type": "integer" } ], "title": "Holders Count", "description": "Number of token holders" }, "total_inflows_cex": { "anyOf": [ { "type": "number" } ], "title": "Total Inflows Cex", "description": "Total CEX inflows (token amount). Only populated when label=exchange, null otherwise." }, "total_inflows_dex": { "anyOf": [ { "type": "number" } ], "title": "Total Inflows Dex", "description": "Total DEX inflows (token amount). Only populated when label=exchange, null otherwise." }, "total_outflows_cex": { "anyOf": [ { "type": "number" } ], "title": "Total Outflows Cex", "description": "Total CEX outflows (token amount). Only populated when label=exchange, null otherwise." }, "total_outflows_dex": { "anyOf": [ { … (truncated) ``` ## More - Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-flows-db50c4b7/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)