{"uid":"cap_W3hjcJSVuU1RkjezPXMPU","slug":"api-nansen-ai-947121b8","name":"Nansen Token God Mode (TGM) Holders","description":"Get \"Token God Mode\" (TGM) holders data","url":"https://api.nansen.ai/api/v1/tgm/holders","method":"GET","headers":{},"bodySchema":{"type":"object","title":"TGMHoldersRequest","required":["chain","token_address"],"properties":{"chain":{"enum":["arbitrum","avalanche","base","bitcoin","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":"TGMHoldersChain","description":"Chains supported for TGM holders endpoint."},"filters":{"anyOf":[{"type":"object","title":"TGMHoldersFilters","properties":{"address":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address","examples":["0x28c6c06298d514db089934071355e5743bf21d60"],"description":"Holder address filter"},"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":"Balance range filter in USD. Defaults to min: 1.0 to exclude dust holders. Set explicitly to override (e.g., {\"min\": 0} to include all holders). Note: This default does not apply to native tokens with 'all_holders' label."},"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"},"total_inflow":{"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":100}],"description":"Total inflow range filter"},"address_label":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Address Label","examples":["Smart Money","%Fund%"],"description":"Holder label filter"},"total_outflow":{"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":100}],"description":"Total outflow range filter"},"balance_change_7d":{"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":5000,"min":-5000}],"description":"7-day balance change range filter"},"balance_change_24h":{"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":-1000}],"description":"24-hour balance change range filter"},"balance_change_30d":{"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":10000,"min":-10000}],"description":"30-day balance change range filter"},"ownership_percentage":{"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":10,"min":0.01}],"description":"Ownership percentage range filter"},"exclude_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"type":"string","title":"LabelType","description":"Filter by entity label type."}}],"title":"Exclude Smart Money Labels","examples":[["Public Figure"],["Exchange"]],"description":"Exclude smart money labels for holders"},"include_smart_money_labels":{"anyOf":[{"type":"array","items":{"enum":["30D Smart Trader","90D Smart Trader","180D Smart Trader","Fund","Smart Trader","Public Figure","Exchange","Whale","BananaGun Bot User","Top Maestro Bot User","Top BananaGun Bot User","Maestro Bot User","Early MAGIC Miner","First Mover LP","First Mover Staking","Profitable LP","Smart HL Perps Trader"],"type":"string","title":"LabelType","description":"Filter by entity label type."}}],"title":"Include Smart Money Labels","examples":[["Public Figure"],["Exchange"]],"description":"Include smart money labels for holders"}},"description":"Filters for TGM holders endpoint.\n\nThese filters control which holders are included in the analysis.","additionalProperties":false}],"examples":[{"value_usd":{"min":10000},"token_amount":{"min":1000},"ownership_percentage":{"min":0.01},"include_smart_money_labels":["30D Smart Trader","Fund"]}],"description":"Additional filters to apply to the query."},"order_by":{"anyOf":[{"type":"array","items":{"type":"object","title":"SortOrder[TGMHoldersSortField]","required":["field","direction"],"properties":{"field":{"enum":["address","name","token_amount","total_outflow","total_inflow","balance_change_24h","balance_change_7d","balance_change_30d","ownership_percentage","value_usd"],"type":"string","title":"TGMHoldersSortField","description":"Enum for sortable fields in TGM holders."},"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\": \"value_usd\", \"direction\": \"DESC\"}] - Sort by value USD descending\n- [{\"field\": \"token_amount\", \"direction\": \"ASC\"}] - Sort by token amount ascending\n- [{\"field\": \"ownership_percentage\", \"direction\": \"DESC\"}] - Sort by ownership percentage descending"},"label_type":{"enum":["whale","public_figure","smart_money","all_holders","exchange"],"type":"string","title":"TGMHoldersLabel","description":"TGM holders label types."},"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"},"premium_labels":{"anyOf":[{"type":"boolean"}],"title":"Premium Labels","description":"Controls label tier in the response. When null/omitted, defaults to true (premium labels filtered by subscription plan). When false, returns free-tier labels for all users. When true, returns premium labels (filtered by subscription plan). Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior."},"aggregate_by_entity":{"type":"boolean","title":"Aggregate By Entity","default":false,"examples":[false],"description":"Whether to return entity data"}},"description":"Request model for TGM holders endpoint.\n\nThis endpoint provides comprehensive data on token holders and their balances.\nRetrieve holders by various criteria including smart money, exchanges, public figures,\nwhales, and top holders with detailed balance information and filtering options.","additionalProperties":false},"responseSchema":{"type":"object","title":"TGMHoldersResponse","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","title":"TGMHolder","properties":{"address":{"anyOf":[{"type":"string"}],"title":"Address","examples":["0x1234567890123456789012345678901234567890"],"description":"Address of contract/EOA"},"value_usd":{"anyOf":[{"type":"number"}],"title":"Value Usd","examples":[50000],"description":"Current token balance value in USD"},"token_amount":{"anyOf":[{"type":"number"}],"title":"Token Amount","examples":[1000000],"description":"Total balance count"},"total_inflow":{"anyOf":[{"type":"number"}],"title":"Total Inflow","examples":[1050000],"description":"Total amount of tokens received by this address"},"address_label":{"anyOf":[{"type":"string"}],"title":"Address Label","examples":["Smart Money"],"description":"Label associated with the address"},"total_outflow":{"anyOf":[{"type":"number"}],"title":"Total Outflow","examples":[50000],"description":"Total amount of tokens sent by this address"},"balance_change_7d":{"anyOf":[{"type":"number"}],"title":"Balance Change 7D","examples":[5000],"description":"Token balance change over the last 7 days"},"balance_change_24h":{"anyOf":[{"type":"number"}],"title":"Balance Change 24H","examples":[1000],"description":"Token balance change over the last 24 hours"},"balance_change_30d":{"anyOf":[{"type":"number"}],"title":"Balance Change 30D","examples":[15000],"description":"Token balance change over the last 30 days"},"ownership_percentage":{"anyOf":[{"type":"number"}],"title":"Ownership Percentage","examples":[2.5],"description":"Percentage of total token supply owned by this address"}},"description":"Individual TGM holder record.\n\nRepresents a single holder with balance information and metadata."},"title":"Data","description":"List of TGM holder records"},"warnings":{"anyOf":[{"type":"array","items":{"type":"string"}}],"title":"Warnings","description":"Optional warnings about the query results. For example, if a token has no USD price data, a warning will indicate that the default value_usd filter may be excluding results."},"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 holders endpoint.\n\nContains a list of holder records with pagination and metadata."},"example":{"request":{"chain":"ethereum","token_address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"},"response":{"data":[{"address":"0x37305b1cd40574e4c5ce33f8e8306be057fd7341","value_usd":4387803369.448287,"token_amount":4389708168.78267,"total_inflow":219872981083.88794,"address_label":"MakerDAO: Lite PSM","total_outflow":215483272915.1053,"balance_change_7d":754832934.469872,"balance_change_24h":18049140.784351,"balance_change_30d":1190901871.038382,"ownership_percentage":0},{"address":"0x38aaef3782910bdd9ea3566c839788af6ff9b200","value_usd":2189072990.985087,"token_amount":2190023294.45702,"total_inflow":18761335867.159138,"address_label":"🤖 🏦 Binance: Wallet","total_outflow":16571312572.702116,"balance_change_7d":-400000000,"balance_change_24h":0,"balance_change_30d":-893157752.583,"ownership_percentage":0},{"address":"0xe1940f578743367f38d3f25c2d2d32d6636929b6","value_usd":1699262328.392209,"token_amount":1699999999.039577,"total_inflow":1700000000.039577,"address_label":"🤖 ZeroDev: SingleOwnerMSCA","total_outflow":1,"balance_change_7d":0,"balance_change_24h":0,"balance_change_30d":0,"ownership_percentage":0},{"address":"0xad354cfbaa4a8572dd6df021514a3931a8329ef5","value_usd":1399392507.0452282,"token_amount":1400000000.5201,"total_inflow":1400000002.0201,"address_label":"🤖 🏦 Binance: Cold Wallet","total_outflow":1.5,"balance_change_7d":0,"balance_change_24h":0,"balance_change_30d":0,"ownership_percentage":0},{"address":"0xffa69c0080582098af595156240214b742735a5e","value_usd":1282443275.4830384,"token_amount":1282999999.8601,"total_inflow":1282999999.989199,"address_label":"🤖 ERC1967Proxy","total_outflow":0.129099,"balance_change_7d":0,"balance_change_24h":0,"balance_change_30d":0,"ownership_percentage":0},{"address":"0x40ec5b33f54e0e8a33a975908c5ba1c14e5bbbdf","value_usd":1081294587.864953,"token_amount":1081763991.126179,"total_inflow":19340235545.069492,"address_label":"🤖 Polygon: PoS ERC20 Bridge","total_outflow":18258471553.943314,"balance_change_7d":13727137.699846,"balance_change_24h":-3647831.143453,"balance_change_30d":-45321826.576399,"ownership_percentage":0},{"address":"0x01b8697695eab322a339c4bf75740db75dc9375e","value_usd":788110089.0823357,"token_amount":788452217.351701,"total_inflow":950000010.351701,"address_label":"​​Custody Vaults","total_outflow":161547793,"balance_change_7d":115000000.000999,"balance_change_24h":115000000.000999,"balance_change_30d":180923262.116389,"ownership_percentage":0},{"address":"0x3d09d2354530466d32ed37c6ad19ea58504a0c37","value_usd":666633531.4862347,"token_amount":666922925.289953,"total_inflow":1221922935.289953,"address_label":"🏦 Deribit: Wallet","total_outflow":555000010,"balance_change_7d":-19999999.95759,"balance_change_24h":0.03661,"balance_change_30d":45433672.949119,"ownership_percentage":0},{"address":"0x08f619716db7c6245401b543e59acac1d25cb483","value_usd":592058196.3518478,"token_amount":592315216.086638,"total_inflow":1129376741.086638,"address_label":"🤖 ERC1967Proxy","total_outflow":537061525,"balance_change_7d":0,"balance_change_24h":0,"balance_change_30d":142504604.79,"ownership_percentage":0},{"address":"0xee7ae85f2fe2239e27d9c1e23fffe168d63b4055","value_usd":579228735.6525908,"token_amount":579480185.960918,"total_inflow":193310035606.78802,"address_label":"🤖 🏦 Binance: Hot Wallet","total_outflow":192730555420.82712,"balance_change_7d":-109615893.449257,"balance_change_24h":-75245989.387486,"balance_change_30d":-133918171.339229,"ownership_percentage":0}],"warnings":null,"pagination":{"page":1,"per_page":10,"is_last_page":false}}},"exampleRequest":{"chain":"ethereum","token_address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"},"tags":["x402"],"displayCostAmount":"0.05","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.05/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.05","per":"call","confidence":"exact"},{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_CdKeA3FrYtQh6_ioVandZ","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_vrwplmdNC2XqWC83V6KBa","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":"Retrieves holders data for a specific token using Nansen's Token God Mode analytics, including wallet labels, smart money flags, and entity aggregations","exampleAgentPrompt":"Using Nansen Token God Mode, show me the top holders of token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 on Ethereum, grouped by entity, and filter to premium-labeled wallets only.","exampleUseCases":null,"resultDescription":"Returns a list of token holders with Nansen wallet labels (e.g. smart money, exchange, fund), optional entity aggregations, balances, label types, and metadata — filtered and sorted according to the query parameters.","failureModes":["Invalid or unsupported token address returns 400 or empty result","Unsupported chain value returns an error","Malformed filters object causes 400 bad request","Missing required token_address parameter causes request failure","Payment failure (402) if x402 payment is not properly attached","Rate limiting or quota exhaustion returns 429"],"whenToPreferThis":"Use this endpoint when you need to identify who holds a specific token with the context of Nansen's proprietary wallet labels (smart money, exchanges, funds, whales). Prefer this over generic on-chain holder lookups when label intelligence, entity aggregation, or smart money classification is needed. Ideal for due diligence, market research, or monitoring institutional accumulation patterns.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:46:27.642Z","isFirstParty":false}