| name | using-nautilus-trader |
| description | General-purpose NautilusTrader (nautilus_trader) usage guidance, OUTSIDE
the nautilus-competition framework. Use when: (1) explaining
NautilusTrader's event-driven architecture, MessageBus, or actor model
for someone new to the library; (2) deciding between `BacktestEngine` /
`BacktestNode` (historical replay) and `TradingNode` (live/testnet/paper
over real venues) and describing the shared-Strategy-code principle; (3)
writing a standalone `Strategy` subclass — lifecycle hooks (`on_start`,
`on_bar`, `on_order_filled`), `order_factory` usage, indicator
registration order; (4) picking `OmsType` (NETTING vs HEDGING) or
`AccountType` (CASH vs MARGIN) for a non-competition backtest. Do NOT
use this skill when (a) the question is specifically about the
`nautilus-competition` repo (team contract, `compete` CLI, observability,
leaderboard) — those have dedicated `nautilus-competition-*` skills; or
(b) the user is hitting the logger-singleton panic or the
catalog/instrument precision mismatch — those have dedicated
`nautilus-trader-logger-singleton` and
`nautilus-trader-catalog-instrument-precision` skills.
|
| author | Claude Code |
| version | 2.0.0 |
| date | 2026-05-12T00:00:00.000Z |
Using NautilusTrader (general guidance)
High-performance algo-trading platform with event-driven architecture.
Same Strategy code runs in backtest and live — no reimplementation.
Rust/Cython core with Python bindings.
Always check current API against upstream docs — breaking changes are
normal before v2.x.
Event-driven architecture (what to say when asked)
NautilusKernel
├── MessageBus pub/sub between components
├── Cache instruments, orders, positions, market data
├── Portfolio accounts, balances, PnL
├── DataEngine data routing (market data -> strategies)
├── ExecutionEngine order routing (strategies -> venue)
└── RiskEngine pre-trade checks
- Data flow: market data -> DataClient -> DataEngine -> Cache ->
MessageBus -> Strategies
- Order flow: Strategy -> RiskEngine -> ExecutionEngine ->
ExecutionClient -> Venue
- Component lifecycle:
INITIALIZED -> STARTING -> RUNNING -> STOPPING -> STOPPED — Strategy hooks into this via on_start, on_stop,
on_reset, on_save, on_load
Engine vs Node (when asked which to use)
| BacktestEngine / BacktestNode | TradingNode |
|---|
| Purpose | Historical replay over catalog data | Live, sandbox, paper over real venues |
| Execution | Simulated (fill models) | Real venue matching |
| Data source | ParquetDataCatalog, ticks, bars | Live adapters (Binance, Bybit, IB) |
| Use for | Research, parameter sweeps, CI tests | Production, paper trading, testnet |
BacktestNode is the high-level wrapper around BacktestEngine — use
BacktestNode for multi-run configs, BacktestEngine for fine-grained
control. The same Strategy class is passed to either — that's the
platform's headline feature.
Minimal Strategy skeleton
from nautilus_trader.trading import Strategy
from nautilus_trader.config import StrategyConfig
from nautilus_trader.indicators.average.ema import ExponentialMovingAverage
from nautilus_trader.model.enums import OrderSide
from nautilus_trader.model.identifiers import InstrumentId
from nautilus_trader.model.data import BarType, Bar
from nautilus_trader.model.objects import Quantity
class EMACrossConfig(StrategyConfig):
instrument_id: str
bar_type: str
fast_period: int = 12
slow_period: int = 26
class EMACross(Strategy):
def __init__(self, config: EMACrossConfig):
super().__init__(config)
self.instrument_id = InstrumentId.from_str(config.instrument_id)
self.bar_type = BarType.from_str(config.bar_type)
self.ema_fast = ExponentialMovingAverage(config.fast_period)
self.ema_slow = ExponentialMovingAverage(config.slow_period)
def on_start(self):
self.register_indicator_for_bars(self.bar_type, self.ema_fast)
.register_indicator_for_bars(.bar_type, .ema_slow)
.subscribe_bars(.bar_type)
():
(.ema_fast.initialized .ema_slow.initialized):
.ema_fast.value > .ema_slow.value:
.portfolio.is_net_long(.instrument_id):
order = .order_factory.market(
instrument_id=.instrument_id,
order_side=OrderSide.BUY,
quantity=Quantity.from_str(),
)
.submit_order(order)
:
.close_all_positions(.instrument_id)
Non-obvious patterns that actually cause bugs
- Register indicators BEFORE subscribing to bars — otherwise the
indicator never sees the stream.
- Use
self.order_factory — never construct Order objects directly.
- Use
Quantity.from_str(...) and Price.from_str(...) — avoids
float-precision issues and matches venue tick sizes.
BarType string format:
{instrument_id}-{step}-{aggregation}-{price_type}-{source} e.g.
BTCUSDT.BINANCE-1-MINUTE-LAST-EXTERNAL.InstrumentId string format: {symbol}.{venue} e.g.
BTCUSDT.BINANCE.- Always guard on
indicator.initialized in on_bar before reading
.value.
Venue config choices
OmsType.NETTING — single net position per instrument (crypto-style).OmsType.HEDGING — multiple positions per instrument (traditional
futures).AccountType.CASH — spot.AccountType.MARGIN — leverage.
Progressive disclosure — sibling .md files
Do NOT load these by default. Read one only if the user's question
targets its topic specifically: data-models.md (Tick/Bar/BarType
details), orders.md (bracket orders, emulation), cache.md (querying
orders/positions), actors.md, indicators.md (custom indicators),
portfolio.md, execution.md (risk engine internals),
integrations.md, adapters.md (custom venue adapter), examples.md,
best-practices.md, troubleshooting.md, installation.md.
(v2.0 removed architecture.md, backtesting.md, live-trading.md,
strategy-development.md — content is inline above or in upstream docs.)
Out of scope — use the dedicated skill
- Logger-singleton panic on 2nd
BacktestEngine init ->
nautilus-trader-logger-singleton skill.
invalid bar.volume.precision / catalog instrument mismatch ->
nautilus-trader-catalog-instrument-precision skill.- Anything inside the
nautilus-competition repo (team contract,
compete CLI, observability stack) -> the three
nautilus-competition-* skills.
