Finding top token holders
token_current_top_holdersGet 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 addressperps: 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" }
# Fund holders (general labels; Fund is not a Smart Money label)
```
{
"mode": "onchain_tokens",
"chain": "ethereum",
"token_address": "0xa0b86a33e6b6c4b3add000b44b3a1234567890ab",
"label_type": "top_100_holders",
"includeLabels": ["Fund"]
}
```
# 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"],
"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.Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"request": "<request>"
},
"name": "token_current_top_holders"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | Pass these fields inside the tool's request argument. For on-chain holders, specify the token contract and its supported chain. Native SOL holders are unavailable; use perps mode for SOL positions. For Hyperliquid positions, use mode='perps' and a symbol such as BTC. Perps mode returns positions, not spot token holders. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |