Backtrader API for Python Algorithmic Trading: A Practical Guide
Backtrader's API separates strategy decisions, data feeds, indicators and broker execution. That separation is useful for diagnosing a backtest: a signal, a submitted order and a fill are different events. A historical simulation can test explicit assumptions; it cannot establish what a live account would have earned.
The objects in a Backtrader run
| Object | Responsibility | What to verify |
|---|---|---|
Cerebro | Connects feeds, strategies, broker and observers/analyzers | Which objects and settings were actually registered |
bt.Strategy | Defines decisions and handles notifications | Signal timing, pending orders and position sizing |
| Data feed | Supplies timestamped price/volume lines | Sessions, adjustments, missing bars and timezone |
bt.Indicator | Calculates lines from available data | Formula, warm-up and indexing |
| Broker | Simulates execution or delegates to an adapter | Fees, fill rules, account and supported order types |
addstrategy() accepts a strategy class; adddata() accepts a feed instance. run() starts the configured experiment. setbroker() replaces the broker object: it does not itself make execution realistic or authenticate every brokerage.
Strategy lifecycle and indicator batch calculation
Define indicators and parameters in __init__(). Before their minimum history is available, the strategy receives prenext() calls. nextstart() marks the first ready iteration and normally delegates to next(). Strategy decisions then run in next(). With replayed or live data, the same developing bar can be visited more than once, so order submission needs a guard.
notify_order() reports order status changes. Keep the returned order reference and handle completion, cancellation, rejection and margin failure. An existing position does not tell you whether another order is pending.
once(start, end) is an indicator batch-calculation method, not a substitute for a strategy's trading loop. In compatible preloaded backtests, runonce can calculate indicator arrays in batches while strategy execution remains event driven. There is no documented universal speed multiplier. Benchmark the exact data and code if runtime matters. See Operating the Platform.
Read the example as separate class fragments
These fragments illustrate the API; they are not a complete executable trading program. They need import backtrader as bt, a data feed and a Cerebro instance. The indented methods belong inside the class.
class MyFirstStrategy(bt.Strategy):
params = (('sma_period', 20),)
The strategy parameter controls the SMA period. The RSI retains its own default settings.
def __init__(self):
self.sma = bt.indicators.SimpleMovingAverage(
self.data.close, period=self.params.sma_period
)
self.rsi = bt.indicators.RSI(self.data.close)
The next fragment bases decisions on RSI only: the SMA is calculated but is not an entry filter.
def next(self):
if not self.position:
if self.rsi[0] < 30:
self.buy()
elif self.rsi[0] > 70:
self.sell()
This minimal logic omits pending-order tracking, explicit sizing, costs and protective exits. sell() submits a sell order using the selected size; it does not mean “close exactly my current long position” in every sizing configuration. Use position-aware exit handling and inspect notifications before extending the example. RSI also needs appropriate handling for data with zero average losses; test flat and one-direction price samples when choosing indicator settings.
Data feed parameters are not interchangeable
For a reproducible first run, use a saved CSV or a defined Pandas data frame. Record the vendor, download date, adjustment policy, timestamp convention and covered interval. A legacy Yahoo feed class does not establish that today's endpoint can supply any requested intraday history.
timeframe and compression describe data and support resampling; declaring a smaller interval cannot create observations that are absent. tzinput identifies the input timezone where needed, while tz controls the output timezone used by the feed. Verify session boundaries and daylight-saving transitions against known timestamps.
Live adapter parameters have narrower meanings. In the documented IB adapter, rtbar=True requests five-second real-time bars where supported; it is not a universal switch for tick-by-tick updates. what selects an IB historical data type. qcheck controls periodic wake-ups involved in delivering resampled bars: reducing it can deliver sooner but leave less room for late data. These are adapter-specific choices, not a remedy for missing vendor history. Consult the IB integration reference.
Configure and inspect a historical run
The following wiring fragment assumes cerebro, data and a strategy class called MyStrategy already exist. That class name differs from MyFirstStrategy above; select the intended class explicitly when assembling your own program.
cerebro.broker.set_cash(10000.00)
cerebro.addstrategy(MyStrategy)
cerebro.adddata(data)
cerebro.run()
Set commission and slippage before running. Add the analyzers you need rather than assuming a chart contains all statistics. For example, compare beginning and ending broker value, inspect closed-trade records, and calculate drawdown from the equity series. State the return frequency and risk-free-rate assumptions when reporting Sharpe ratio.
A high win rate alone is inconclusive. In a hypothetical ten-trade sample, nine gains of $10 and one loss of $100 produce a $10 net loss before fees despite a 90% win rate. This arithmetic is not a reported strategy result.
Use optstrategy() to enumerate candidate parameters, then compare an explicitly selected metric. Reserve later data before choosing a winner, include transaction costs, and disclose how many alternatives were tested. The best historical parameter set is not evidence of future superiority. For manual forex testing, see the FX Replay guide.
Cerebro settings that change interpretation
cheat_on_open: Enables a separatenext_open()cycle before broker evaluation, with indicators still holding their previous values. Broker support must also be enabled. It does not merely change ordinary close orders into open orders; the assumed information and submission timing must be attainable in your intended workflow.stdstats: Adds the default broker, trade and buy/sell observers. These are not a substitute for explicitly configured analyzers.tradehistory: Records additional trade history when enabled; account for memory cost.quicknotify: Delivers live broker notifications as soon as the engine can process them, instead of waiting for the next prices. It is not a configurable notification frequency.
Check the Cerebro reference against the installed release. There is no generic millisecond feed switch that guarantees high-frequency execution fidelity. Timestamp resolution, feed delivery and broker latency are separate constraints.
From simulation to a broker adapter
The default broker is a simulator. For a compatible store-based integration, obtain its broker object and attach it to Cerebro; adding a live data feed alone does not send orders to the brokerage.
Backtrader's live-trading documentation describes legacy integrations including Interactive Brokers and OANDA v1. Alpaca support comes from a separate adapter. Check current API compatibility, dependencies, market-data entitlements and order support before using any connector. A familiar broker name in old documentation is not current compatibility evidence.
Test against the intended paper endpoint using separate credentials. Reconcile submitted orders, partial fills, rejected orders, positions and cash after reconnects. A fixed week or month of paper trading does not certify readiness. Multiple assets require per-feed positions and order references; timers run within the engine's data/session processing and do not turn it into an independent always-running scheduler.
Frequently asked questions
What Python knowledge does Backtrader require?
Classes, inheritance, data handling and debugging are useful. You also need to understand order state and the assumptions behind your market data.
Does once() replace next() for faster strategy trading logic?
No. The documented once() interface supports batch indicator calculations. Strategy decisions still run through the event-driven lifecycle.
Can Backtrader trade cryptocurrency or multiple assets?
Historical testing can use compatible feeds for those instruments. Live execution depends on a maintained adapter, supported products and account permissions. Multiple feeds do not automatically implement portfolio risk controls.
Is this example ready for live trading?
No. The snippets omit complete setup, pending-order handling, explicit risk controls and broker integration. They illustrate API responsibilities and make no performance claim.