Skip to content

Quickstart#

Install:

pip install hl-research

This walkthrough takes about ten minutes and ends with a wallet wrapped HTML report you can share.

1. Pull cache#

Every analysis runs against the local Parquet cache. Pull at least one asset's candles and funding before doing anything else.

hlr data pull BTC --since 2024-01-01
hlr data pull-funding BTC --since 2024-01-01
hlr data ls

hlr data ls shows what's in the cache. The cache lives under ~/.cache/hl-research/ by default; override with --cache-dir or HLR_CACHE_DIR.

2. Inspect a wallet#

hlr wallet inspect 0xabc...

Live HL info call. Shows account equity, withdrawable, margin used, and any open positions.

3. Build a wrapped report#

Pull the wallet's fills first, then build the report:

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

The HTML file is fully self-contained (plotly bundle inlined). You can share it. It includes:

  • PnL by asset
  • Hour-of-day heatmap
  • Hold-time distribution
  • Funding ledger
  • Behavior cluster (revenge trader, funding farmer, scalper, etc.)
  • Counterfactual versus holding spot from entry

4. Run a backtest#

Write a strategy file:

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

class MovingAverage(Strategy):
    def on_candle(self, candle, ctx):
        # return a list of Order objects each candle
        return []

Then:

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

See Writing a strategy for the full API.

5. Explore interactively#

hlr tui

Two-pane Textual app. Press 1 through 6 to jump between Home, Wallet, Funding, Vault, Backtest, and Settings. Press / for the picker, q to quit.

Output modes#

Every command supports:

  • Default: formatted output for humans (Rich tables, panels)
  • --json: machine-readable JSON to stdout
  • --out PATH: standalone HTML report (where applicable)

Pipe the JSON forms into jq, scripts, or notebooks for anything beyond the built-in views.