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.