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"],
  "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

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

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 28, 2026

addedInput schema / properties / request / additionalProperties
```
Added value: +false
```

removedInput schema / properties / request / anyOf

Removed value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "description": "Pass these fields inside the tool's request argument.\n\nFor on-chain holders, specify the token contract and its supported chain.\nNative SOL holders are unavailable; use perps mode for SOL positions.\nFor Hyperliquid positions, use mode='perps' and a symbol such as BTC.\nPerps mode returns positions, not spot token holders.",
-    "properties": {
-      "aggregateByEntity": {
-        "default": false,
-        "description": "Whether to aggregate data by entity instead of individual addresses",
-        "type": "boolean"
-      },
-      "chain": {
-        "default": "ethereum",
-        "description": "Blockchain network. Supported: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync",
-        "type": "string"
-      },
-      "entryPrice": {
-        "anyOf": [
-          {
-            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
-            "properties": {
-              "from": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Minimum value (inclusive), optional"
-              },
-              "to": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Maximum value (inclusive), optional"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Entry price range filter - perps mode only"
-      },
-      "includeSmartMoneyLabels": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "30D Smart Trader",
-                "90D Smart Trader",
-                "180D Smart Trader",
-                "All Time Smart Trader",
-                "Fund",
-                "Smart HL Perps Trader",
-                "Any Smart Money"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "List of smart money labels to filter by (default: empty list). Use 'Any Smart Money' to include all smart money types."
-      },
-      "labelType": {
-        "default": "top_100_holders",
-        "description": "Label type for holder analysis and filtering",
-        "enum": [
-          "whale",
-          "public_figure",
-          "smart_money",
-          "top_100_holders",
-          "exchange"
-        ],
-        "type": "string"
-      },
-      "mode": {
-        "default": "onchain_tokens",
-        "description": "Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.",
-        "enum": [
-          "onchain_tokens",
-          "perps"
-        ],
-        "type": "string"
-      },
-      "orderBy": {
-        "anyOf": [
-          {
-            "enum": [
-              "holding_size",
-              "total_outflow",
-              "total_inflow",
-              "balance_change_24h",
-              "balance_change_7d",
-              "balance_change_30d",
-              "side",
-              "entry_price",
-              "leverage",
-              "liquidation_price",
-              "funding_usd",
-              "upnl_usd"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Sort field. holding_size works in both modes. onchain_tokens only: total_inflow, total_outflow, balance_change_24h, balance_change_7d, balance_change_30d. perps only: side, entry_price, leverage, liquidation_price, funding_usd, upnl_usd. Native tokens with labelType='top_100_holders' support holding_size only; use another labelType for other on-chain sorts. An unsupported combination is not an error: the call falls back to holding_size and the output notes the changed sort."
-      },
-      "order_by_direction": {
-        "default": "DESC",
-        "enum": [
-          "ASC",
-          "DESC",
-          "asc",
-          "desc"
-        ],
-        "type": "string"
-      },
-      "page": {
-        "default": 1,
-        "type": "integer"
-      },
-      "positionValueUsd": {
-        "anyOf": [
-          {
-            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
-            "properties": {
-              "from": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Minimum value (inclusive), optional"
-              },
-              "to": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Maximum value (inclusive), optional"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Position value range filter in USD - perps mode only"
-      },
-      "side": {
-        "anyOf": [
-          {
-            "enum": [
-              "Long",
-              "Short"
-            ],
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Position side filter: Long or Short (case-insensitive). Perps mode only."
-      },
-      "tokenAddress": {
-        "type": "string"
-      },
-      "upnlUsd": {
-        "anyOf": [
-          {
-            "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
-            "properties": {
-              "from": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Minimum value (inclusive), optional"
-              },
-              "to": {
-                "anyOf": [
-                  {
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ],
-                "default": null,
-                "description": "Maximum value (inclusive), optional"
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Unrealized PnL range filter in USD - perps mode only"
-      }
-    },
-    "required": [
-      "tokenAddress"
-    ],
-    "type": "object"
-  }
-]

addedInput schema / properties / request / description

Added value: +"Pass these fields inside the tool's request argument.\n\nFor on-chain holders, specify the token contract and its supported chain.\nNative SOL holders are unavailable; use perps mode for SOL positions.\nFor Hyperliquid positions, use mode='perps' and a symbol such as BTC.\nPerps mode returns positions, not spot token holders."

addedInput schema / properties / request / properties

Added value: +{
+  "aggregateByEntity": {
+    "default": false,
+    "description": "Whether to aggregate data by entity instead of individual addresses",
+    "type": "boolean"
+  },
+  "chain": {
+    "default": "ethereum",
+    "description": "Blockchain network. Supported: arbitrum, arc, avalanche, base, bnb, ethereum, hyperevm, injective, iotaevm, linea, mantle, mantra, monad, near, optimism, plasma, polygon, robinhood, ronin, scroll, sei, solana, sonic, sui, ton, tron, unichain, zksync",
+    "type": "string"
+  },
+  "entryPrice": {
+    "anyOf": [
+      {
+        "additionalProperties": false,
+        "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
+        "properties": {
+          "from": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Minimum value (inclusive), optional"
+          },
+          "to": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Maximum value (inclusive), optional"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Entry price range filter - perps mode only"
+  },
+  "includeSmartMoneyLabels": {
+    "anyOf": [
+      {
+        "items": {
+          "enum": [
+            "30D Smart Trader",
+            "90D Smart Trader",
+            "180D Smart Trader",
+            "All Time Smart Trader",
+            "Fund",
+            "Smart HL Perps Trader",
+            "Any Smart Money"
+          ],
+          "type": "string"
+        },
+        "type": "array"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "List of smart money labels to filter by (default: empty list). Use 'Any Smart Money' to include all smart money types."
+  },
+  "labelType": {
+    "default": "top_100_holders",
+    "description": "Label type for holder analysis and filtering",
+    "enum": [
+      "whale",
+      "public_figure",
+      "smart_money",
+      "top_100_holders",
+      "exchange"
+    ],
+    "type": "string"
+  },
+  "mode": {
+    "default": "onchain_tokens",
+    "description": "Analysis mode: 'onchain_tokens' for on-chain tokens by contract address, 'perps' for Hyperliquid perpetual futures by symbol. If mode is omitted and token_address is a symbol (not a contract address), mode defaults to 'perps'.",
+    "enum": [
+      "onchain_tokens",
+      "perps"
+    ],
+    "type": "string"
+  },
+  "orderBy": {
+    "anyOf": [
+      {
+        "enum": [
+          "holding_size",
+          "total_outflow",
+          "total_inflow",
+          "balance_change_24h",
+          "balance_change_7d",
+          "balance_change_30d",
+          "side",
+          "entry_price",
+          "leverage",
+          "liquidation_price",
+          "funding_usd",
+          "upnl_usd"
+        ],
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Sort field. holding_size works in both modes. onchain_tokens only: total_inflow, total_outflow, balance_change_24h, balance_change_7d, balance_change_30d. perps only: side, entry_price, leverage, liquidation_price, funding_usd, upnl_usd. Native tokens with labelType='top_100_holders' support holding_size only; use another labelType for other on-chain sorts. An unsupported combination is not an error: the call falls back to holding_size and the output notes the changed sort."
+  },
+  "order_by_direction": {
+    "default": "DESC",
+    "enum": [
+      "ASC",
+      "DESC",
+      "asc",
+      "desc"
+    ],
+    "type": "string"
+  },
+  "page": {
+    "default": 1,
+    "type": "integer"
+  },
+  "positionValueUsd": {
+    "anyOf": [
+      {
+        "additionalProperties": false,
+        "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
+        "properties": {
+          "from": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Minimum value (inclusive), optional"
+          },
+          "to": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Maximum value (inclusive), optional"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Position value range filter in USD - perps mode only"
+  },
+  "side": {
+    "anyOf": [
+      {
+        "enum": [
+          "Long",
+          "Short"
+        ],
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Position side filter: Long or Short (case-insensitive). Perps mode only."
+  },
+  "tokenAddress": {
+    "type": "string"
+  },
+  "upnlUsd": {
+    "anyOf": [
+      {
+        "additionalProperties": false,
+        "description": "Numeric range where from_value and to_value are optional,\nallowing for open-ended ranges (e.g., only minimum or only maximum).",
+        "properties": {
+          "from": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Minimum value (inclusive), optional"
+          },
+          "to": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Maximum value (inclusive), optional"
+          }
+        },
+        "type": "object"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "default": null,
+    "description": "Unrealized PnL range filter in USD - perps mode only"
+  }
+}

addedInput schema / properties / request / required
```
Added value: +[
+  "tokenAddress"
+]
```
addedInput schema / properties / request / type
```
Added value: +"object"
```

Changed1 schema field changedOct 23, 2026