Rank perpetual traders by realized and unrealized PnL for a specific Hyperliquid perp contract.
What it does
This endpoint ranks traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. It returns both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages, position values, netflow amounts, and trading patterns. The data covers Hyperliquid perpetual contracts exclusively.
The endpoint accepts a token symbol (e.g., "BTC", "ETH", "SOL"), a date range, optional filters (trader address, PnL ranges, smart money labels, position values, number of trades), and pagination parameters. Results can be sorted by realized PnL, unrealized PnL, total PnL, ROI metrics, holding amounts, position value, and more. Premium labels (smart money classifications) are available as an optional parameter.
Pricing is $0.05 per call via the x402 protocol, or 50 credits (free tier) / 5 credits (pro tier) when using API key authentication. Rate limits apply per-second and per-minute as indicated in response headers.
Capabilities
Use cases
- —Identify the most profitable perpetual traders for a given token over a date range
- —Analyze smart money positioning and performance on Hyperliquid perp contracts
- —Build copy-trading signals based on top-performing perp traders
- —Research which traders have the highest ROI on specific perpetual markets
- —Filter for traders with large unrealized gains to detect conviction positions
Fit
Best for
- —Quantitative researchers analyzing Hyperliquid perp trader performance
- —Trading bots that need to identify top-performing perp traders programmatically
- —Portfolio managers tracking smart money perpetual positions
- —Agents building derivatives intelligence dashboards
Not for
- —Spot/DEX token PnL analysis (use /api/v1/tgm/pnl-leaderboard instead)
- —Real-time trade execution or order placement
- —Historical price data retrieval (use token-ohlcv endpoint)
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard \
-H 'Content-Type: application/json' \
-H 'apiKey: YOUR_API_KEY' \
-d '{
"token_symbol": "BTC",
"date": {"from": "2025-01-01T00:00:00Z", "to": "2025-01-31T23:59:59Z"},
"pagination": {"page": 1, "per_page": 10}
}'Example
Request
{
"date": {
"to": "2025-01-31T23:59:59Z",
"from": "2025-01-01T00:00:00Z"
},
"filters": {
"pnl_usd_realised": {
"min": 1000
},
"position_value_usd": {
"min": 5000
}
},
"order_by": [
{
"field": "pnl_usd_total",
"direction": "DESC"
}
],
"pagination": {
"page": 1,
"per_page": 10
},
"token_symbol": "BTC"
}Response
{
"data": [
{
"price_usd": 97500,
"nof_trades": 42,
"pnl_usd_total": 140000.75,
"holding_amount": 2.5,
"netflow_amount": -1,
"trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
"max_balance_held": 5,
"pnl_usd_realised": 125000.5,
"roi_percent_total": 0.35,
"netflow_amount_usd": -100000,
"pnl_usd_unrealised": 15000.25,
"position_value_usd": 243750,
"max_balance_held_usd": 487500,
"roi_percent_realised": 0.31,
"trader_address_label": "Smart HL Perps Trader [0x28c6c0]",
"roi_percent_unrealised": 0.04,
"still_holding_balance_ratio": 0.5
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed request/response models, clear pricing ($0.05 via x402), endpoint confirmed live via 402 MPP challenge. Docs are comprehensive from the OpenAPI spec. Minor deduction because no standalone documentation page was crawlable and response schema references aren't fully expanded inline.
Warnings
- —No standalone documentation page found at api.nansen.ai/docs — schema is inferred entirely from OpenAPI spec
- —Premium labels parameter behavior may change in future releases (default switching from true to false)
Citations
- —Endpoint costs $0.05 per call via x402 protocol, or 50 credits (free) / 5 credits (pro)https://api.nansen.ai
- —Covers Hyperliquid perpetual contracts only, no chain field neededhttps://api.nansen.ai
- —Returns realized PnL, unrealized PnL, ROI percentages, position values, and trading patternshttps://api.nansen.ai
- —Endpoint is live (402 MPP challenge returned on HEAD request)https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard