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_rangeenum<string>

Window to rank over. Default all (data starts 2025-08-01).

Available options:1d7d30d90dall

sort_byenum<string>

Rank by this metric. Always sorted descending.

Available options:total_pnlwin_ratevolume_traded

min_tradesinteger

Only traders with at least this many trades. Defaults to 5; pass 0 for the full population.

min_days_activeinteger

Only traders active at least this many days (0 = no filter).

min_account_age_daysinteger

Only accounts at least this old, in days (0 = no filter).

min_human_scoreinteger

Only traders scoring at least this, 0-100 (0 = no filter).

dexenum<string>

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.

Available options:main_dexxyzflxvntlhynakmabcdcashparamkts

limitinteger

Results per page (1-100).

offsetinteger

Results to skip.

Trader Leaderboard

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/hyperliquid/leaderboard', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseHyperliquidTrader.json",
  "data": [
    {
      "account_age_days": 123,
      "address": "<string>",
      "days_active": 123,
      "human_score": 123,
      "rank": 123,
      "total_fees": 123,
      "total_funding": 123,
      "total_pnl": 123,
      "total_trades": 123,
      "traded_pairs": [],
      "volume_traded": 123,
      "win_rate": 123
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}