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
Body

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
post
/api/v1/tgm/perp-pnl-leaderboard
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
  }
}
PreviousPerp ScreenerNextOverview

Last updated

Was this helpful?