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
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"
}
```
**Restrictions exclusively when querying for native tokens (ETH, BNB, etc.):**
- Only supports sorting by `orderBy='holding_size'` (others will fail)
- With `label_type='top_100_holders'`: limited filters (holding_size, total_outflow, total_inflow, address, smart money labels)
- For advanced filters, use different`label_type` or set `aggregate_by_entity=true`
**orderBy Restrictions (use 'holding_size' to avoid API errors):**
- Token address: 0xa0b86a33e6b6c4b3add000b44b3a1234567890ab
**Does not** work for SOL in onchain_tokens mode (tokenAddress So11111111111111111111111111111111111111112). For SOL analysis, use perps mode instead.