{"uid":"cap_74XBrB2V6iY1Py0dR8E63","slug":"nansen-flows-db50c4b7","name":"Nansen TGM Flows","description":"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.\n\n`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.\n\n**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`).","url":"https://api.nansen.ai/api/v1/tgm/flows?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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 for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75"}],"examples":[{"max":1000,"min":0.01}],"description":"Price range filter in USD"},"value_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":10000}],"description":"Value range filter in USD"},"token_amount":{"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":1000}],"description":"Token amount range filter"},"holders_count":{"anyOf":[{"type":"object","title":"IntegerRangeFilter","properties":{"max":{"anyOf":[{"type":"integer"}],"title":"Max","examples":[100,1000,10000],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"integer"}],"title":"Min","examples":[10,100,1000],"description":"Minimum value (inclusive)"}},"description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"}],"examples":[{"min":100}],"description":"Holders count range filter"},"total_inflows_count":{"anyOf":[{"type":"object","title":"IntegerRangeFilter","properties":{"max":{"anyOf":[{"type":"integer"}],"title":"Max","examples":[100,1000,10000],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"integer"}],"title":"Min","examples":[10,100,1000],"description":"Minimum value (inclusive)"}},"description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"}],"examples":[{"min":10}],"description":"Total inflows count range filter"},"total_outflows_count":{"anyOf":[{"type":"object","title":"IntegerRangeFilter","properties":{"max":{"anyOf":[{"type":"integer"}],"title":"Max","examples":[100,1000,10000],"description":"Maximum value (inclusive)"},"min":{"anyOf":[{"type":"integer"}],"title":"Min","examples":[10,100,1000],"description":"Minimum value (inclusive)"}},"description":"Filter for integer values with optional min/max bounds.\nUse for counts, numbers of items, and other whole number values. - Values between 5 and 100"}],"examples":[{"min":10}],"description":"Total outflows count range filter"}},"description":"Filters for TGM flows endpoint.\n\nThese filters control which data points are included in the flows analysis.","additionalProperties":false}],"examples":[{"price_usd":{"max":1000,"min":0.01},"value_usd":{"min":10000}}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"TGMFlowsSortOrder","required":["field","direction"],"properties":{"field":{"enum":["date","price_usd","token_amount","value_usd","holders_count","total_inflows_count","total_outflows_count","total_inflows_dex","total_outflows_dex","total_inflows_cex","total_outflows_cex"],"type":"string","title":"TGMFlowsSortField","description":"Enum for sortable fields in TGM flows."},"direction":{"enum":["ASC","DESC"],"type":"string","title":"SortDirection","description":"Enum for sort directions."}}}}],"title":"Order By","description":"Custom sort order to override the endpoint's default ordering.\n\nExamples:\n- [{\"field\": \"date\", \"direction\": \"DESC\"}] - Sort by date descending (most recent first)\n- [{\"field\": \"total_inflows_usd\", \"direction\": \"ASC\"}] - Sort by total inflows ascending\n- [{\"field\": \"total_outflows_usd\", \"direction\": \"DESC\"}] - Sort by total outflows descending"},"pagination":{"type":"object","title":"PaginationRequest","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Page number (1-based)"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page (max 1000)"}},"description":"Pagination parameters for API requests."},"token_address":{"type":"string","title":"Token Address","examples":["2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv"],"description":"Token address"}},"description":"Request model for TGM flows endpoint.\n\nThis endpoint provides comprehensive token flow analytics showing inflow and outflow patterns\nfrom various holder segments including Exchanges, Smart Money addresses, Public Figures, and Whales\nwith time-based statistics and trends.","additionalProperties":false},"responseSchema":{"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":[{"type":"number"}],"title":"Total Outflows Dex","description":"Total DEX outflows (token amount). Only populated when label=exchange, null otherwise."},"total_inflows_count":{"anyOf":[{"type":"number"}],"title":"Total Inflows Count","description":"Total inflows"},"total_outflows_count":{"anyOf":[{"type":"number"}],"title":"Total Outflows Count","description":"Total outflows"}},"description":"Individual TGM flow record.\n\nRepresents a single flow record with token holder statistics."},"title":"Data","description":"List of TGM flow records"},"warnings":{"anyOf":[{"type":"array","items":{"type":"string"}}],"title":"Warnings","description":"Optional warnings about the query results. For example, when the DEX/CEX flow fields are null because a non-exchange label was requested."},"pagination":{"type":"object","title":"PaginationInfo","properties":{"page":{"type":"integer","title":"Page","default":1,"minimum":1,"description":"Current page number"},"per_page":{"type":"integer","title":"Per Page","default":10,"maximum":1000,"minimum":1,"description":"Number of records per page"},"is_last_page":{"type":"boolean","title":"Is Last Page","default":true,"description":"Whether this is the last page"}},"description":"Pagination information for API responses."}},"description":"Response model for TGM flows endpoint.\n\nContains a list of flow records with pagination and metadata."},"example":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"displayCostAmount":"0.01","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":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.01","per":"call","confidence":"exact"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_HS7j2lBV0AfRYn_W8fdvp","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_z21dHVrefdMySpbna7lOC","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Returns hourly snapshots of token balances, inflows, and outflows for specific holder categories (smart money, whales, public figures, exchanges) over a given time range.","exampleAgentPrompt":"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.","exampleUseCases":null,"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-10T18:42:50.326Z","isFirstParty":false,"canonicalSlug":"nansen-flows-db50c4b7"}