token_pnl_leaderboard

io.github.nansen-ai/nansen-mcp · Verify this server

Upto 25 results (per page) of trader PnL for a token. Use the sorting and filtering options to narrow down the results. **Modes:** - `onchain_tokens` (default): Analyze on-chain tokens by contract address - `perps`: Analyze Hyperliquid perpetual futures by symbol (chain auto-set to "hyperliquid") — supports native tokens **NOTE:** This tool does not support native tokens (so11111111111111111111111111111111111111112, 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee) in `onchain_tokens` mode. Native tokens (by symbol - SOL, ETH, ARB etc) ARE fully supported in `perps` mode. Returns: Trader performance rankings as markdown. Returns empty string if no trading data found. Columns returned: - **Address**: Trader's wallet address - **Label**: Nansen label of the trader - **Total PnL**: Combined realized and unrealized PnL (currency formatted, can be negative) - **Total ROI**: Total return on investment as percentage (percentage formatted) - **Realized PnL**: Profit/loss from completed trades (currency formatted, can be negative) - **Realized ROI**: Return on investment from realized trades only (percentage formatted) - **Unrealized PnL**: Current profit/loss on open positions (currency formatted, can be negative) - **Unrealized ROI**: Return on investment from unrealized positions only (percentage formatted) - **Token Holdings**: Current token quantity held (numeric formatted) - **Holdings USD**: Current USD value of token holdings (currency formatted) - **Token Price**: Current price per token (price formatted) - **Peak Token Holdings**: Maximum token quantity ever held in the date range (numeric formatted) - **Peak Holdings USD**: Maximum USD value ever held in the date range (currency formatted) - **Still Holding %**: Percentage of peak holdings still held (percentage formatted) - **Total Trades**: Number of trades executed by this address - **Net Flow**: Net money flow - negative means net seller (currency formatted, can be negative) **Sorting** Options You can **ONLY** sort by pnl_usd_total, roi_percent_total, pnl_usd_realised, roi_percent_realised, pnl_usd_unrealised, roi_percent_unrealised, holding_amount, max_balance_held, nof_trades, still_holding_balance_ratio, netflow_amount **Filtering** Options: 📋 List filters: trader_address, trader_address_label 📊 Numeric range filters: pnl_usd_realised, pnl_usd_unrealised, holding_amount, holding_usd, nof_trades, still_holding_balance_ratio, max_balance_held, max_balance_held_usd Examples: # On-chain tokens (default mode) ``` { "mode": "onchain_tokens", "chain": "ethereum", "tokenAddress": "0xa0b86a33e6ba3e5b9e4b1b1b1b1b1b1b1b1b1b1b", "dateRange": {"from": "30D_AGO", "to": "NOW"}, "orderBy": "pnl_usd_total", "order_by_direction": "desc" } ``` # Hyperliquid perpetual futures ``` { "mode": "perps", "tokenAddress": "ETH", "dateRange": {"from": "7D_AGO", "to": "NOW"} } ``` # Advanced filtering: Find profitable active traders with significant holdings ``` { "chain": "ethereum", "tokenAddress": "0xa0b86a33e6ba3e5b9e4b1b1b1b1b1b1b1b1b1b1b", "dateRange": {"from": "30D_AGO", "to": "NOW"}, "pnlUsdTotal": {"from": 1000, "to": 999999999}, "nofTrades": {"from": 5, "to": 100}, "holdingUsd": {"from": 10000, "to": 999999999}, "stillHoldingBalanceRatio": {"from": 0.1, "to": 1.0}, "orderBy": "roi_percent_total", "order_by_direction": "desc" } ``` Notes: - Ranked by total PnL performance by default - Useful for identifying successful traders and copying strategies - Both ascending and descending sorts provide valuable insights (winners vs losers) - ONLY RETURNS TOP 25 RESULTS for the sort order. Hence the result is NEVER complete. - Make sure the sort order is relevant to your analysis as otherwise you will miss data. ** This tool does not support hyperevm as chain **