Hyperliquid Address Leaderboard

Update: The premium_labels parameter on this endpoint now defaults to false, as previously announced in the API changelog. Requests that omit the parameter return free-tier labels at the standard credit cost. Passing premium_labels=true returns premium labels (Smart Money, Fund, etc.), is billed at 150 credits per call, and requires a paid plan. See the API changelog for details.

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

• Covers the Hyperliquid perpetuals dataset (reliable from May 2025), not per-chain history — see the Hyperliquid note on the coverage page.

Get Perpetual Trading Leaderboard Data

post

Get perpetual trading leaderboard data showing the most profitable traders within a given date range. This endpoint provides trader performance metrics including total PnL, ROI, and account values.

What it helps to answer:

1. Who are the most profitable perpetual traders in a given timeframe?

2. What is the ROI of the top performing traders?

3. What are the account values of successful perpetual traders?

4. How do trader addresses and labels correlate with performance?

5. What is a top trader holding right now?

Key Features:

• Trader address and label information

• Total, realized and unrealized PnL in USD

• ROI as a fractional ratio (0.15 means 15%)

• Traded notional and fill count over the timeframe

• The five largest open positions per trader

• Account value tracking

• Flexible filtering and sorting options

Label Tier Control (premium_labels): When omitted or set to false (the default), the response contains free-tier labels and the request is billed at the standard credit cost for this endpoint. Passing premium_labels=true returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan.

Authorizations

apikeystringRequired

API key for authentication

Body

Request model for Perp Leaderboard endpoint. This endpoint provides a perpetual trading leaderboard showing the most profitable traders within a given date range.

filtersany ofOptional

Additional filters to apply to the query.

Example: {"account_value":{"min":10000},"total_pnl":{"min":1000}}

premium_labelsany ofOptional

Controls label tier in the response. When null/omitted or false (the default), returns free-tier labels at the standard credit cost for this endpoint. When true, returns premium labels (Smart Money, Fund, and other advanced labels), is billed at 150 credits per call, and requires a paid plan.

booleanOptional

order_byany ofOptional

Custom sort order to override the endpoint's default ordering

Responses

200

Perpetual trading 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

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/perp-leaderboard

POST /api/v1/perp-leaderboard HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "date": {
    "from": "2025-10-14",
    "to": "2025-10-15"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "account_value": {
      "min": 10000
    },
    "total_pnl": {
      "min": 1000
    }
  },
  "premium_labels": true,
  "order_by": [
    {
      "field": "total_pnl",
      "direction": "ASC"
    }
  ]
}

{
  "data": [
    {
      "trader_address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "trader_address_label": "🏦 Binance 14 [0x28c6c0]",
      "total_pnl": 1250.5,
      "realized_pnl_usd": 800.25,
      "unrealized_pnl_usd": 450.25,
      "roi": 0.155,
      "volume_usd": 5000000,
      "total_trades": 420,
      "top_positions": [
        {
          "coin": "BTC",
          "side": "long",
          "size_base": 12.5,
          "position_value_usd": 125000,
          "entry_price": 60000,
          "unrealized_pnl_usd": 5000
        }
      ],
      "account_value": 10000
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}