{"uid":"cap_KFd2dyBdsGzqbQJZFH-iB","slug":"nansen-holders-4212946e","name":"Nansen Token Holders (TGM)","description":"Retrieve the top token holders with their current balances, historical activity, and recent balance changes. Provides insights into token distribution, smart money and fund holdings.\n\n**Performance Optimization for Native Tokens:**\nWhen querying native tokens with `label_type: \"all_holders\"`, this endpoint uses an optimized model to prevent timeouts. This optimization has the following limitations:\n- **Ordering**: Only `token_amount` field is supported\n- **Filters**: Limited to: `token_amount`, `total_outflow`, `total_inflow`, `address`, `include_smart_money_labels`, `exclude_smart_money_labels`\n\nTo use advanced filters and ordering on native tokens, specify a `label_type` other than \"all_holders\" (e.g., \"smart_money\", \"whale\", \"exchange\").\n\n**Label Tier Control (`premium_labels`):**\nWhen omitted or set to `false` (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing `premium_labels=true` returns premium labels (Smart Money, Fund, and other advanced labels), is billed at **150 credits per call**, and requires a paid plan.","url":"https://api.nansen.ai/api/v1/tgm/holders?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"TGMHoldersRequest","required":["chain","token_address"],"properties":{"chain":{"enum":["arbitrum","arc","avalanche","base","bitcoin","bnb","ethereum","hyperevm","injective","iotaevm","linea","mantle","mantra","monad","near","optimism","plasma","polygon","robinhood","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":"TGMHoldersSortOrder","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 or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan."},"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":null,"exampleRequest":null,"tags":["blockchain","smart-money","wallet","tokens","defi","analytics","profiler","dex","pnl","onchain","prediction-market","data"],"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":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"}]},"paymentMethods":[{"uid":"pm_GZdTdtQ-7fiV01AEVplsS","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":"Nansen","brandSlug":"nansen","brandBaseUrl":"https://nansen.ai","brandDocsUrl":"https://docs.nansen.ai","whatItDoes":"Retrieves top token holders with balances, historical activity, balance changes, and smart money labels for any token across 26+ chains.","exampleAgentPrompt":"Show me the top smart money and whale holders of the USDC token on Ethereum, filtering for wallets holding at least $10,000 worth, and include their 7-day balance changes.","exampleUseCases":null,"resultDescription":"Returns a paginated list of token holder records, each containing the holder's address, current token balance, USD value, ownership percentage of total supply, total inflow/outflow, 24h/7d/30d balance changes, and address label (e.g. 'Smart Money', 'Exchange', 'Whale'). Also includes optional warnings about query result quality.","failureModes":["Invalid chain enum value — returns 422 validation error","Token address not found on specified chain — returns empty data array","Timeout when querying native tokens with all_holders label and unsupported filters — mitigated by using optimized model","Unsupported filter fields when using all_holders label type on native tokens — returns error or warning","Pagination out of range — returns empty data array","Missing required fields (chain or token_address) — returns 422 validation error"],"whenToPreferThis":"Use this endpoint when you need ranked token holder data with smart money labels, balance change history, and ownership percentages across major blockchains. Prefer over generic on-chain queries when you need Nansen's proprietary smart money and whale labeling. Best for token distribution analysis, whale watching, and tracking institutional/fund accumulation or distribution patterns.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-09T18:46:20.430Z","isFirstParty":false,"canonicalSlug":"nansen-holders-4212946e"}