NautilusTrader Skill#

This skill teaches you how to use the NautilusTrader open-source algorithmic trading platform. NautilusTrader is a Rust-native, high-performance trading system with Python bindings (via PyO3). It works as both a backtesting engine and a live trading system — the same strategy code runs in both environments with zero changes.

Prerequisites — check before ANY task#

Before doing any work, you MUST verify the environment is ready. Follow these steps in order:

Step 1: Check if nautilus_trader exists in the workspace#

Look for a nautilus_trader/ directory in the user's workspace that contains pyproject.toml and a nautilus_trader/ Python package subdirectory. Run:

bash

ls pyproject.toml nautilus_trader/__init__.py 2>/dev/null

If both files exist, the project is present — skip to Step 3.

Step 2: Clone the repository (only if Step 1 failed)#

If the project is not found in the workspace, clone it:

bash

git clone https://github.com/nautechsystems/nautilus_trader.git
cd nautilus_trader

Step 3: Check if the Python environment is set up#

Check if a virtual environment exists and nautilus_trader is installed:

bash

python -c "import nautilus_trader; print(nautilus_trader.__version__)" 2>/dev/null

If this succeeds, the environment is ready — proceed to the user's task.

Step 4: Set up the environment (only if Step 3 failed)#

NautilusTrader requires Python 3.12+ and the Rust toolchain. Install in this order:

4a. Install system prerequisites

bash

# macOS (Rust + clang are typically available, just ensure Rust is installed)
curl https://sh.rustup.rs -sSf | sh -s -- -y
source $HOME/.cargo/env

# Linux (Ubuntu)
curl https://sh.rustup.rs -sSf | sh -s -- -y
source $HOME/.cargo/env
sudo apt-get install -y clang

Verify: rustc --version and clang --version

4b. Install uv (if not already available)

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

4c. Install nautilus_trader

There are two installation approaches:

Option A: Install from PyPI (recommended for users who just want to USE the framework)

bash

uv venv --python 3.12
source .venv/bin/activate   # Linux/macOS
uv pip install nautilus_trader
uv pip install "nautilus_trader[visualization]"  # Optional: for tearsheet reports

Option B: Install from source (recommended when working inside the cloned repository)

bash

cd nautilus_trader
uv sync --all-extras

This creates a virtual environment, installs all dependencies, and builds the Cython/Rust extensions. It takes several minutes on first build.

For faster development iteration, use:

bash

make build-debug    # Debug build (faster compilation, slower runtime)
make install        # Release build (slower compilation, faster runtime)

4d. Set environment variables (source builds only, Linux/macOS)

bash

export PYO3_PYTHON=$(pwd)/.venv/bin/python

# Linux only:
export LD_LIBRARY_PATH="$(python -c 'import sys; print(sys.base_prefix)')/lib:$LD_LIBRARY_PATH"

4e. Verify installation

bash

python -c "import nautilus_trader; print(f'NautilusTrader {nautilus_trader.__version__} installed successfully')"

Optional dependencies#

ExtraInstall commandPurposeVisualizationuv pip install "nautilus_trader[visualization]"Plotly tearsheets and chartsInteractive Brokersuv pip install "nautilus_trader[ib]"IB adapter dependenciesDocker (for IB Gateway)uv pip install "nautilus_trader[docker]"Dockerized IB GatewayBetfairuv pip install "nautilus_trader[betfair]"Betfair adapterPolymarketuv pip install "nautilus_trader[polymarket]"Polymarket adapter

When to read which reference#

Based on what the user needs, read the appropriate reference file from the references/ directory next to this SKILL.md. Each reference file is self-contained with code templates and explanations.

User's goalReference file to readConvert CSV/external data into Nautilus formatreferences/data_conversion.mdWrite a trading strategyreferences/strategy_development.mdRun a backtest and generate reportsreferences/backtesting.mdRun paper/simulated trading with real market datareferences/paper_trading.mdConnect to a live exchange/broker and tradereferences/live_trading.md

Read only the reference file(s) relevant to the current task. If a task spans multiple areas (e.g., "convert data, write a strategy, and backtest it"), read them in the order listed above.

Project layout#

text

nautilus_trader/             # Python package (v1, production)
├── adapters/                # Venue adapters (Binance, Bybit, IB, etc.)
├── backtest/                # BacktestEngine, BacktestNode
├── examples/                # Example strategies and scripts
│   ├── strategies/          # EMACross, MarketMaker, etc.
│   └── algorithms/          # TWAP execution algorithm
├── indicators/              # Technical indicators (EMA, SMA, RSI, ATR, etc.)
├── live/                    # TradingNode for live/sandbox trading
├── model/                   # Domain types: instruments, orders, events, data
├── persistence/             # Data catalog (Parquet), wranglers
├── analysis/                # Reports, tearsheets, visualization
└── trading/                 # Strategy base class

examples/                    # Runnable example scripts
├── backtest/                # Backtest examples (FX, crypto, equities)
├── data_conversion/         # Data conversion examples
├── live/                    # Live trading examples per exchange
└── sandbox/                 # Sandbox (paper trading) examples

docs/concepts/               # Concept guides (data, strategies, backtesting, etc.)
docs/integrations/           # Per-exchange integration guides

Core concepts quick reference#

Data types#

NautilusTrader uses these built-in market data types (in descending order of granularity):

TypeDescriptionOrderBookDeltaIndividual order book updates (L1/L2/L3)OrderBookDepth10Aggregated order book snapshot (up to 10 levels per side)QuoteTickBest bid/ask prices with sizes (top-of-book)TradeTickA single executed tradeBarOHLCV candle aggregated by time, tick, volume, etc.

Instrument types#

TypeUse caseCurrencyPairForex, crypto spot (e.g., EUR/USD, BTC/USDT)CryptoPerpetualCrypto perpetual futures (e.g., BTCUSDT-PERP)EquityStocks (e.g., AAPL, TSLA)FuturesContractTraditional futures (e.g., ES, IF)OptionContractOptionsCfdCFDs

BarType string syntax#

Standard format: {instrument_id}-{step}-{aggregation}-{price_type}-{source}

Examples:

text

EUR/USD.SIM-1-MINUTE-BID-INTERNAL        # 1-min bars from bid quotes, aggregated internally
BTCUSDT-PERP.BINANCE-5-MINUTE-LAST-EXTERNAL  # 5-min bars from exchange
AAPL.XNAS-1-HOUR-LAST-INTERNAL           # 1-hour bars aggregated internally from trades

• Price types: BID, ASK, MID (from QuoteTick), LAST (from TradeTick)
• Sources: INTERNAL (Nautilus aggregates), EXTERNAL (exchange/provider provides)

Key identifiers#

• InstrumentId: e.g., "EUR/USD.SIM", "ETHUSDT-PERP.BINANCE", "AAPL.XNAS"
• Venue: e.g., "SIM", "BINANCE", "INTERACTIVE_BROKERS"
• TraderId: e.g., "TRADER-001"
• StrategyId: auto-generated as {ClassName}-{order_id_tag}

Environment contexts#

NautilusTrader has three operating modes:

ModeData sourceExecutionUse caseBacktestHistorical data filesSimulated exchangeStrategy researchSandboxLive market feedsSimulated locallyPaper tradingLiveLive market feedsReal exchangeProduction trading

The same strategy code runs in all three modes.

Installation#

bash

pip install nautilus_trader

# With visualization support (Plotly tearsheets)
pip install "nautilus_trader[visualization]"

For development in this repository:

bash

make install          # Release build
make build-debug      # Debug build (faster compilation)

Important conventions#

• Timestamps are UNIX nanoseconds ( ts_event, ts_init)
• Prices use fixed-point arithmetic ( Price, Quantity types) — never raw floats
• All imports come from the nautilus_trader package
• Strategy code is identical across backtest, sandbox, and live — only the engine config changes
• Do not block the event loop — strategy callbacks must return quickly
• One TradingNode per process — use separate processes for parallel live nodes

Key source files for reference#

When writing code, these files in the repository are the most useful references:

PurposePathEMA Cross strategy (simplest example)nautilus_trader/examples/strategies/ema_cross.pyQuickstart backtestdocs/getting_started/quickstart.pyLoading external CSV datadocs/how_to/loading_external_data.pyBacktest with ticksexamples/backtest/fx_ema_cross_audusd_ticks.pyBar-based backtestexamples/backtest/fx_ema_cross_bracket_gbpusd_bars_external.pySandbox exampleexamples/sandbox/binance_futures_testnet_sandbox.pyLive trading exampleexamples/live/binance/binance_spot_ema_cross_bracket_algo.pyData conversion (CN futures)examples/data_conversion/if_data_converter.pyStrategy concepts docdocs/concepts/strategies.mdData concepts docdocs/concepts/data.mdBacktesting concepts docdocs/concepts/backtesting.mdLive trading concepts docdocs/concepts/live.mdReports & analysis docdocs/concepts/reports.mdVisualization docdocs/concepts/visualization.mdIntegration guides (per exchange)docs/integrations/*.md

Typical end-to-end workflow#

1. Prepare data → Read references/data_conversion.md
   • Load raw CSV/API data → DataFrame → DataWrangler → Nautilus objects
   • Optionally persist to ParquetDataCatalog
2. Write strategy → Read references/strategy_development.md
   • Create StrategyConfig + Strategy subclass
   • Implement on_start, on_bar/ on_quote_tick, on_stop
3. Backtest → Read references/backtesting.md
   • Configure BacktestEngine or BacktestNode
   • Run and generate reports/tearsheets
4. Paper trade → Read references/paper_trading.md
   • Configure TradingNode with Sandbox execution client
   • Use live data feeds with simulated order execution
5. Go live → Read references/live_trading.md
   • Switch execution client from Sandbox to real exchange adapter
   • Configure reconciliation, risk management