Rank traders by PnL for any token — realized, unrealized, and ROI via Nansen on-chain analytics.
What it does
The Nansen TGM PnL Leaderboard endpoint ranks traders by their profit-and-loss performance for a specific token on a given blockchain. It returns both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages, holding amounts, netflow data, and trading patterns. The endpoint supports filtering by trader address, label, PnL ranges, holding amounts, and number of trades, with optional premium label tiers for smart money identification.
This is a POST endpoint under the Nansen API v1 Token God Mode (TGM) suite. It accepts a chain identifier, token contract address, date range, pagination, filters, and sort order. Supported chains include Ethereum, Solana, Base, Arbitrum, Polygon, and many others. The endpoint costs $0.05 per call via the x402 payment protocol (or 50 free-tier credits / 5 pro credits with an API key). Rate limits are applied per-second and per-minute, reported via response headers.
The response includes per-trader records with fields such as pnl_usd_realised, pnl_usd_unrealised, pnl_usd_total, roi_percent_total, holding_amount, holding_usd, max_balance_held, still_holding_balance_ratio, netflow_amount_usd, and nof_trades. Results are paginated and sortable by any of these fields.
Capabilities
Use cases
- —Rank the most profitable traders for a specific token over a date range
- —Identify smart money wallets accumulating or distributing a token
- —Backtest trading signals by analyzing historical trader PnL for a token
- —Build dashboards showing top performers for any ERC-20 or SPL token
- —Filter for traders with high realized ROI to discover alpha wallets
Fit
Best for
- —Crypto researchers analyzing per-token trader performance
- —Trading bots that need to identify profitable wallets for copy-trading signals
- —DeFi analytics dashboards ranking traders by PnL across multiple chains
- —Fund managers evaluating smart money behavior around specific tokens
Not for
- —Real-time sub-second trade execution or streaming price feeds
- —Non-blockchain or traditional equity market analytics
- —Users needing free unlimited access — each call costs $0.05 via x402
Quick start
curl -X POST https://api.nansen.ai/api/v1/tgm/pnl-leaderboard \
-H 'Content-Type: application/json' \
-d '{
"chain": "ethereum",
"token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
"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"
},
"chain": "ethereum",
"filters": {
"pnl_usd_realised": {
"min": 1000
}
},
"order_by": [
{
"field": "pnl_usd_realised",
"direction": "DESC"
}
],
"pagination": {
"page": 1,
"per_page": 10
},
"token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933"
}Response
{
"data": [
{
"price_usd": 0.0000123,
"nof_trades": 25,
"holding_usd": 61500,
"pnl_usd_total": 135025.5,
"holding_amount": 5000000000,
"netflow_amount": 1500000000,
"trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
"max_balance_held": 10000000000,
"pnl_usd_realised": 125000.5,
"roi_percent_total": 15.5,
"netflow_amount_usd": 25000.75,
"pnl_usd_unrealised": 10025,
"max_balance_held_usd": 123000,
"roi_percent_realised": 12.3,
"trader_address_label": "Binance 14",
"roi_percent_unrealised": 3.2,
"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 x402 pricing ($0.05/call), live 402 challenge confirmed, and comprehensive endpoint documentation. Minor deduction because no actual data response was captured (only the 402 challenge).
Warnings
- —No agents.txt or robots.txt found at the origin
- —The quick_start snippet requires either an x402 payment header or an API key — unauthenticated calls return 402
Citations
- —Endpoint price is $0.05 per call via x402 protocolhttps://api.nansen.ai
- —Endpoint supports chains including ethereum, solana, base, arbitrum, polygon, and others (TGMPnLLeaderboardChain enum)https://api.nansen.ai
- —Credit cost is 50 (free tier) or 5 (pro tier) per callhttps://api.nansen.ai
- —Endpoint returns realized PnL, unrealized PnL, ROI, holding amounts, netflow, and trade counts per traderhttps://api.nansen.ai
- —x402 402 challenge was captured live from the endpointhttps://api.nansen.ai/api/v1/tgm/pnl-leaderboard