MarketDeck docs

backtest

Run historical strategy simulations with parameter grids — the data path that vets a strategy before live use.

marketdeck backtest replays historical Hyperliquid candles through a strategy and stores the equity curve and trade list as gzipped sibling files. The metadata row is what list and show consult; the heavy data only loads when you ask for it.

Usage#

marketdeck backtest <subcommand> [args]

Subcommands#

SubcommandWhat it does
list [--limit N]Newest-first metadata rollup.
show <id>Full payload including the equity curve and the trade list.
delete <id>Drop the row plus its gzipped blobs.
strategiesList built-in + custom strategies.
run --coin BTC --interval 1h --lookback-days 30 --strategy ID [--params JSON] [--start-cash 10000] [--save] [--note "..."]Execute one backtest.
sweep --coin BTC --interval 1h --lookback-days 30 --strategy ID --param k=START..END:STEP [--param …] [--start-cash 10000]Cartesian-product run over a parameter grid.
compare <id> [id...]Compare saved runs by ROI and core risk metrics.
export <id> [--csv]Export a saved run as JSON or trade CSV.
batch --strategy ID --coins BTC,ETH [flags] [--save]Run one strategy across several coins.
walk-forward --strategy ID --coin BTC [--windows N] [--window-days N]Run expanding-window walk-forward checks.
optimize --coin BTC --strategy ID --param k=A..B:SResearch alias for sweep; results are sorted by ROI.
rank [--limit N] [--strategy ID]Rank saved runs by ROI.
promote <id> [--name NAME]Save an audit marker for a selected run.

Examples#

marketdeck backtest strategies --format text

marketdeck backtest run \
    --coin BTC \
    --interval 1h \
    --lookback-days 60 \
    --strategy sma-cross \
    --params '{"fast":12,"slow":26}' \
    --start-cash 10000 \
    --save \
    --note "default sma-cross"

marketdeck backtest sweep \
    --coin BTC \
    --interval 1h \
    --lookback-days 30 \
    --strategy sma-cross \
    --param fast=5..30:5 \
    --param slow=20..80:10

marketdeck backtest batch \
    --strategy sma_crossover \
    --coins BTC,ETH,SOL \
    --interval 1h \
    --lookback-days 45

marketdeck backtest compare run-a run-b --format json
marketdeck backtest export run-a --csv > trades.csv
marketdeck backtest walk-forward --strategy rsi_mean_reversion --coin BTC
marketdeck backtest rank --limit 10
marketdeck backtest promote 42 --name btc-default

sweep evaluates the cross-product of every parameter range and returns one row per combination with the rolled-up metrics — ROI, win rate, max drawdown, profit factor, total fees, average hold time. Each combination is one backtest under the hood; the CLI just orchestrates the grid.

Where the data lives#

KindPath
Metadatabacktest_runs table (DB)
Equity curves~/.local/share/marketdeck/backtests/equity_curve/<id>.json.gz
Trade lists~/.local/share/marketdeck/backtests/trades/<id>.json.gz

marketdeck backtest delete <id> drops both the row and its sibling files. marketdeck prune backtests --older-than 90 does the same for everything older than N days.

Strategies#

Built-in strategies live in core/strategies/. Custom strategies are JSON files with init_body / evaluate_body JS. They can be generated, linted, validated, and tested through the CLI, then used by run, sweep, batch, and walk-forward.

marketdeck strategies list --format text
marketdeck strategies template --format text
marketdeck strategies show my-strategy --format text