Implementation:Nautechsystems Nautilus trader BacktestEngine Add Instrument
| Field | Value |
|---|---|
| sources | https://github.com/nautechsystems/nautilus_trader , https://nautilustrader.io/docs/ |
| domains | backtesting, instrument management, market definition |
| last_updated | 2026-02-10 12:00 GMT |
Overview
Concrete tool for registering a financial instrument with the backtest engine provided by NautilusTrader.
Description
The add_instrument method on BacktestEngine validates that the instrument's venue has already been registered, checks that the instrument type is compatible with the venue's account type (e.g., CurrencyPair cannot be added to a single-currency CASH account), ensures a market data client exists, and then registers the instrument in both the kernel's data engine cache and the simulated exchange's internal instrument registry.
Usage
Call engine.add_instrument(instrument) after adding the venue but before adding any market data for that instrument.
Code Reference
- Source location:
nautilus_trader/backtest/engine.pyx, lines 720--769 - Signature:
def add_instrument(self, instrument: Instrument) -> None
- Import:
from nautilus_trader.backtest.engine import BacktestEngine
# Instrument subclasses:
from nautilus_trader.model.instruments import CurrencyPair, Equity, FuturesContract
I/O Contract
Inputs:
| Parameter | Type | Required | Description |
|---|---|---|---|
instrument |
Instrument |
Yes | The instrument definition to register. Must have a venue that is already added to the engine. |
Outputs / Side Effects:
| Output | Type | Description |
|---|---|---|
| None (return) | None |
Method mutates engine state in place. |
| Cache entry | side effect | The instrument is processed by the data engine and stored in the kernel cache for strategy lookups. |
| Exchange registration | side effect | The instrument is added to the SimulatedExchange for the instrument's venue, enabling the matching engine to process orders.
|
| Data client | side effect | A BacktestMarketDataClient is created for the venue if not already present.
|
Raises:
| Exception | Condition |
|---|---|
InvalidConfiguration |
The venue for the instrument has not been added to the engine. |
InvalidConfiguration |
A CurrencyPair instrument is added to a venue with a single-currency CASH account.
|
Usage Examples
Registering an equity instrument:
from nautilus_trader.backtest.engine import BacktestEngine
from nautilus_trader.test_kit.providers import TestInstrumentProvider
engine = BacktestEngine()
# ... add venue first ...
instrument = TestInstrumentProvider.equity("AAPL", "XNAS")
engine.add_instrument(instrument)
Registering a cryptocurrency pair on a margin venue:
from nautilus_trader.model.instruments import CurrencyPair
# Venue must have been added with AccountType.MARGIN or multi-currency CASH
btc_usdt = TestInstrumentProvider.btcusdt_binance()
engine.add_instrument(btc_usdt)