Hyperliquid Leaderboard

Common Scenarios

Usecase	Required Parameters	Optional Filters	Expected Output
Find top perpetual traders in a specific date range	date ={ "from": "2025-10-14", "to": "2025-10-15" }	pagination ={ "page": 1, "per_page": 10 }	List of the most profitable perpetual traders (addresses and labels) with their total PnL, ROI (%), and account values in the date range
Filter leaderboard for high-value profitable accounts	date ={ "from": "2025-10-14", "to": "2025-10-15" }	filters ={ "account_value": { "min": 10000 }, "total_pnl": { "min": 1000 } }	Leaderboard limited to traders with $10k+ account value and $1k+ profit, for easier benchmarking
Show only smart money leaders (filtered by trader address label)	date ={ "from": "2025-10-14", "to": "2025-10-15" }	filters ={ "trader_address_label": "Smart Money" }	Leaderboard showing only traders identified as Smart Money, with PnL, ROI, and account value for each

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 are the ROI percentages for top performing traders?

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

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

Key Features:

• Trader address and label information

• Total PnL tracking in USD

• ROI calculations as percentages

• Account value tracking

• Flexible filtering and sorting options

Authorizations

ApiKeyAuth

apiKeystringRequired

API key for authentication

Body

application/json

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

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

post

/api/v1/perp-leaderboard

HTTPcURLJavaScriptPython

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,
      "roi": 15.5,
      "account_value": 10000
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  }
}