Hyperliquid Vaults and Leaderboard Data via API in Python

"""Read helpers for Hyperliquid vault and leaderboard data.

Three sources, one module:

- Dwellir's Hyperliquid Info proxy for the per-user queries it serves
  (clearinghouseState, batchClearinghouseStates, userVaultEquities, leadingVaults, ...).
- Hyperliquid's public Info endpoint for the two vault queries the proxy does not serve
  (vaultDetails, portfolio). Checked on 5 November 2026.
- The stats-data feeds behind app.hyperliquid.xyz: /Mainnet/vaults (every vault, about
  14 MB) and /Mainnet/leaderboard (every ranked trader, about 40 MB). Both are cached on
  disk because you want to download them once per run, not once per lookup.
"""

import json
import os
import time
from pathlib import Path

import httpx

API_KEY = os.environ.get("DWELLIR_API_KEY", "")
DWELLIR_INFO = f"https://api-hyperliquid-mainnet-info.n.dwellir.com/{API_KEY}/info"
PUBLIC_INFO = "https://api.hyperliquid.xyz/info"
STATS_BASE = "https://stats-data.hyperliquid.xyz/Mainnet"

# Info types the Dwellir proxy answers with 403 "type not allowed". Route these
# to the public endpoint. Everything else goes through Dwellir.
PUBLIC_ONLY = {"vaultDetails", "portfolio"}

CACHE_DIR = Path(__file__).parent / ".cache"


def info(query: dict, timeout: float = 30.0):
    """POST one Info query to the right host and return the parsed JSON."""
    if query["type"] in PUBLIC_ONLY:
        url = PUBLIC_INFO
    elif API_KEY:
        url = DWELLIR_INFO
    else:
        raise RuntimeError("Set DWELLIR_API_KEY to query the Dwellir Hyperliquid Info endpoint")
    resp = httpx.post(url, json=query, timeout=timeout)
    if resp.status_code >= 400:
        # The key sits in the Dwellir URL, so never let httpx print it.
        raise RuntimeError(f"{query['type']} failed with HTTP {resp.status_code}: {resp.text[:200]}")
    return resp.json()


def feed(name: str, max_age_s: int = 600):
    """Download /Mainnet/<name> once and reuse it for max_age_s seconds."""
    CACHE_DIR.mkdir(exist_ok=True)
    path = CACHE_DIR / f"{name}.json"
    if path.exists() and time.time() - path.stat().st_mtime < max_age_s:
        return json.loads(path.read_text())
    resp = httpx.get(f"{STATS_BASE}/{name}", timeout=120.0)
    resp.raise_for_status()
    data = resp.json()  # parse before caching, so a bad body is never reused
    path.write_bytes(resp.content)
    return data

def windows(pairs):
    """Turn Hyperliquid's [["day", {...}], ["week", {...}]] lists into a dict."""
    return {name: value for name, value in pairs}


def usd(value) -> str:
    """Format a numeric string as a dollar amount with thousands separators."""
    return f"${float(value):,.0f}"


def pct(value, signed: bool = True) -> str:
    """Format a fraction (0.12 = 12%) as a percentage, signed for returns."""
    return f"{float(value) * 100:{'+' if signed else ''}.1f}%"

"""Rank Hyperliquid vaults, inspect one, or list the vaults an address leads.

    python vaults.py top --by tvl --n 20
    python vaults.py top --by apr --min-tvl 250000
    python vaults.py show 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303
    python vaults.py leader 0x677d831aef5328190852e24f13c46cac05f984e7
"""

import argparse
from datetime import datetime, timezone

from hl_api import feed, info, pct, usd, windows


def last(series: list) -> float:
    """Last value of a cumulative PnL series, or 0 when the window has no points yet."""
    return float(series[-1]) if series else 0.0


def load_vaults(open_only: bool = True, min_tvl: float = 0.0) -> list[dict]:
    """Flatten the /Mainnet/vaults feed into one dict per vault."""
    rows = []
    for entry in feed("vaults"):
        summary = entry["summary"]
        if open_only and summary["isClosed"]:
            continue
        tvl = float(summary["tvl"])
        if tvl < min_tvl:
            continue
        pnls = windows(entry["pnls"])
        rows.append({
            "name": summary["name"],
            "address": summary["vaultAddress"],
            "leader": summary["leader"],
            "tvl": tvl,
            "apr": float(entry["apr"]),
            # Each window is a short series of cumulative PnL points. The last
            # point is the PnL over that window; a brand-new vault has none yet.
            "pnl_day": last(pnls["day"]),
            "pnl_week": last(pnls["week"]),
            "pnl_month": last(pnls["month"]),
            "pnl_all": last(pnls["allTime"]),
            "created": datetime.fromtimestamp(summary["createTimeMillis"] / 1000, timezone.utc),
            "kind": summary["relationship"]["type"],
        })
    return rows

def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = parser.add_subparsers(dest="command", required=True)

    top = sub.add_parser("top", help="rank vaults")
    top.add_argument("--by", choices=SORT_KEYS, default="tvl")
    top.add_argument("--n", type=int, default=20)
    top.add_argument("--min-tvl", type=float, default=0.0)
    top.add_argument("--include-closed", action="store_true")

    sub.add_parser("show", help="inspect one vault").add_argument("address")
    sub.add_parser("leader", help="vaults an address leads").add_argument("address")

    args = parser.parse_args()
    if args.command == "top":
        rows = load_vaults(open_only=not args.include_closed, min_tvl=args.min_tvl)
        print(f"{len(rows)} vaults after filters")
        print_top(rows, args.by, args.n)
    elif args.command == "show":
        show_vault(args.address)
    else:
        show_leader(args.address)


if __name__ == "__main__":
    main()

3062 vaults after filters
  #  Vault                                         TVL       APR       30d PnL  Address
  1  Hyperliquidity Provider (HLP)        $151,014,571     -0.0%      $122,470  0xdfc24b077bc1425ad1dea75bcb6f8158e10df303
  2  HLP Strategy X                       $100,778,255     +4.3%      $356,963  0x469f690213c467c39a23efacfd2816896009d7d8
  3  HLP Liquidator 2                      $30,000,002     +0.0%            $2  0xb0a55f13d22f66e6d495ac98113841b2326e9540
  4  Growi HF                              $12,496,442     -0.6%      $-82,557  0x1e37a337ed460039d1b15bd3bc489de789768d5e
  5  [ Systemic Strategies ] L/S Grids     $11,103,636   +137.0%    $1,246,919  0x07fd993f0fa3a185f7207adccd29f7a87404689d
  6  drkmttr                                $7,213,316    -36.2%   $-4,388,417  0xc179e03922afe8fa9533d3f896338b9fb87ce0c8
  7  DOUBLETOP Vault                        $7,182,580    -11.8%     $-960,705  0x53f8f390fd4f70941c5d160a964f6893c8dbceff
  8  [ Systemic Strategies ] ♾️ HyperGr     $6,132,482   +169.4%      $902,959  0xd6e56265890b76413d1d527eb9b75e334c0c5b42
  9  BredoStrategy                          $5,124,118    -39.2%   $-3,299,440  0x654016a8c9fcf0c4cb7ed6078aba21f7f399f7b7
 10  HLP Strategy A                         $3,060,457     -2.1%     $-107,633  0x010461c14e146ac35fe42271bdc1134ee31c703a

def show_vault(address: str) -> None:
    """Everything the vault page shows, from vaultDetails plus live positions."""
    details = info({"type": "vaultDetails", "vaultAddress": address})
    portfolio = windows(details["portfolio"])
    print(f"{details['name']}  ({address})")
    print(f"  leader        {details['leader']}")
    print(f"  APR           {pct(details['apr'])}")
    print(f"  leader share  {pct(details['leaderFraction'], signed=False)} of equity, "
          f"{pct(details['leaderCommission'], signed=False)} commission")
    print(f"  deposits      {'open' if details['allowDeposits'] else 'closed'}"
          f"{', vault closed' if details['isClosed'] else ''}")
    print(f"  followers     {len(details['followers'])} listed, "
          f"max distributable {usd(details['maxDistributable'])}")

    print("  returns")
    for window in ("day", "week", "month", "allTime"):
        history = portfolio[window]["accountValueHistory"]
        if not history:
            print(f"    {window:<8} no history yet")
            continue
        pnl = portfolio[window]["pnlHistory"][-1][1]
        start, end = float(history[0][1]), float(history[-1][1])
        print(f"    {window:<8} equity {usd(start):>14} -> {usd(end):>14}   "
              f"pnl {usd(pnl):>13}   volume {usd(portfolio[window]['vlm'])}")

    print("  largest followers")
    followers = sorted(details["followers"], key=lambda f: float(f["vaultEquity"]), reverse=True)
    for f in followers[:5]:
        print(f"    {f['user']}  equity {usd(f['vaultEquity']):>12}  "
              f"all-time pnl {usd(f['allTimePnl']):>12}  {f['daysFollowing']} days")

    # HLP is a parent vault: its capital sits in child vaults, which show up in
    # the vaults feed with the parent as their leader.
    children = [v for v in load_vaults(open_only=False) if v["leader"].lower() == address.lower()]
    if children:
        print(f"  child vaults ({len(children)})")
        for c in sorted(children, key=lambda c: c["tvl"], reverse=True):
            print(f"    {c['name']:<24} TVL {usd(c['tvl']):>13}  APR {pct(c['apr']):>7}  {c['address']}")

    # A vault is an address, so its open positions come from clearinghouseState
    # like any other wallet. This call runs through Dwellir.
    state = info({"type": "clearinghouseState", "user": address})
    positions = [p["position"] for p in state["assetPositions"] if float(p["position"]["szi"]) != 0]
    print(f"  open positions ({len(positions)})  account value {usd(state['marginSummary']['accountValue'])}")
    for p in sorted(positions, key=lambda p: abs(float(p["positionValue"])), reverse=True)[:10]:
        side = "LONG " if float(p["szi"]) > 0 else "SHORT"
        print(f"    {side} {p['coin']:<8} {usd(p['positionValue']):>13}  "
              f"{p['leverage']['value']}x {p['leverage']['type']}  "
              f"upnl {usd(p['unrealizedPnl'])}")

[ Systemic Strategies ] L/S Grids  (0x07fd993f0fa3a185f7207adccd29f7a87404689d)
  leader        0x2b804617c6f63c040377e95bb276811747006f4b
  APR           +137.8%
  leader share  7.9% of equity, 10.0% commission
  deposits      open
  followers     100 listed, max distributable $5,496,930
  returns
    day      equity    $11,240,855 ->    $11,111,113   pnl     $-161,380   volume $6,961,193
    week     equity    $11,048,770 ->    $11,111,113   pnl      $444,003   volume $20,822,926
    month    equity    $10,797,571 ->    $11,111,113   pnl    $1,254,395   volume $82,254,487
    allTime  equity             $0 ->    $11,111,113   pnl    $2,666,403   volume $1,072,362,168
  largest followers
    0xa9ff08af55b24bb5d064d776a078e8a292b8dfe2  equity   $3,401,808  all-time pnl     $391,981  641 days
    Leader  equity     $877,263  all-time pnl     $720,683  651 days
    0x8fec806c9e94ff7ab2af3d7e4875c2381413f98e  equity     $534,659  all-time pnl      $84,659  146 days
    0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50  equity     $483,231  all-time pnl      $19,210  83 days
    0xa69d62573ff153390148bf41b233e65901993b48  equity     $386,911  all-time pnl     $158,769  504 days
  open positions (60)  account value $11,111,113
    LONG  XMR         $3,074,524  5x cross  upnl $167,158
    LONG  ETH         $2,649,361  25x cross  upnl $-174,937
    LONG  AAVE        $1,840,490  10x cross  upnl $-197,783
    LONG  BTC         $1,400,222  40x cross  upnl $-18,806
    LONG  POL         $1,264,704  5x cross  upnl $-88,820
    LONG  BNB         $1,233,521  10x cross  upnl $-36,679
    LONG  PENDLE      $1,158,061  5x cross  upnl $-293,465
    LONG  LDO         $1,155,351  5x cross  upnl $-224,220
    LONG  PAXG          $947,295  5x cross  upnl $-79,053
    LONG  HYPE          $930,902  10x cross  upnl $-70,543

"""Rank Hyperliquid traders from the leaderboard feed and profile the top ones live.

    python leaderboard.py top --window week --by pnl --n 20
    python leaderboard.py top --window month --by roi --min-value 100000 --profile
    python leaderboard.py top --vault-leaders --n 10
    python leaderboard.py addresses --out addresses.txt
"""

import argparse

from hl_api import feed, info, pct, usd, windows
from vaults import load_vaults

WINDOWS = ("day", "week", "month", "allTime")
METRICS = ("pnl", "roi", "vlm")


def load_leaderboard(min_value: float = 0.0, min_volume: float = 0.0, window: str = "month") -> list[dict]:
    """Flatten /Mainnet/leaderboard into one dict per trader.

    min_value drops small accounts. min_volume drops accounts that did not trade
    in the window: deposits and transfers can show up as PnL on a tiny starting
    balance, which makes their ROI meaningless.
    """
    rows = []
    for row in feed("leaderboard")["leaderboardRows"]:
        value = float(row["accountValue"])
        if value < min_value:
            continue
        perf = windows(row["windowPerformances"])
        if float(perf[window]["vlm"]) < min_volume:
            continue
        rows.append({
            "address": row["ethAddress"],
            "name": row.get("displayName") or "",
            "value": value,
            # perf[window] is {"pnl": ..., "roi": ..., "vlm": ...} as strings. Flattened
            # to pnl_day, roi_day, vlm_day, pnl_week, ... pnl_allTime, roi_allTime, vlm_allTime.
            **{f"{m}_{w}": float(perf[w][m]) for w in WINDOWS for m in METRICS},
        })
    return rows

def print_top(rows: list[dict], window: str, by: str, n: int, live: bool) -> None:
    key = f"{by}_{window}"
    rows = sorted(rows, key=lambda r: r[key], reverse=True)[:n]
    states = profile([r["address"] for r in rows]) if live else {}
    print(f"{'#':>3}  {'Trader':<42} {'Account':>13} {'PnL':>13} {'ROI':>8} {'Volume':>16}")
    for i, r in enumerate(rows, 1):
        print(f"{i:>3}  {r['address']:<42} {usd(r['value']):>13} {usd(r[f'pnl_{window}']):>13} "
              f"{pct(r[f'roi_{window}']):>8} {usd(r[f'vlm_{window}']):>16}")
        notes = [r["name"]] if r["name"] else []
        if r["address"] in states:
            notes.append(describe(states[r["address"]]))
        if notes:
            print(f"     {' | '.join(notes)}")

def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    sub = parser.add_subparsers(dest="command", required=True)

    top = sub.add_parser("top", help="rank traders")
    top.add_argument("--window", choices=WINDOWS, default="week")
    top.add_argument("--by", choices=METRICS, default="pnl")
    top.add_argument("--n", type=int, default=20)
    top.add_argument("--min-value", type=float, default=0.0,
                     help="ignore accounts below this value in USD")
    top.add_argument("--min-volume", type=float, default=0.0,
                     help="ignore accounts that traded less than this in the window (ROI on untraded deposits is noise)")
    top.add_argument("--vault-leaders", action="store_true",
                     help="only traders who lead at least one open vault")
    top.add_argument("--profile", action="store_true",
                     help="add live positions from Dwellir batchClearinghouseStates")

    dump = sub.add_parser("addresses", help="write every leaderboard address to a file")
    dump.add_argument("--out", default="addresses.txt")

    args = parser.parse_args()
    if args.command == "addresses":
        rows = load_leaderboard()
        with open(args.out, "w") as fh:
            fh.write("\n".join(r["address"] for r in rows) + "\n")
        print(f"wrote {len(rows)} addresses to {args.out}")
        return

    rows = load_leaderboard(min_value=args.min_value, min_volume=args.min_volume, window=args.window)
    print(f"{len(rows)} traders after filters")
    if args.vault_leaders:
        # A leader can run several vaults (HLP's leader runs eight). Name the
        # largest and count the rest.
        vaults_by_leader: dict[str, list[dict]] = {}
        for v in sorted(load_vaults(open_only=True), key=lambda v: v["tvl"], reverse=True):
            vaults_by_leader.setdefault(v["leader"], []).append(v)
        rows = [dict(r, name=f"leads {vs[0]['name']} ({usd(vs[0]['tvl'])} TVL"
                             + (f", and {len(vs) - 1} more)" if len(vs) > 1 else ")"))
                for r in rows if (vs := vaults_by_leader.get(r["address"]))]
        print(f"{len(rows)} of them lead an open vault")
    print_top(rows, args.window, args.by, args.n, live=args.profile)


if __name__ == "__main__":
    main()

def profile(addresses: list[str]) -> dict[str, dict]:
    """Live account state for many wallets in one Dwellir request.

    batchClearinghouseStates is a Dwellir-only Info type. It is billed per wallet,
    so 20 addresses cost 20 responses, the same as 20 single calls, in one round trip.
    """
    result = info({"type": "batchClearinghouseStates", "users": addresses}, timeout=60.0)
    return {address: state for address, state in result["successful_states"]}


def describe(state: dict) -> str:
    """One line: biggest position, leverage, margin use."""
    summary = state["marginSummary"]
    value = float(summary["accountValue"])
    used = float(summary["totalMarginUsed"])
    positions = [p["position"] for p in state["assetPositions"] if float(p["position"]["szi"]) != 0]
    if not positions:
        return f"flat, margin used {used / value * 100 if value else 0:.0f}%"
    big = max(positions, key=lambda p: abs(float(p["positionValue"])))
    side = "long" if float(big["szi"]) > 0 else "short"
    return (f"{len(positions)} positions, largest {side} {big['coin']} "
            f"{usd(big['positionValue'])} at {big['leverage']['value']}x, "
            f"margin used {used / value * 100 if value else 0:.0f}%")

48192 traders after filters
  #  Trader                                           Account           PnL      ROI           Volume
  1  0x5b5d51203a0f9079f8aeb098a6523a13f298c060  $220,434,589   $58,999,938   +35.1%     $145,461,895
     23 positions, largest short ETH $184,268,026 at 5x, margin used 100%
  2  0xb83de012dba672c76a7dbbbf3e459cb59d7d6e36  $196,167,837   $51,772,639   +35.4%     $229,779,403
     30 positions, largest short BTC $147,935,229 at 5x, margin used 100%
  3  0x024294c53a69c1e6b39810b3fac87385752fffa1   $46,014,702   $26,138,317  +183.1%     $370,469,635
     flat, margin used 0%
  4  0xf5d81a135f756ca16544e53c20fc20643ec3ad53   $97,862,218   $20,575,626   +24.1%  $13,401,831,903
     29 positions, largest long BTC $279,299 at 3x, margin used 9%
  5  0x7fdafde5cfb5465924316eced2d3715494c517d1   $44,531,145   $16,380,053   +28.8%     $766,542,921
     BobbyBigSize | 35 positions, largest short BTC $37,965,921 at 30x, margin used 53%

"""Show a wallet's vault deposits with names, lockups and vault performance.

    python my_vaults.py 0x677d831aef5328190852e24f13c46cac05f984e7
"""

import sys
from datetime import datetime, timezone

from hl_api import info, pct, usd
from vaults import load_vaults


def main(address: str) -> None:
    # userVaultEquities runs through Dwellir. It returns address, equity and
    # lockup only, so we join the vaults feed for names and APR.
    equities = info({"type": "userVaultEquities", "user": address})
    if not equities:
        print(f"{address} has no vault deposits")
        return
    vaults = {v["address"]: v for v in load_vaults(open_only=False)}
    now = datetime.now(timezone.utc)

    total = 0.0
    print(f"{'Vault':<34} {'Equity':>12} {'APR':>9} {'TVL':>14}  Lockup")
    for e in equities:
        v = vaults.get(e["vaultAddress"])
        name = v["name"] if v else e["vaultAddress"]
        apr = pct(v["apr"]) if v else "n/a"
        tvl = usd(v["tvl"]) if v else "n/a"
        unlock = datetime.fromtimestamp(e["lockedUntilTimestamp"] / 1000, timezone.utc)
        lock = "unlocked" if unlock <= now else f"locked until {unlock:%Y-%m-%d %H:%M} UTC"
        total += float(e["equity"])
        print(f"{name[:34]:<34} {usd(e['equity']):>12} {apr:>9} {tvl:>14}  {lock}")
    print(f"{'total':<34} {usd(total):>12}")


if __name__ == "__main__":
    if len(sys.argv) != 2:
        sys.exit(__doc__)
    main(sys.argv[1])

9076 traders after filters
103 of them lead an open vault
  #  Trader                                           Account           PnL      ROI           Volume
  1  0x49e96e255ba418d08e66c35b588e2f2f3766e1d0   $30,940,980   $14,356,501   +36.7%   $1,410,528,403
     leads TEST VAULT DO NOT SEND FUNDS HERE ($100 TVL)
  2  0xf517639a8872e756ac98d3c65507d2ebc25cc032   $11,304,504    $1,579,753   +17.0%     $755,212,366
     leads 100x degen Vault ($5 TVL)
  3  0x94dac1facdc4afd2614c3119447187b4143bc449   $10,354,584      $636,752   +50.0%      $14,828,128
     leads Big Brother Capital ($1,345 TVL)
  4  0x7facb3ec0415d6605e0cf5dff744f1108224ff4d      $951,789      $415,872  +137.1%       $2,352,282
     leads Long HYPE | Short Garbage ($1,192 TVL)
  5  0xf04ac903c91a028c9a6de6dcb86875920f02206c       $97,468       $88,102  +158.0%       $3,451,895
     leads Special Sits 50x ($0 TVL)