---
title: "Trader Leaderboard"
method: GET
path: "/gateway/v1/hyperliquid/leaderboard"
tags: ["Hyperliquid"]
---

# Trader Leaderboard

`GET /gateway/v1/hyperliquid/leaderboard`

Returns traders ranked by a chosen performance metric (PnL by default), with quality filters to exclude bots and brand-new accounts. Each row carries `rank` (1-based, offset-adjusted position in this response's ordering).

**Metric basis — does NOT reconcile with `/performance`:** the leaderboard is built on the upstream Hydromancer trade model, whose `total_pnl` is funding-INCLUSIVE over an all-markets trade universe, while `/hyperliquid/performance`/`/trades`/`/trades/aggregate` are funding-EXCLUDED over our episode warehouse. A leaderboard PnL and the same trader's `/performance` net can differ severalfold — do not display them side-by-side as the same number.

**Ranking:** `sort_by` (`total_pnl`, `win_rate`, `volume_traded`) over a `time_range` window (`1d`, `7d`, `30d`, `90d`, `all`). Always sorted descending.

**Filters:** `min_trades` (defaults to 5; pass `0` for the full population), `min_days_active`, `min_account_age_days`, `min_human_score`, and `dex` (`main_dex` or omit for the NATIVE market only — note `/trades/aggregate` omits to ALL markets — or a builder market: `xyz`, `flx`, `vntl`, `hyna`, `km`, `abcd`, `cash`, `para`, `mkts`).

Paginated with `limit`/`offset`; `meta.total` is the exact count matching your filters.

## Query parameters

- `time_range` '1d' | '7d' | '30d' | '90d' | 'all' — Window to rank over. Default all (data starts 2025-08-01).
- `sort_by` 'total_pnl' | 'win_rate' | 'volume_traded' — Rank by this metric. Always sorted descending.
- `min_trades` integer — Only traders with at least this many trades. Defaults to 5; pass 0 for the full population.
- `min_days_active` integer — Only traders active at least this many days (0 = no filter).
- `min_account_age_days` integer — Only accounts at least this old, in days (0 = no filter).
- `min_human_score` integer — Only traders scoring at least this, 0-100 (0 = no filter).
- `dex` 'main_dex' | 'xyz' | 'flx' | 'vntl' | 'hyna' | 'km' | 'abcd' | 'cash' | 'para' | 'mkts' — Market to rank within: main_dex (or omit) for the native market ONLY, or a builder market — one of: xyz, flx, vntl, hyna, km, abcd, cash, para, mkts. NOTE: the omit default differs from /trades/aggregate, where omitting dex aggregates across ALL markets.
- `limit` integer — Results per page (1-100).
- `offset` integer — Results to skip.

## Response `200`

OK

- DataResponseHyperliquidTrader
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` HyperliquidTrader[], nullable, required
    - `account_age_days` integer — Account age in days (lifetime). Omitted when the trader has no fills on record.
    - `address` string, required — Trader's wallet address (0x)
    - `days_active` integer, required — Distinct active days within the selected window
    - `human_score` integer, required — Human-likeness, 0-100
    - `rank` integer, required — 1-based position within this response's window/sort/filter set, offset-adjusted (rank = offset + row index + 1). NOT a stable global id — it shifts as the leaderboard moves.
    - `total_fees` number, double, required — Net fees, USD (positive = paid, negative = rebate)
    - `total_funding` number, double, required — Net funding, USD (positive = received)
    - `total_pnl` number, double, required — Net PnL over the window, USD (after fees + funding)
    - `total_trades` integer, required — Trades in the window
    - `traded_pairs` string[], nullable, required — Markets the trader has ever filled (lifetime — NOT limited to the selected window, unlike the metrics above), e.g. BTC, kPEPE, xyz:SILVER
    - `volume_traded` number, double, required — Notional volume, USD
    - `win_rate` number, double, required — Share of profitable trades (0-1)
  - `meta` OffsetMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable
    - `has_more` boolean — Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required — Maximum number of items returned in this response
    - `offset` integer, required — Number of items skipped (pagination offset)
    - `total` integer — Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer — Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/498f461e81c4/schema)