Rank Hyperliquid perpetual traders by realized and unrealized PnL for a specific contract.
What it does
The Nansen TGM Perp PnL Leaderboard endpoint ranks traders by their profit/loss performance on Hyperliquid perpetual contracts. Given a token symbol (e.g., BTC, ETH, SOL) and a date range, it returns per-trader metrics including realized PnL, unrealized PnL, total PnL, ROI percentages, position value, holding amounts, max balance held, netflow, and number of trades. Results can be filtered by trader address, smart money labels, PnL ranges, and position values, and sorted by any of the returned numeric fields.
The endpoint is part of Nansen's Token God Mode (TGM) suite and is accessed via POST at `/api/v1/tgm/perp-pnl-leaderboard`. It supports x402 pay-per-request at $0.05 per call, or can be used with a Nansen API key (50 credits on free tier, 5 on pro). Premium labels (smart money, alpha trader) are available via the `premium_labels` parameter. Pagination is supported up to 1000 records per page.
The endpoint returns JSON with a `data` array of leaderboard records and a `pagination` object. Rate limits are communicated via response headers (per-second and per-minute). The API uses OpenAPI 3.1.0 and the full schema is available at the origin.
Capabilities
Use cases
- —Rank the most profitable Hyperliquid perpetual traders for a given token and time period
- —Identify smart money traders with the highest realized PnL on specific perp contracts
- —Screen for traders with large unrealized positions on Hyperliquid
- —Backtest which addresses consistently profit from perpetual trading
- —Build dashboards showing top perp traders by ROI or total PnL
Fit
Best for
- —Crypto trading research and alpha discovery on Hyperliquid perpetuals
- —Identifying smart money perpetual trading patterns
- —Building trader leaderboards and performance dashboards
Not for
- —Spot/DEX token PnL analysis (use /api/v1/tgm/pnl-leaderboard instead)
- —Real-time trade execution or order placement
- —Non-Hyperliquid perpetual exchanges
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard \
-H 'Content-Type: application/json' \
-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
}
},
"pagination": {
"page": 1,
"per_page": 10
},
"token_symbol": "BTC"
}Response
{
"data": [
{
"price_usd": 97500,
"nof_trades": 25,
"pnl_usd_total": 135025.5,
"holding_amount": 1.5,
"trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
"pnl_usd_realised": 125000.5,
"roi_percent_total": 15.5,
"pnl_usd_unrealised": 10025,
"position_value_usd": 146250,
"roi_percent_realised": 12.3,
"trader_address_label": "Smart HL Perps Trader",
"roi_percent_unrealised": 3.2
}
],
"pagination": {
"page": 1,
"per_page": 10,
"is_last_page": false
}
}Endpoint
Quality
Full OpenAPI 3.1.0 schema with detailed request/response models, clear x402 pricing ($0.05/call), live 402 challenge confirmed, and comprehensive endpoint documentation including filters, sort fields, and pagination. Only minor gap: no crawled docs page (returns 404), but the OpenAPI spec is thorough.
Warnings
- —No external documentation page found at api.nansen.ai/docs — rely on OpenAPI spec for integration details
- —Premium labels parameter default will change from true to false in a future release
Citations
- —Endpoint is POST /api/v1/tgm/perp-pnl-leaderboard with x402 payment at $0.05 per callhttps://api.nansen.ai
- —Supports Hyperliquid perpetual contracts only, with realized/unrealized PnL, ROI, and smart money label filteringhttps://api.nansen.ai
- —Credit cost is 50 (free tier) or 5 (pro tier); premium_labels variant costs 150 pro creditshttps://api.nansen.ai
- —x402 402 challenge confirmed live via POST probehttps://api.nansen.ai/api/v1/tgm/perp-pnl-leaderboard