token_current_top_holders

io.github.nansen-ai/nansen-mcp · Verify this server

Get upto 25 (per page) top holders information for a specific token. **Note:** Using `labelType: smart_money` is not a good proxy for an overall market view. Use it only if user explicitly requests it, or to combine it with other non smart money data. **Modes:** - `onchain_tokens` (default): Analyze on-chain tokens by contract address - `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid") Columns returned (onchain_tokens mode): - **Address**: Wallet/contract address of the token holder - **Label**: Nansen label (e.g., exchange, whale, etc.) - **Balance**: Current balance held (numeric with K/M/B formatting) - **Balance USD**: USD value of token holdings (currency formatted) - **Ownership %**: Percentage of total token supply owned (percentage, 2 decimal places) - **Sent**: Total tokens sent from this address historically (numeric) - **Received**: Total tokens received by this address historically (numeric) - **24h Change**: Balance change in last 24 hours (numeric, can be negative) - **7d Change**: Balance change in last 7 days (numeric, can be negative) - **30d Change**: Balance change in last 30 days (numeric, can be negative) Columns returned (perps mode): - **Trader Address**: Address of the trader - **Trader Label**: Nansen label for the trader - **Side**: Position direction (Long/Short) - **Position Value USD**: Total USD value of the position (currency formatted) - **Position Size**: Size of the position in tokens (numeric) - **Leverage**: Leverage multiplier (e.g., "20X") - **Leverage Type**: Type of leverage (cross/isolated) - **Entry Price**: Average entry price (price formatted) - **Mark Price**: Current mark price (price formatted) - **Liquidation Price**: Liquidation price (price formatted) - **Funding USD**: Cumulative funding payments (currency formatted) - **Unrealized PnL USD**: Unrealized profit/loss (currency formatted) Sorting Options (default: holding_size desc): onchain_tokens mode: holding_size, total_outflow, total_inflow, balance_change_24h, balance_change_7d, balance_change_30d perps mode: holding_size, side, entry_price, leverage, liquidation_price, funding_usd, upnl_usd Use only a value listed for the selected mode. A value from the wrong mode is not an error: the call falls back to holding_size and the output notes the changed sort. Examples: # On-chain tokens (default mode) ``` { "mode": "onchain_tokens", "chain": "ethereum", "token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab", "label_type": "top_100_holders" } ``` # Hyperliquid perpetual futures ``` { "mode": "perps", "token_address": "PENGU", "label_type": "smart_money" } ``` # Find most active senders using filters ``` { "mode": "onchain_tokens", "chain": "ethereum", "token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab", "label_type": "smart_money", "includeSmartMoneyLabels": ["All Time Smart Trader", "Fund"], "orderBy": "total_outflow", "order_by_direction": "desc" } ``` # Find biggest accumulators (who received most tokens) ``` { "mode": "onchain_tokens", "chain": "ethereum", "token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab", "label_type": "whale", "orderBy": "total_inflow", "order_by_direction": "desc" } ``` # Perps mode with filters ``` { "mode": "perps", "token_address": "ETH", "label_type": "smart_money", "side": "Long", "upnlUsd": {"from": 10000}, "positionValueUsd": {"from": 100000}, "orderBy": "holding_size", "order_by_direction": "desc" } ``` **Native-token / stablecoin `orderBy` restriction:** With `labelType='top_100_holders'` (the default), native tokens (`0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` and native SUI) and stablecoins/pegged tokens support `orderBy='holding_size'` only. To sort such a token by another onchain field, use `labelType='whale'`, `smart_money`, `exchange` or `public_figure` instead. An unsupported combination is not an error: the call falls back to `holding_size` and the output notes the changed sort. **Other `top_100_holders` limits for native tokens:** limited filters (holding_size, total_outflow, total_inflow, address, smart money labels). For advanced filters use a different `labelType` or set `aggregateByEntity=true`. **Does not** work for SOL in onchain_tokens mode (tokenAddress So11111111111111111111111111111111111111112). For SOL analysis, use perps mode instead.