Nansen

Finding top token holders

token_current_top_holders

Read-only

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`request`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes