QuantConnect and LEAN

01What it is, and a short history

LEAN was released as open source on 12 January 2015, in a forum announcement by Jared Broad that described it as the result of three years of development, which places the start of the engine around 2012; the repository’s first public commit carries the release date.^1,2 It is licensed under Apache 2.0, so it can be run, modified and deployed privately without the hosted platform.²

The engine is written in C#. Python algorithms call the same engine through Python.NET, so a Python strategy uses the C# order, portfolio and data machinery rather than a separate reimplementation.^5,6 Since 2024 the Python API uses PEP 8 names (set_holdings, on_data), and the older CamelCase names remain valid; the announcement warns that attribute names of your own can now clash with API methods, which is why the examples below prefix theirs with an underscore.⁷

02Architecture

One algorithm, two worlds

LEAN is event-driven. The documentation describes it as a streaming analysis system: data is fed to the algorithm one time slice at a time, in fast-forward during a backtest and in real time when live, so the same algorithm code runs in both.⁸ The engine achieves this by assembling itself from handlers chosen by configuration. The data feed, the transaction handler, the setup handler and the real-time clock each have a backtesting and a live implementation. The algorithm sees the same interface either way.⁹

Inside the engine, one loop turns the handlers’ output into calls on the algorithm. For each time slice it sets the clock, updates prices and the portfolio, lets the fill models try the open orders, fires scheduled events, updates consolidators and the indicators registered on them, calls on_data and the framework models, and then processes the orders they sent.¹¹ In a backtest all of it runs on one thread, in data time. Live, the scheduled events run on a timer thread and fills arrive from the broker whenever they happen, so an event can fire, and a position can change, between slices (Figure 1).

The algorithm framework

A strategy can be written as a single class, or as five pluggable models that the framework runs in sequence: universe selection chooses the securities, the alpha model emits directional insights, portfolio construction turns insights into portfolio targets (a quantity for each security), risk management adjusts the targets, and execution places the orders that move the portfolio towards them.¹² The separation is the same one this series uses: a signal (Indicators and the 200-day moving average), sizing (Volatility targeting) and execution (TWAP, slicing and jitter) are different problems and are easier to test apart.

Around the algorithm, a brokerage model sets what a given broker allows and charges. It fixes fees, order types and leverage, supplies the fill, slippage and buying-power models, and validates each order before it is sent.¹³ Data arrives at tick, second, minute, hour or daily resolution; US equity subscriptions default to minute.¹⁴

03Using it

A first algorithm

The smallest useful algorithm sets a date range and starting cash, subscribes to a security and trades on data. This is LEAN’s own template, in the current Python naming:¹⁵

from AlgorithmImports import *


class BasicTemplateAlgorithm(QCAlgorithm):
    def initialize(self):
        self.set_start_date(2013, 10, 7)
        self.set_end_date(2013, 10, 11)
        self.set_cash(100000)
        self.add_equity("SPY", Resolution.MINUTE)

    def on_data(self, data):
        if not self.portfolio.invested:
            self.set_holdings("SPY", 1)

A slightly larger example, the trend rule from Indicators and the 200-day moving average, shows the pieces a real strategy uses: a built-in indicator registered with the engine, a warm-up period that fills it before trading starts, and an explicit guard while it warms up.¹⁶

from AlgorithmImports import *


class SmaTrend(QCAlgorithm):
    """Hold the ETF while it is above its 200-day simple moving average; otherwise hold cash.

    The rule from Indicators and the 200-day moving average, written for LEAN. With daily bars the signal is only known at the
    close, when the market has shut, so LEAN turns the market order into a market-on-open order that fills at the next open.
    """

    def initialize(self):
        self.set_start_date(2010, 1, 1)
        self.set_end_date(2024, 12, 31)
        self.set_cash(100_000)
        # Leading underscores: in the PEP 8 API, `symbol` and `sma` are QCAlgorithm methods.
        self._symbol = self.add_equity("SPY", Resolution.DAILY).symbol
        self._trend = self.sma(self._symbol, 200, Resolution.DAILY)   # a registered indicator
        self.set_warm_up(200, Resolution.DAILY)                         # fill it before trading

    def on_data(self, data: Slice):
        if self.is_warming_up or not self._trend.is_ready:
            return
        price = self.securities[self._symbol].price
        above = price > self._trend.current.value
        if above and not self.portfolio.invested:
            self.set_holdings(self._symbol, 1.0)
        elif not above and self.portfolio.invested:
            self.liquidate(self._symbol)

When an order fills

LEAN passes a bar to the algorithm at its end time, so a daily bar arrives at the close, when the market has shut.¹⁷ What an order sent then, or at any other moment, actually does depends on its type, the data and the mode. A market order sent while the market is closed, and on US equities 16:00 counts as closed, becomes a market-on-open order and fills at the next session’s open.¹⁸ A market-on-open order is refused during the session unless the security has daily data only, and a market-on-close order must arrive at least 15.5 minutes before the close (LEAN’s default buffer, which is configurable); sent after the close, it is for the next one.^19,20 Since June 2026 (LEAN pull request 9534), a backtest on daily data no longer fills a market order sent during the session at the previous day’s close: it works the order at that day’s close or, if it arrives within the close buffer, at the next open. Live, where the broker has a price, the same order fills at once.¹⁰ Figure 3 lays the combinations out on one synthetic path.

Where the work is done

The hosted platform provides a browser IDE, research notebooks attached to the data library, cloud backtesting and live deployment.^22,23 The lean command-line tool brings the same workflow to a local editor: it runs the engine locally in Docker and can push projects to and pull them from the cloud. Its documentation states that using it requires membership of a paid organisation tier.^24,25

pip install --upgrade lean      # needs Docker for local runs
lean login                      # link the CLI to your QuantConnect account
lean init                       # set up a workspace in the current directory
lean create-project "SMA Trend"
lean backtest "SMA Trend"       # run LEAN locally in Docker
lean cloud backtest "SMA Trend" --push   # or push and run in the cloud

04From backtest to live

When an algorithm goes live its code stays as it is. The handlers around it change (the step-by-step figure in Architecture), and with them the account it starts from, the clock it runs on and what a restart costs.

• The brokerage model. Set the model of the broker you will trade through in initialize, so the backtest already charges its fees, accepts only its order types and applies its margin or cash-account rules. The default is QuantConnect’s paper-trading model.¹³
• The starting book. Live, most brokerages load the account’s cash, positions and open orders when the algorithm starts; for the others, cash and positions are entered when deploying, and open orders are not restored.²⁶ The algorithm must cope with starting from a position it did not open.
• State across restarts. A redeploy, an update or an automatic restart after an error starts a new instance and runs initialize again.²⁶ Warm-up rebuilds the indicators; anything else the algorithm remembers must be saved, for example in the Object Store, which persists across restarts; it is shared by every backtest and live deployment in the organisation, so keep live state under a key that backtests do not touch. Paper and real-money deployments of the same project share that key too, so delete it, or use a new key, when moving from paper to real money.²⁷ Building strategies from components treats what a component must re-derive after a crash.
• Paper first. The documentation recommends paper trading before real money.²⁶ It tests the live data feed, the clock and the start-up path; the fills are still simulated. It also runs in live mode, so the backtest-only conversion of daily-data market orders does not apply there.
• Logs and notifications. self.log writes to the live log, and self.notify sends email, SMS, Telegram or webhook messages; backtests ignore notifications.²⁸

# In initialize(): the broker's fees, order types and margin rules, in the backtest too.
self.set_brokerage_model(BrokerageName.DEFAULT, AccountType.CASH)  # name your broker here

# State that warm-up cannot rebuild, kept across live restarts (import json at the top).
# The Object Store is shared by the project's backtests and its live deployment: keep live
# state under its own key, and let backtests neither read nor write it.
self._key = f"{self.project_id}/live/state"  # paper and real money share it: clear it when switching
self._state = (json.loads(self.object_store.read(self._key))
               if self.live_mode and self.object_store.contains_key(self._key) else {})


def on_order_event(self, order_event: OrderEvent):
    if order_event.status == OrderStatus.FILLED:
        self.log(f"{order_event.symbol} {order_event.fill_quantity} at {order_event.fill_price}")
        self._state["last_fill"] = str(self.time)
        if self.live_mode:  # backtests ignore notifications anyway, and must not touch live state
            self.object_store.save(self._key, json.dumps(self._state))
            self.notify.email(address="alerts@example.com", subject="Fill", message=str(order_event))

Deployment is a wizard, in the browser or in the terminal: it asks for the brokerage and its credentials, the live data provider, the node and the notifications. From the CLI, lean live deploy runs the engine on your own machine in Docker, with paper trading among the brokerages it offers, and lean cloud live deploy starts the same project on QuantConnect Cloud.^26,29,30

lean live deploy "SMA Trend"               # live on this machine, in Docker
lean cloud live deploy "SMA Trend" --push  # or push and deploy on QuantConnect Cloud

Keep the data resolution the backtest used, and remember the one order rule that differs by design: live, a market order on daily data fills at the market price at once (Figure 3). Release discipline, staged capital and the kill switch are the subject of Going live; comparing the account with its backtest day by day is that of Live versus backtest reconciliation.

05Data

The data library covers point-in-time US equities free of survivorship bias, plus derivatives and alternative datasets, usable directly in backtests and notebooks; some datasets are licensed separately. The documented coverage of the core price data:^{31,32,33,34,35,36}

Equity prices are split- and dividend-adjusted by default, and raw, split-adjusted and total-return modes can be chosen per subscription (a scaled-raw mode applies to history requests).¹⁴ The choice matters: under the default adjusted mode a backtest also fills at adjusted prices, which differ from the prices a live order will see, so a strategy whose sizing, limit prices or cost model depends on the traded price may be better tested on raw data.

06Strengths and cautions

Problems in a LEAN backtest usually trace to defaults and data assumptions rather than to the engine, and four habits address most of them.

Four habits make results from any backtesting engine, this one included, closer to what live trading will deliver:

1. Set the reality models explicitly. Choose the brokerage model for the broker you will use and a slippage model; do not rely on the defaults.^37,38
2. Backtest at the resolution you will trade. If live orders are sent intraday, backtest on minute data, so fills see the same prices and times.
3. Record the engine version and parameters with every result. The engine evolves; a backtest that cannot be rerun on the same code is an anecdote.
4. Reconcile live against backtest from the first day. Compare positions and fills, not only returns. Differences found in the first week are cheap; differences found after a year are not.

07Documentation

The official documentation is extensive. These pages are the most useful entry points.