Optimize NautilusTrader backtests

Use HyperOptimizer to run NautilusTrader backtests as managed optimization trials. Your container owns the strategy and engine setup; HyperOptimizer chooses parameter sets and collects metrics.

Why NautilusTrader fits HPO

NautilusTrader strategies are often sensitive to windows, thresholds, bar sizes, sizing rules, and risk parameters. HyperOptimizer lets you expose those values as CLI flags and evaluate them across many containerized backtests.

Repeatable backtests

Run the same Nautilus script repeatedly with different parameter values.

Managed search

Let HyperOptimizer choose candidates while you focus on strategy logic.

Risk-aware metrics

Emit PnL, drawdown, order count, runtime, or custom objective scores.

Integration architecture

Package

Build an image with your NautilusTrader environment and data access.

Inject

Receive --hpo-* parameters in your backtest entrypoint.

Run

Configure your strategy and run one backtest.

Collect

Print metrics for HyperOptimizer to collect.

1. Parse HPO parameters

import argparse

def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--hpo-bar-size", type=str, default="5-MINUTE")
    parser.add_argument("--hpo-lookback-window", type=int, default=50)
    parser.add_argument("--hpo-risk-multiplier", type=float, default=1.0)
    return parser.parse_args()

args = parse_args()

2. Configure the backtest

Map CLI values into your strategy or config objects before running the engine.

strategy_config = StrategyConfig(
    bar_size=args.hpo_bar_size,
    lookback_window=args.hpo_lookback_window,
    risk_multiplier=args.hpo_risk_multiplier,
)

engine.add_strategy(MyStrategy(strategy_config))
engine.run()
backtest_result = engine.get_result()

Each HyperOptimizer trial should call engine.run() once for one parameter set.

3. Emit results

import json

metrics = {
    "total_pnl": float(backtest_result.stats_pnls.get("PnL", 0)),
    "total_orders": backtest_result.total_orders,
    "elapsed_time": backtest_result.elapsed_time,
}

for key, value in metrics.items():
    print(f"hpo.metrics.{key}={json.dumps(value, default=str)}")

Recommended metrics

Name
total_pnl
Type
objective
Description
Useful for raw profitability, but pair it with risk guardrails.
Name
max_drawdown
Type
guardrail
Description
Helps avoid unstable configurations.
Name
total_orders
Type
context
Description
Helps spot overfit runs with too few or too many orders.
Name
elapsed_time
Type
runtime
Description
Useful when you care about trial cost or operational latency.

For general setup, read the Quickstart.