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:

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:

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:

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

# 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)

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)

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)

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:

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)

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

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

Optional dependencies

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.

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

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):

Instrument types

BarType string syntax

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

Examples:

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:

The same strategy code runs in all three modes.

Installation

pip install nautilus_trader

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

For development in this repository:

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:

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