Metadata-Version: 2.4
Name: hl-research
Version: 0.1.0
Summary: Local-first quantitative research toolkit for Hyperliquid.
Project-URL: Homepage, https://github.com/ramenxbt/hl-research
Project-URL: Repository, https://github.com/ramenxbt/hl-research
Project-URL: Issues, https://github.com/ramenxbt/hl-research/issues
Author-email: Matthew Rahm <ramenxbt@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: backtesting,cli,hyperliquid,quant,research
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: duckdb<2.0,>=1.0
Requires-Dist: httpx[http2]<1.0,>=0.27
Requires-Dist: jinja2<4.0,>=3.1
Requires-Dist: matplotlib<4.0,>=3.9
Requires-Dist: plotly<6.0,>=5.22
Requires-Dist: polars<2.0,>=1.0
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: rich<14.0,>=13.7
Requires-Dist: textual<1.0,>=0.65
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: all
Requires-Dist: matplotlib<4.0,>=3.9; extra == 'all'
Requires-Dist: optuna<4.0,>=3.6; extra == 'all'
Requires-Dist: plotly<6.0,>=5.22; extra == 'all'
Requires-Dist: textual<1.0,>=0.65; extra == 'all'
Provides-Extra: optimize
Requires-Dist: optuna<4.0,>=3.6; extra == 'optimize'
Provides-Extra: plot
Requires-Dist: matplotlib<4.0,>=3.9; extra == 'plot'
Requires-Dist: plotly<6.0,>=5.22; extra == 'plot'
Provides-Extra: tui
Requires-Dist: textual<1.0,>=0.65; extra == 'tui'
Description-Content-Type: text/markdown

# hl-research

[![PyPI](https://img.shields.io/pypi/v/hl-research.svg)](https://pypi.org/project/hl-research/)
[![Python](https://img.shields.io/pypi/pyversions/hl-research.svg)](https://pypi.org/project/hl-research/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/ramenxbt/hl-research/actions/workflows/ci.yml/badge.svg)](https://github.com/ramenxbt/hl-research/actions/workflows/ci.yml)

**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.

```bash
pip install hl-research
```

---

## The headline feature

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

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

![wallet wrapped report](docs/assets/wallet-wrapped.png)

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](#quickstart)
- [What you get](#what-you-get)
- [Tour by command group](#tour-by-command-group)
- [Architecture](#architecture)
- [FAQ](#faq)

---

## Quickstart

Requires Python 3.12 or newer.

```bash
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.

```text
$ 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
```

```text
$ 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:

```bash
hlr wallet inspect 0xabc...
```

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

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

Without `--out` you get a terminal summary:

```text
╭─ 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:

```text
$ 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:

```text
$ 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:

```text
$ 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:

```text
$ 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

```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 []
```

```text
$ 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:

```bash
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

```bash
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

```text
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`](examples/basic_backtest.ipynb) and [`examples/wallet_analysis.ipynb`](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](CONTRIBUTING.md). Issues and PRs welcome.

---

## Install

```bash
pip install hl-research
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv pip install hl-research
```

Optional extras:

```bash
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](https://ramenxbt.github.io/hl-research/).

- [Quickstart](https://ramenxbt.github.io/hl-research/quickstart/)
- [Command reference](https://ramenxbt.github.io/hl-research/commands/data/)
- [Writing a strategy](https://ramenxbt.github.io/hl-research/reference/strategies/)
- [Architecture](https://ramenxbt.github.io/hl-research/reference/architecture/)

## License

MIT. See [LICENSE](LICENSE).
