LEAN Engine , Algorithmic Trading

intent

Run backtests on trading strategies using QuantConnect's LEAN engine, develop and test US equity algorithms, manage market data, and deploy live trading to Interactive Brokers. use this skill when you need to validate a trading strategy against historical data, create a new algorithm, analyze backtest performance, download or update market datasets, or connect to live trading infrastructure.

inputs

required environment variables

variable	purpose	example
LEAN_ROOT	path to cloned LEAN repository	/home/user/lean
DOTNET_ROOT	path to .NET SDK installation	/home/user/.dotnet
PYTHONNET_PYDLL	path to Python shared library for pythonnet binding	$LEAN_ROOT/.libs/libpython3.11.so.1.0

add these to your shell profile before first use:

export LEAN_ROOT="$HOME/lean"
export DOTNET_ROOT="$HOME/.dotnet"
export PATH="$PATH:$DOTNET_ROOT"
export PYTHONNET_PYDLL="$LEAN_ROOT/.libs/libpython3.11.so.1.0"

system dependencies

• .NET 8 SDK (download from https://dotnet.microsoft.com/download/dotnet/8.0)
• python3 (for algorithm scripts and data download utilities)
• git (to clone QuantConnect/Lean repository)
• bash (for helper scripts)

external integrations

• Interactive Brokers TWS/Gateway: optional, required only for live trading. must be running on the specified host/port (default localhost:4002 for Gateway). requires account credentials stored in config.json.
• Yahoo Finance: accessed by download_us_universe.py to fetch historical market data. no authentication required.

directory structure

$LEAN_ROOT/
  Launcher/bin/Debug/          # pre-built launcher
    QuantConnect.Lean.Launcher.dll
  Launcher/config.json         # runtime config (algorithm, data paths, broker settings)
  Algorithm.Python/            # where you place .py algorithm files
  Data/
    equity/usa/daily/          # market data (ZIP files containing CSV)

procedure

step 1: install .NET 8 SDK and set up environment

input: none

action:

wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 8.0
export DOTNET_ROOT="$HOME/.dotnet"
export PATH="$PATH:$DOTNET_ROOT"
dotnet --version  # verify

output: .NET 8.x SDK installed and in PATH. DOTNET_ROOT and PATH environment variables set.

step 2: clone and build LEAN repository

input: $LEAN_ROOT environment variable set to target directory, .NET SDK available in PATH

action:

git clone https://github.com/QuantConnect/Lean.git "$LEAN_ROOT"
cd "$LEAN_ROOT"
dotnet build QuantConnect.Lean.sln -c Debug

output: full LEAN source tree in $LEAN_ROOT. compiled launcher at $LEAN_ROOT/Launcher/bin/Debug/QuantConnect.Lean.Launcher.dll. Python shared library at $LEAN_ROOT/.libs/libpython3.x.so.1.0 (auto-detected or manually installed).

step 3: download initial market data

input: python3, pip, $LEAN_ROOT set and built

action:

pip install yfinance pandas
python3 {baseDir}/scripts/download_us_universe.py \
  --symbols sp500 \
  --start 2020-01-01 \
  --data-dir "$LEAN_ROOT/Data"

output: ZIP files containing daily OHLCV data in $LEAN_ROOT/Data/equity/usa/daily/. each ZIP file corresponds to one ticker. data format inside each ZIP: CSV with lines YYYYMMDD HH:MM,Open*10000,High*10000,Low*10000,Close*10000,Volume (prices stored as integers, multiplied by 10000 for precision).

step 4: create or place algorithm file

input: algorithm source code (Python, inherits from QCAlgorithm)

action: place your .py file in $LEAN_ROOT/Algorithm.Python/YourAlgo.py. example:

from AlgorithmImports import *

class MyStrategy(QCAlgorithm):
    def Initialize(self):
        self.SetStartDate(2024, 1, 1)
        self.SetEndDate(2025, 1, 1)
        self.SetCash(100_000)
        self.AddEquity("SPY", Resolution.Daily)
        self.SetBenchmark("SPY")
        self.SetBrokerageModel(BrokerageName.InteractiveBrokersBrokerage,
                               AccountType.Margin)

    def OnData(self, data):
        if not self.Portfolio.Invested:
            self.SetHoldings("SPY", 1.0)

output: algorithm file exists at $LEAN_ROOT/Algorithm.Python/YourAlgo.py. class name extracted from the Python code (e.g., MyStrategy).

step 5: configure LEAN launcher

input: algorithm class name, path to .py file, data folder path, optionally Interactive Brokers credentials (if running live)

action: edit $LEAN_ROOT/Launcher/config.json. set these fields:

{
  "algorithm-type-name": "MyStrategy",
  "algorithm-language": "Python",
  "algorithm-location": "../../../Algorithm.Python/YourAlgo.py",
  "data-folder": "../Data/",
  "environment": "backtesting"
}

for live trading to Interactive Brokers, also set:

{
  "environment": "live-interactive",
  "ib-account": "U1234567",
  "ib-user-name": "your_ib_account",
  "ib-password": "your_ib_password",
  "ib-host": "127.0.0.1",
  "ib-port": 4002
}

output: config.json updated with algorithm and broker settings. original config safely preserved (see step 6 for safe execution approach).

step 6: run backtest

input: config.json populated (step 5), algorithm file in place (step 4), market data downloaded (step 3), LEAN built (step 2), environment variables set (step 1)

action: use helper script or direct dotnet invocation.

option A (helper script):

bash {baseDir}/scripts/run_backtest.sh MyStrategy YourAlgo.py

option B (direct):

export PATH="$PATH:$DOTNET_ROOT"
cd "$LEAN_ROOT/Launcher/bin/Debug"
dotnet QuantConnect.Lean.Launcher.dll

the helper script creates a temporary config.backtest.json from the original config, modifying only algorithm and environment fields. it then runs LEAN against the temp config and restores the original upon completion (via bash trap).

output: backtest runs to completion. logs printed to stdout. result files written to $LEAN_ROOT/Results/ (JSON statistics, order logs, algorithm logs).

step 7: analyze backtest results

input: completed backtest run

action: examine output files:

ls -la "$LEAN_ROOT/Results/"
cat "$LEAN_ROOT/Results/*-log.txt"                  # algorithm debug logs
cat "$LEAN_ROOT/Results/*-order-log.txt"            # trade execution log
cat "$LEAN_ROOT/Results/*.json"                     # performance statistics

output: performance metrics extracted (total return, sharpe ratio, max drawdown, win rate, etc.). trade history reviewed. algorithm behavior validated against strategy intent.

step 8: rebuild LEAN (if source code modified)

input: changes made to LEAN source files (optional step, skip if not developing LEAN internals)

action:

export PATH="$PATH:$DOTNET_ROOT"
cd "$LEAN_ROOT"
dotnet build QuantConnect.Lean.sln -c Debug

output: recompiled LEAN binaries at $LEAN_ROOT/Launcher/bin/Debug/. new launcher ready for use.

decision points

decision: run backtest vs. live trading

if environment in config.json is set to "backtesting":

• run step 6 (run backtest). LEAN will simulate trades against historical data. no broker connection required. results are deterministic and repeatable.

else if environment is set to "live-interactive":

• verify Interactive Brokers TWS or Gateway is running on the configured host/port.
• verify ib-account, ib-user-name, ib-password are populated and valid.
• run step 6. LEAN will place real orders. use extreme caution. test with small position sizes first.

else:

• configuration error. check config.json syntax and field names.

decision: market data available vs. download required

if data files exist in $LEAN_ROOT/Data/equity/usa/daily/ for all requested symbols:

• skip step 3. proceed directly to step 4.

else if data files missing or date range incomplete:

• run step 3 to download or update data from Yahoo Finance.
• if Yahoo Finance is unreachable (network timeout, rate limit), manually place ZIP files in $LEAN_ROOT/Data/equity/usa/daily/ or use alternative data source (see reference docs).

decision: algorithm language Python vs. C#

if algorithm file is .py and inherits from QCAlgorithm:

• set algorithm-language to "Python" in config.json.
• LEAN loads the algorithm via pythonnet binding. requires PYTHONNET_PYDLL environment variable set correctly.

else if algorithm is C# (.cs file):

• set algorithm-language to "CSharp".
• LEAN compiles and loads via C# runtime. no pythonnet dependency.

else:

• unsupported language or missing import. check syntax and inheritance.

decision: config.json safety (live trading credentials)

if running backtests:

• use the helper script (run_backtest.sh), which creates a temporary config and restores the original after execution.
• original config.json (including Interactive Brokers credentials) is never written to.

else if manually editing config.json for live trading:

• edit directly and carefully. credentials stored in plain text. keep file permissions restrictive (chmod 600).
• back up config.json before changes.
• do not commit credentials to version control.

output contract

backtest execution

• stdout: LEAN diagnostic output, algorithm debug logs (from self.Debug() calls), progress indicators.
• result files directory: $LEAN_ROOT/Results/
  • {timestamp}-order-log.txt: CSV format, one row per trade (symbol, quantity, entry/exit price, P&L, etc.).
  • {timestamp}-log.txt: raw algorithm log output and LEAN engine diagnostics.
  • {timestamp}-statistics.json: JSON object containing performance metrics:
    • TotalReturn: decimal return (0.15 = 15%)
    • SharpeRatio: decimal Sharpe ratio
    • MaxDrawdown: decimal max drawdown (negative)
    • WinRate: decimal fraction of profitable trades
    • ProfitFactor: gross profit / gross loss
    • TotalTrades: integer count of closed positions
    • additional fields per QuantConnect schema
  • {timestamp}-backtest-results.json: full backtest metadata and trade history

data download

• directory: $LEAN_ROOT/Data/equity/usa/daily/
• file format: one ZIP file per ticker (e.g., SPY.zip)
• contents: inside each ZIP, a single CSV file with headers Date,Open,High,Low,Close,Volume. prices stored as integers (multiply by 10000). one bar per line.

algorithm file

• location: $LEAN_ROOT/Algorithm.Python/{AlgoName}.py
• format: valid Python 3, inherits from QCAlgorithm, defines Initialize() and OnData() methods.

outcome signal

backtest completed successfully

• backtest process exits with status code 0.
• stdout contains no fatal errors or exceptions.
• result files exist in $LEAN_ROOT/Results/ with recent timestamps.
• {timestamp}-statistics.json is valid JSON and contains expected performance fields.

algorithm produced trades

• {timestamp}-order-log.txt is non-empty (contains more than just headers).
• TotalTrades field in statistics > 0.
• P&L field shows entry and exit prices for at least one position.

algorithm ran with zero trades

• {timestamp}-order-log.txt may be empty or contain only headers.
• TotalTrades field in statistics is 0.
• TotalReturn is likely 0 or matches cash interest (if configured).
• this is valid if strategy logic intentionally avoids entries (e.g., condition never met).

data download succeeded

• new or updated ZIP files appear in $LEAN_ROOT/Data/equity/usa/daily/.
• file sizes are non-zero.
• unzipping a file produces a valid CSV.

configuration error detected

• backtest process exits with non-zero status.
• stdout contains error message referencing config.json field (e.g., "algorithm-location not found").
• no result files written.
• action: fix config field and re-run step 6.

Interactive Brokers connection issue (live trading)

• backtest process exits with non-zero status.
• stderr contains "IB Gateway" or "connection refused" or "port not open".
• action: verify TWS/Gateway is running, port matches config.json, and account credentials are correct.