Perp PnL Leaderboard

Common Scenarios

Usecase	Required Parameters	Optional Filters	Expected Output
Filter for high-profit and high-balance addresses	token_symbol ="ETH" date ={ "from": "2025-10-14", "to": "2025-10-15" }	filters ={ "pnl_usd_realised": { "min": 100000 }, "position_value_usd": { "min": 100000 } }	Only addresses with at least $100k realized PnL and $100k+ in position value are shown
Surface only smart money traders for a specific contract	token_symbol ="SOL" date ={ "from": "2025-10-14", "to": "2025-10-15" }	filters ={ "trader_address_label": "Smart Money" }	Leaderboard limited to traders labeled as Smart Money

Get TGM Perp PnL Leaderboard Data

post

Rank traders by their profit/loss performance for a specific perpetual contract on Hyperliquid. Shows both realized profits (from completed trades) and unrealized profits (from current holdings), along with ROI percentages and trading patterns. This endpoint can be used to analyze the realized and unrealized profit for each trader who traded the input perpetual contract.

Key Features:

• Hyperliquid perpetual contracts only (no chain field needed)

• Realized and unrealized PnL tracking

• ROI calculations and trading patterns

• Position size and balance tracking

Request Format:

• token_symbol: Perpetual contract symbol (e.g., "BTC", "ETH", "SOL")

• date: Date range for analysis

• filters: Optional filters for trader addresses, PnL ranges, etc.

• pagination: Page and per_page parameters

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

Request model for TGM Perp PnL leaderboard endpoint. Simplified version that only supports Hyperliquid perpetual contracts.

token_symbolstringRequired

Perpetual contract symbol (e.g., BTC, ETH, SOL)

Example: BTC

filtersany ofOptional

Additional filters to apply to the query.

Example: {"pnl_usd_realised":{"min":1000},"position_value_usd":{"min":1000}}

order_byany ofOptional

Custom sort order to override the endpoint's default ordering

Responses

200

TGM Perp PnL leaderboard data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/api/v1/tgm/perp-pnl-leaderboard

HTTPcURLJavaScriptPython

POST /api/v1/tgm/perp-pnl-leaderboard HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 245

{
  "token_symbol": "BTC",
  "date": {
    "from": "2025-10-14",
    "to": "2025-10-15"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "pnl_usd_realised": {
      "min": 1000
    },
    "position_value_usd": {
      "min": 1000
    }
  },
  "order_by": [
    {
      "field": "pnl_usd_realised",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "trader_address_label": "🏦 Binance 14 [0x28c6c0]",
      "price_usd": 1.23,
      "pnl_usd_realised": 1250.5,
      "pnl_usd_unrealised": 100.25,
      "holding_amount": 5000,
      "position_value_usd": 6000,
      "max_balance_held": 10000,
      "max_balance_held_usd": 12000,
      "still_holding_balance_ratio": 0.5,
      "netflow_amount_usd": 2500.75,
      "netflow_amount": 1500,
      "roi_percent_total": 15.5,
      "roi_percent_realised": 12.3,
      "roi_percent_unrealised": 3.2,
      "pnl_usd_total": 1350.75,
      "nof_trades": 25
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}