Python backtesting on Hyperliquid

Install

The Keel CLI ships as the keel-trade package on PyPI — version 0.1.6 as of April 2026. Recommended install path is pipx, which puts the keel binary on your PATH in an isolated virtualenv so it does not collide with project dependencies.

pipx install keel-trade

# Verify
keel --version
keel --help

Requires Python 3.11+. If you do not have pipx: brew install pipx on macOS or pip install --user pipx on Linux. If you would rather install into an existing virtualenv, plain pip install keel-trade works. v0.1.x — early but functional; expect command surface to expand. Stable enough for daily research work.

Write a strategy

A Keel strategy is a Python file that declares a Globals, a Universe, and a Pipeline of components. Components are typed steps that load data, compute signals, aggregate forecasts, and normalize portfolio weights — there are 199 registered components today covering data loaders, signals, regimes, allocators, and risk overlays. Here is a minimal momentum strategy on the top-30 HL perps by volume:

# my_strategy.py
Globals(target_timeframe="1d")

Universe(mode="top_volume", top_n=30, market="perp", resolved=[], resolved_at="")

Pipeline([
    # Load HL 15-minute price bars for the top-30 perps by volume
    PriceDataLoader(timeframe="15min"),

    # Resample to the target timeframe declared in Globals
    TargetTimeframeResampler(),

    # 8-period rate-of-change as the momentum signal
    ROC(period=8),

    # Scale forecasts to a target average absolute value of 10
    ForecastScaler(avg_abs_target=10.0),

    # Cap extreme forecasts at +/- 20
    ForecastCapper(limit=20.0),

    # Convert forecasts to portfolio weights at unit gross leverage
    ForecastWeightNormalizer(target_leverage=1.0),
], name="hl_momentum")

Save that anywhere as my_strategy.py. The components used here — PriceDataLoader, ROC, ForecastScaler, ForecastCapper, and ForecastWeightNormalizer — are real classes in the component registry. Browse the full catalog with keel components search or look up a single component with keel components detail ROC. Prefer starting from a template? keel strategy new my_strat --template momentum gives you a working scaffold.

Validate the strategy

Before running a backtest, validate the strategy file. The validator checks that the pipeline parses, components exist, types match between adjacent stages, parameters fall in accepted ranges, and the universe is resolvable. It runs entirely offline and catches the vast majority of mistakes before you burn compute on a backtest.

keel strategy validate my_strategy.py

# Also useful before backtesting:
keel strategy stage my_strategy.py      # Check it's ready to run
keel strategy explain my_strategy.py    # Show the resolved pipeline structure

If validation fails the CLI returns exit code 7 and prints a concrete pointer to the failing line — missing parameter, type mismatch, unknown component, malformed universe. Fix and re-run. Validation is fast (sub-second) so the loop is tight.

Authenticate and upload

Backtests run on the Keel platform, not your laptop — the hosted engine has the price and funding data already cached and the production-grade portfolio simulator already warmed up. Grab an API key from Settings → API Keys in the dashboard, then either set KEEL_API_KEY or run keel auth login. Then upload your strategy to the platform.

export KEEL_API_KEY=sk_org_xxx

# Upload the strategy — returns a strategy id like str_abc123
keel strategy create my_strategy.py

Run the backtest

Fire the backtest with the strategy id you just got back. The hosted engine runs your Pipeline through a production-grade portfolio simulator — per-bar fee and slippage modeling, 1-hour funding applied as a separate cashflow, and per-asset equity attribution. Backtests run async; poll keel backtest status until it completes.

# Start a backtest — returns a backtest id like bt_xyz789
keel backtest run str_abc123 \
    --start-date 2025-01-01 \
    --end-date 2026-02-27

# Poll status (completes in seconds for most universes)
keel backtest status bt_xyz789

# Pull the results
keel backtest results bt_xyz789

Inspect results

Two surfaces for the same data. The Keel app renders the decomposed equity curve (price-only, funding, combined), metrics, and per-asset attribution as an interactive report — go to the app and open the backtest. For programmatic analysis, keel backtest results bt_xyz789 returns the full JSON result — metrics, equity series, funding decomposition, weights — so you can drop it into a DataFrame and compute whatever derived statistics you need.

# Explain how the pipeline resolves (offline)
keel strategy explain my_strategy.py

# Full JSON result for the run
keel --format json backtest results bt_xyz789

# List recent runs across all strategies
keel backtest list --limit 5

Once a backtest passes muster, the same strategy ships live with keel live deploy str_abc123 --confirm against your Hyperliquid account. The Pipeline that passed the backtest is the same Pipeline that trades live — no port from research code to production execution.