{"uid":"cap_F8o3Ns2nelfEn14NVjBtL","slug":"api-nansen-ai-54b62832","name":"Nansen Token God Mode (TGM) Flows","description":"Get \"Token God Mode\" (TGM) flows data","url":"https://api.nansen.ai/api/v1/tgm/flows","method":"GET","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","avalanche","base","bnb","ethereum","hyperevm","hyperliquid","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","ronin","scroll","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":"SortOrder[TGMFlowsSortField]","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":"Block date of the flow data point"},"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"},"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"},"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":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_skKOjnvL6Ds_2oIVe70BM","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves Token God Mode (TGM) flow intelligence data showing token movement and transfer activity tracked by Nansen's smart money analytics","exampleAgentPrompt":"Pull the Token God Mode flows data from Nansen for ETH on Ethereum mainnet over the last 24 hours so I can see what smart money is doing with it.","exampleUseCases":null,"resultDescription":"Returns Token God Mode (TGM) flow data including token transfer volumes, inflow/outflow metrics, and smart money movement intelligence for the queried token(s) and time range.","failureModes":["Invalid or unsupported token address returns an error or empty result","Unsupported chain identifier causes a 400 bad request","Exceeding rate limits or insufficient USDC payment triggers a 402 payment required error","Time range outside available data history returns empty or partial results","Malformed request body causes a 422 validation error"],"whenToPreferThis":"Use this endpoint when you need granular token-level flow data (inflows, outflows, transfer volumes) from Nansen's Token God Mode product, especially to track smart money activity around a specific token. Prefer over generic on-chain data sources when Nansen's wallet labeling and smart money classification is important.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T20:13:43.237Z","isFirstParty":false}