Nautilus Trader

How to use the NautilusTrader algorithmic trading platform for data conversion, strategy development, backtesting, paper trading (sandbox), and live trading. Use this skill whenever the user wants to build or run a quantitative trading strategy with nautilus_trader, convert market data for backtesting, set up a backtest engine, run a sandbox/paper-trading session, connect to a live exchange or broker, or generate performance reports and tearsheets. Also use it when the user mentions NautilusTrader, trading strategies, backtesting frameworks, or connecting to exchanges like Binance, Bybit, Interactive Brokers, etc.

Audits

Pass

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install nautilus-trader-pro

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

Extra	Install command	Purpose
Visualization	`uv pip install "nautilus_trader[visualization]"`	Plotly tearsheets and charts
Interactive Brokers	`uv pip install "nautilus_trader[ib]"`	IB adapter dependencies
Docker (for IB Gateway)	`uv pip install "nautilus_trader[docker]"`	Dockerized IB Gateway
Betfair	`uv pip install "nautilus_trader[betfair]"`	Betfair adapter
Polymarket	`uv 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 goal	Reference file to read
Convert CSV/external data into Nautilus format	`references/data_conversion.md`
Write a trading strategy	`references/strategy_development.md`
Run a backtest and generate reports	`references/backtesting.md`
Run paper/simulated trading with real market data	`references/paper_trading.md`
Connect to a live exchange/broker and trade	`references/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

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

Type	Description
`OrderBookDelta`	Individual order book updates (L1/L2/L3)
`OrderBookDepth10`	Aggregated order book snapshot (up to 10 levels per side)
`QuoteTick`	Best bid/ask prices with sizes (top-of-book)
`TradeTick`	A single executed trade
`Bar`	OHLCV candle aggregated by time, tick, volume, etc.

Instrument types

Type	Use case
`CurrencyPair`	Forex, crypto spot (e.g., EUR/USD, BTC/USDT)
`CryptoPerpetual`	Crypto perpetual futures (e.g., BTCUSDT-PERP)
`Equity`	Stocks (e.g., AAPL, TSLA)
`FuturesContract`	Traditional futures (e.g., ES, IF)
`OptionContract`	Options
`Cfd`	CFDs

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:

Mode	Data source	Execution	Use case
Backtest	Historical data files	Simulated exchange	Strategy research
Sandbox	Live market feeds	Simulated locally	Paper trading
Live	Live market feeds	Real exchange	Production trading

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:

Purpose	Path
EMA Cross strategy (simplest example)	`nautilus_trader/examples/strategies/ema_cross.py`
Quickstart backtest	`docs/getting_started/quickstart.py`
Loading external CSV data	`docs/how_to/loading_external_data.py`
Backtest with ticks	`examples/backtest/fx_ema_cross_audusd_ticks.py`
Bar-based backtest	`examples/backtest/fx_ema_cross_bracket_gbpusd_bars_external.py`
Sandbox example	`examples/sandbox/binance_futures_testnet_sandbox.py`
Live trading example	`examples/live/binance/binance_spot_ema_cross_bracket_algo.py`
Data conversion (CN futures)	`examples/data_conversion/if_data_converter.py`
Strategy concepts doc	`docs/concepts/strategies.md`
Data concepts doc	`docs/concepts/data.md`
Backtesting concepts doc	`docs/concepts/backtesting.md`
Live trading concepts doc	`docs/concepts/live.md`
Reports & analysis doc	`docs/concepts/reports.md`
Visualization doc	`docs/concepts/visualization.md`
Integration guides (per exchange)	`docs/integrations/*.md`

Typical end-to-end workflow

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