hl-research 0.1.0

Local-first quantitative research toolkit for Hyperliquid.

hl-research

A Python toolkit for quantitative research on Hyperliquid. Pulls historical data from the HL info API on demand, caches it locally as Parquet, and ships research primitives for backtesting, wallet behavior analysis, vault inspection, and funding research. Runs from a laptop. No infrastructure.

pip install hl-research

---

The headline feature

Paste a wallet, get a self-contained HTML report:

hlr data pull-fills 0xabc... --since 2024-01-01
hlr wallet wrapped 0xabc... --out wrapped.html
open wrapped.html

PnL by asset, hour-of-day pattern, hold-time distribution, funding ledger, behavior cluster, counterfactual vs holding spot, top wins and losses. One file. Shareable.

---

Contents

• Quickstart
• What you get
• Tour by command group
• Architecture
• FAQ

---

Quickstart

Requires Python 3.12 or newer.

pip install hl-research

# Pull cache for one asset
hlr data pull BTC --since 2024-01-01
hlr data pull-funding BTC --since 2024-01-01

# See what's cached
hlr data ls

# Inspect a wallet (live)
hlr wallet inspect 0xabc...

# Build the wrapped report
hlr data pull-fills 0xabc... --since 2024-01-01
hlr wallet wrapped 0xabc... --out wrapped.html

# Browse interactively
hlr tui

Every command supports --json for piping into scripts. Report commands accept --out PATH for standalone HTML artifacts.

---

What you get

Command group	What it does
hlr data	Incremental Parquet cache (DuckDB metadata) over the HL info API
hlr wallet	Inspect any wallet, build wrapped reports, list fills and funding
hlr funding	Funding-rate history, cross-asset heatmap, perp-perp basis, naive prediction
hlr vault	List, rank, and inspect HLP and user vaults
hlr backtest	Run strategy files written in plain Python, grid + random optimization, walk-forward
hlr tui	Six-screen Textual app over the same data layer

---

Tour by command group

hlr data — local cache

The cache is the foundation. Everything else reads from it.

$ hlr data ls

  KIND      ENTITY        INTERVAL   ROWS       SIZE   SINCE        UNTIL        UPDATED
 ────────────────────────────────────────────────────────────────────────────────────────────────
  candles   BTC           1h          720   34.68 KB   2024-04-01   2024-04-30   2026-05-19 15:44
  candles   ETH           1h          720   34.95 KB   2024-04-01   2024-04-30   2026-05-19 15:44
  candles   SOL           1h          720   35.12 KB   2024-04-01   2024-04-30   2026-05-19 15:44
  fills     0xa1b2…0000   —            18    6.27 KB   2024-04-01   2024-04-12   2026-05-19 15:44
  funding   BTC           —           720   14.16 KB   2024-04-01   2024-04-30   2026-05-19 15:44
  funding   ETH           —           720   14.27 KB   2024-04-01   2024-04-30   2026-05-19 15:44

$ hlr data info
╭─ cache ──────────────────────────────────────────────────────────────────────╮
│                                                                              │
│  CACHE DIRECTORY    ~/.cache/hl-research                                     │
│  TOTAL SIZE         203.08 KB                                                │
│  FILES              9                                                        │
│  DATASETS           9                                                        │
│  LAST SYNC          2026-05-19 15:44                                         │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Incremental by default — re-running pull resumes from the last cached candle.

hlr wallet — paste an address

Live account state:

hlr wallet inspect 0xabc...

Behavioral wrapped report (see screenshot above) — the headline artifact:

hlr wallet wrapped 0xabc... --out wrapped.html

Without --out you get a terminal summary:

╭─ wallet wrapped ─────────────────────────────────────────────────────────────╮
│                                                                              │
│  WALLET            0xa1b2…0000                                               │
│  PERIOD            2024-04-01 → 2024-04-12                                   │
│  REALIZED PNL      +$4,240.00                                                │
│  FUNDING NET       $0.00                                                     │
│  WIN RATE          88.9%                                                     │
│  TRADES            9                                                         │
│  CLUSTER           chad                                                      │
│                    Win rate was at least 65% and total PnL exceeded 1k.      │
│                                                                              │
│  HOLD vs ACTUAL    -$17,908.51   (pass --out to write the full HTML report)  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Behavior clusters are rules-based — revenge_trader, funding_farmer, scalper, swing_trader, chad, leverage_addict, hold_and_pray, balanced. The output includes the reason that triggered the classification.

hlr funding — rates, basis, prediction

Cross-asset funding snapshot, sorted by absolute rate, annualized APR on the right:

$ hlr funding heatmap

  ASSET       RATE
 ──────────────────────────────────────────────────────────────────────────────────────────────
  BTC     +0.0147%                               │████████████████████████████   +16.1% APR
  SOL     +0.0134%                               │█████████████████████████      +14.7% APR
  HYPE    -0.0059%                    ███████████│                               -6.4% APR
  ETH     +0.0014%                               │███                            +1.5% APR

History + sparkline:

$ hlr funding history BTC
╭─ funding history ────────────────────────────────────────────────────────────╮
│                                                                              │
│  ASSET              BTC                                                      │
│  OBSERVATIONS       720                                                      │
│  RANGE              2024-04-01 → 2024-04-30                                  │
│  LATEST             +0.0147% / period                                        │
│  MEAN               +0.0126% / period                                        │
│                                                                              │
│  ▄▂▁▁▄▄▅▇▅▂▇█▄▂▆▇▄▆▂▁▂▇▅▃▅▆▅▆▃▂▂▃▃▃▇▂▃▅▁▁▇▆▇▇▃▂▆▇▃▁                          │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Perp-vs-perp basis leaderboard:

$ hlr funding arb BTC

  PAIR          LATEST BASIS   ANNUALIZED   MEAN BASIS     N
 ────────────────────────────────────────────────────────────
  BTC / HYPE        +0.0206%      +22.52%     +0.0168%   720
  BTC / ETH         +0.0133%      +14.60%     +0.0035%   720
  BTC / SOL         +0.0013%       +1.45%     -0.0036%   720

Naive EWMA prediction with disclaimer:

$ hlr funding predict BTC
╭─ funding prediction ─────────────────────────────────────────────────────────╮
│                                                                              │
│  PREDICTED RATE     +0.0111%                                                 │
│  LOWER (95%)        +0.0013%                                                 │
│  UPPER (95%)        +0.0209%                                                 │
│                                                                              │
│  Naive EWMA baseline. Do not trade on this without a real model.             │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

hlr backtest — strategies in plain Python

# my_strategy.py
from hl_research.backtest.strategy import Order, Strategy

class MeanReversion(Strategy):
    def __init__(self):
        super().__init__()
        self._lookback = []

    def on_candle(self, candle, ctx):
        self._lookback.append(candle.close)
        if len(self._lookback) > 20:
            self._lookback.pop(0)
        mean = sum(self._lookback) / len(self._lookback)
        position = ctx.positions.get(candle.asset)
        held = position.size if position else 0.0
        if candle.close < mean * 0.99 and held <= 0:
            return [Order(asset=candle.asset, side="buy", size=0.05, kind="market")]
        if candle.close > mean * 1.01 and held > 0:
            return [Order(asset=candle.asset, side="sell", size=abs(held),
                          kind="market", reduce_only=True)]
        return []

$ hlr backtest run my_strategy.py --asset BTC

╭─ backtest ───────────────────────────────────────────────────────────────────╮
│                                                                              │
│  STRATEGY           MeanReversion                                            │
│  ASSET              BTC                                                      │
│  PERIOD             2024-04-01 → 2024-04-30                                  │
│                                                                              │
│  TOTAL RETURN       -2.43%                                                   │
│  SHARPE             -1.18                                                    │
│  MAX DRAWDOWN       -2.43%                                                   │
│  HIT RATE           +0.00%                                                   │
│  PROFIT FACTOR      0.00                                                     │
│  TRADES             4                                                        │
│  NET FUNDING        -$149.27                                                 │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

╭─ equity ─────────────────────────────────────────────────────────────────────╮
│                                                                              │
│  ████████▇▇▆▆▆▆▆▆▆▆▆▆▆▆▅▅▄▄▄▄▄▄▄▄▄▄▄▃▃▃▃▃▃▃▃▃▃▃▂▂▁▁▁▁▁▁▁▁▁▁▁▁                │
│                                                                              │
│  START   $100,000.00    END     $97,571.67                                   │
│  PEAK    $100,000.00    TROUGH  $97,571.67                                   │
│  CHANGE  -$2,428.33 (-2.43%)                                                 │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

The example loses money on this short window — backtesting on a month of one asset is a sanity check, not an alpha signal.

Optimization and walk-forward:

hlr backtest optimize my_strategy.py --param "lookback:10..30:5"
hlr backtest walk-forward my_strategy.py --window 90d --step 30d
hlr backtest run my_strategy.py --asset BTC --out report.html

hlr tui — interactive Textual app

hlr tui

Two-pane layout with six sections. 1–6 to switch, / for the asset picker, r to reload, q to quit. All views reuse the same cache and analytics the CLI uses.

---

Architecture

HL info endpoint
    │
    ▼
api/         typed httpx client, retries, rate limit
    │
    ▼
cache/       Parquet on disk, DuckDB metadata, incremental sync
    │
    ▼
data/        Polars LazyFrames, pure transforms
    │
    ├──▶ analytics/   wrapped, behavior, counterfactual, funding, vault
    ├──▶ backtest/    event loop, fill simulation, metrics, optimizer
    └──▶ presentation/  Rich tables, Plotly charts, Jinja2 reports
              │
              └──▶ cli/, tui/

The data layer never calls presentation. Presentation never calls the API. The CLI binds the two. Pure functions in analytics/, frozen dataclasses everywhere, mypy strict across 79 source files.

Cache layout on disk:

~/.cache/hl-research/
├── meta.duckdb                             # sync state, asset and vault tables
└── data/
    ├── candles/asset=BTC/interval=1h/2024-04.parquet
    ├── funding/asset=BTC/2024.parquet
    ├── fills/wallet=0xabc.../2024-Q2.parquet
    └── vaults/address=0xvault.../trades.parquet

Partitioned for Polars and DuckDB. Re-pulling resumes from the last cached row.

---

FAQ

Does this need a Hyperliquid account? No. Every endpoint hl-research uses is public.

Does it trade? No. hl-research is read-only by design. It never holds keys, places orders, or signs anything.

What data is missing? L2 microstructure history. Tick-level book data isn't available from the public API and we can't reconstruct it without a continuous ingestor. Candles, funding, fills, and vault state are all here.

How big does the cache get? ~50MB for two years of top-20 assets at 1h candles + funding. Active trader wallet fills add 1-10MB per wallet.

Can I use this in a notebook? Yes — see examples/basic_backtest.ipynb and examples/wallet_analysis.ipynb. Every CLI command has a programmatic equivalent under hl_research.*.

What about live mode? On the v0.2 roadmap. Today everything is on-demand from the REST endpoint.

How do I contribute? See CONTRIBUTING.md. Issues and PRs welcome.

---

Install

pip install hl-research

Or with uv:

uv pip install hl-research

Optional extras:

pip install "hl-research[plot]"      # matplotlib + plotly for charts
pip install "hl-research[tui]"       # Textual interactive app
pip install "hl-research[all]"       # everything

Docs

Full reference at ramenxbt.github.io/hl-research.

• Quickstart
• Command reference
• Writing a strategy
• Architecture

License

MIT. See LICENSE.