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. Then install Keel with pipx install keel-trade . v0.4.2 is 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. For multiple schemas, prefer keel components describe-batch ROC ForecastScaler ForecastWeightNormalizer.

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 compose --source-file my_strategy.py --dry-run --format json

If validation or compile feedback includes errors, the CLI prints structured JSON pointing at the problem — missing parameter, type mismatch, unknown component, malformed universe. Fix and re-run the dry-run compose loop.

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 save your strategy to the platform.

# Save the strategy — returns a strategy id like str_abc123
keel strategy compose --source-file my_strategy.py --name my_strategy --format json

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. The CLI waits by default for up to about 90 seconds and returns a run id plus status URL if the run is still active.

# Start a backtest — returns run_id
BT_ID=$(keel backtest run str_abc123 \
    --start-date 2025-01-01 \
    --end-date 2026-02-27 \
    --format json | jq -r '.run_id')

# Pull the summary
keel backtest summarize "$BT_ID" --format json

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 summarize btr_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.

# Full JSON summary for the run
keel backtest summarize "$BT_ID" --format json

# Find recent backtest-related calls
keel audit list-last --n 20 --format json

Once a backtest passes muster, the same strategy ships live with keel live deploy str_abc123 --account-id acct_xyz789 against your Hyperliquid account for a preview. Actual deploy requires OAuth live scope, local arming, and an explicit --no-preview call. The Pipeline that passed the backtest is the same Pipeline that trades live — no port from research code to production execution.