{
  "id": "surf.hyperliquid.leaderboard",
  "object": "tool",
  "name": "Trader Leaderboard",
  "summary": "Returns traders ranked by a chosen performance metric (PnL by default), with quality filters to exclude bots and brand-new accounts.",
  "description": "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, /hyperliquid/trades and /hyperliquid/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.\n\nRaw surf#hyperliquid/leaderboard endpoint: input is { body, queryParams, pathParams } as the provider documents them (https://docs.asksurf.ai/data-api/hyperliquid/leaderboard).",
  "category": "lookup",
  "hosted_by": "Surf",
  "runtime": "partner",
  "side_effects": false,
  "status": "live",
  "credits": 0,
  "price": null,
  "providers": [
    {
      "id": "surf",
      "name": "Surf",
      "price": null,
      "own_key_only": true
    }
  ],
  "mcp_name": "surf_hyperliquid_leaderboard",
  "input_schema": {
    "type": "object",
    "properties": {
      "queryParams": {
        "type": "object",
        "properties": {
          "time_range": {
            "default": "all",
            "type": "string",
            "enum": [
              "1d",
              "7d",
              "30d",
              "90d",
              "all"
            ],
            "description": "Window to rank over. Default all (data starts 2025-08-01). Defaults to \"all\"."
          },
          "sort_by": {
            "default": "total_pnl",
            "type": "string",
            "enum": [
              "total_pnl",
              "win_rate",
              "volume_traded"
            ],
            "description": "Rank by this metric. Always sorted descending. Defaults to \"total_pnl\"."
          },
          "min_trades": {
            "default": 5,
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Only traders with at least this many trades. Defaults to 5; pass 0 for the full population. Defaults to 5."
          },
          "min_days_active": {
            "default": 0,
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Only traders active at least this many days (0 = no filter). Defaults to 0."
          },
          "min_account_age_days": {
            "default": 0,
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Only accounts at least this old, in days (0 = no filter). Defaults to 0."
          },
          "min_human_score": {
            "default": 0,
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Only traders scoring at least this, 0-100 (0 = no filter). Defaults to 0."
          },
          "dex": {
            "type": "string",
            "enum": [
              "main_dex",
              "xyz",
              "flx",
              "vntl",
              "hyna",
              "km",
              "abcd",
              "cash",
              "para",
              "mkts"
            ],
            "description": "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": {
            "default": 20,
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Results per page (1-100). Defaults to 20."
          },
          "offset": {
            "default": 0,
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Results to skip. Defaults to 0."
          }
        },
        "additionalProperties": false
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "kind": "endpoint"
}