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

Label Tier Control (premium_labels): The premium_labels parameter is now available to all users. When omitted, it defaults to true (premium labels). In a future release, the default will change to false. Pass premium_labels=true explicitly to preserve premium label behavior.

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}}

premium_labelsany ofOptional

Controls label tier in the response. When null/omitted (default), returns labels as per subscription plan (existing behavior). When false, returns free-tier labels for all users. When true, returns premium labels. Note: In a future release, the default will change from true to false — pass premium_labels=true explicitly to preserve premium label behavior.

booleanOptional

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

402

Payment Required

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: 287

{
  "token_symbol": "BTC",
  "date": {
    "from": "2025-10-14T00:00:00Z",
    "to": "2025-10-15T23:59:59Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "pnl_usd_realised": {
      "min": 1000
    },
    "position_value_usd": {
      "min": 1000
    }
  },
  "premium_labels": true,
  "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
  }
}