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_usd, nof_trades, still_holding_balance_ratio,
netflow_amount_usd
**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"},
"order_by": "pnlUsdTotal",
"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},
"order_by": "roiPercentTotal",
"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 **
Connector