NautilusTrader

https://nautilustrader.io/docs/latest
Admin
NautilusTrader is an open-source, high-performance, production-grade algorithmic trading platform...
Tokens:748,146
Snippets:5,429
Trust Score:7.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick setup for Linux or macOS

Source: https://nautilustrader.io/docs/latest/developer_guide/environment_setup

Clones the repository, installs Rust and uv, installs project tools, syncs dependencies, and builds a debug version. Sets environment variables for Python and Linux library paths.

```bash
git clone --branch develop https://github.com/nautechsystems/nautilus_trader
cd nautilus_trader

curl https://sh.rustup.rs -sSf | sh
source "$HOME/.cargo/env"

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

cargo install cargo-binstall --locked
make install-tools
./scripts/install-capnp.sh

make sync
source python/.venv/bin/activate

export PYO3_PYTHON="$PWD/python/.venv/bin/python"

if [ "$(uname -s)" = "Linux" ]; then
  PYTHON_LIB_DIR="$("$PYO3_PYTHON" -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))')"
  export LD_LIBRARY_PATH="$PYTHON_LIB_DIR${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
fi

export PYTHONHOME="$("$PYO3_PYTHON" -c 'import sys; print(sys.base_prefix)')"

prek install
make build-debug
```

--------------------------------

### Run the Kraken Hurst-VPIN live example

Source: https://nautilustrader.io/docs/latest/tutorials/hurst_vpin_kraken

Run the live example with cargo. The example trades Kraken Futures production with real funds by default, reading KRAKEN_FUTURES_API_KEY and KRAKEN_FUTURES_API_SECRET. To paper trade on demo, edit the example file to pass true as the demo argument and set environment to KrakenEnvironment::Demo.

```bash
cargo run -p nautilus-kraken --features examples \
  --example kraken-hurst-vpin-live
```

--------------------------------

### Backtest setup with BacktestEngine and reports

Source: https://nautilustrader.io/docs/latest/tutorials/gold_book_imbalance_ax

Configures a BacktestEngine with a netting margin venue, MakerTakerFeeModel, and runs a strategy over quotes. After run(), generate account, fills, and positions reports, then reset and dispose the engine. The runnable example is architect_ax_book_imbalance.py.

```python
from decimal import Decimal

from nautilus_trader.common import LogLevel
from nautilus_trader.backtest import BacktestEngine
from nautilus_trader.config import BacktestEngineConfig
from nautilus_trader.config import LoggerConfig
from nautilus_trader.execution import MakerTakerFeeModel
from nautilus_trader.model import AccountType
from nautilus_trader.model import Money
from nautilus_trader.model import OmsType
from nautilus_trader.model import TraderId
from nautilus_trader.model import Venue

engine = BacktestEngine(
    BacktestEngineConfig(
        trader_id=TraderId.from_str("BACKTESTER-001"),
        logging=LoggerConfig(stdout_level=LogLevel.INFO),
    ),
)

AX = Venue("AX")
engine.add_venue(
    venue=AX,
    oms_type=OmsType.NETTING,
    account_type=AccountType.MARGIN,
    base_currency=USD,
    starting_balances=[Money.from_str("100000 USD")],
    fee_model=MakerTakerFeeModel(
        maker_rate=Decimal("0.0002"),
        taker_rate=Decimal("0.0005"),
    ),
)

engine.add_instrument(XAU_PERP)
engine.add_data(quotes)
engine.add_strategy(strategy)
engine.run()
```

```python
print(engine.generate_account_report(venue=AX))
print(engine.generate_order_fills_report())
print(engine.generate_positions_report())

engine.reset()
engine.dispose()
```

--------------------------------

### Run Bybit options examples

Source: https://nautilustrader.io/docs/latest/tutorials/options_data_bybit

Commands to run the two example binaries. Stop either example with Ctrl+C; the actor's on_stop callback unsubscribes from all streams before shutdown.

```bash
# Per-instrument Greeks
cargo run --example bybit-greeks-tester --package nautilus-bybit --features examples

# Option chain snapshots
cargo run --example bybit-option-chain --package nautilus-bybit --features examples
```

--------------------------------

### Set up Tokio runtime for LiveNode::run()

Source: https://nautilustrader.io/docs/latest/how_to/run_rust_live_trading

Shows the required Tokio runtime setup for LiveNode::run(), which is async. The example loads a .env file with dotenvy and calls node.run().await? inside a #[tokio::main] async main function.

```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv().ok();

    // ... node setup ...

    node.run().await?;
    Ok(())
}
```

--------------------------------

### Run BacktestEngine example (engine-ema-cross)

Source: https://nautilustrader.io/docs/latest/concepts/rust

Runs the low-level BacktestEngine example for an EMA cross strategy. Requires the 'examples' feature on nautilus-backtest.

```bash
cargo run -p nautilus-backtest --features examples --example engine-ema-cross
```

--------------------------------

### Copy and run the Lighter Rust data client quickstart

Source: https://nautilustrader.io/docs/latest/how_to/get_started_lighter

Copies the quickstart into your workspace, changes into it, and runs it. This builds a LiveNode, registers the Lighter data client, adds a DataTester, and connects to testnet public streams. Stop it with Ctrl+C.

```bash
cp -R examples/quickstarts/lighter-rust-data-client ~/lighter-rust-data-client
cd ~/lighter-rust-data-client
cargo run
```

--------------------------------

### Install NautilusTrader stable 1.x with uv

Source: https://nautilustrader.io/docs/latest/getting_started/installation

Installs the latest stable 1.x release of NautilusTrader. A 1.x install cannot run the examples on these pages; see Migrate from v1 to v2 for API differences.

```bash
uv pip install nautilus_trader
```

--------------------------------

### Check installed NautilusTrader version

Source: https://nautilustrader.io/docs/latest/getting_started/installation

Check the installed NautilusTrader version. A version starting with '1.' means the resolver picked the stable line.

```bash
python -c "import nautilus_trader; print(nautilus_trader.__version__)"
```

--------------------------------

### Build and run bybit-delta-neutral example

Source: https://nautilustrader.io/docs/latest/tutorials/delta_neutral_options_bybit

Commands to build the example binary and run it for 30 seconds against Bybit mainnet. The log is saved to /tmp/bybit_dn.log. Requires building NautilusTrader from source.

```bash
make sync

cargo build --release --example bybit-delta-neutral --package nautilus-bybit --features examples
timeout 30 ./target/release/examples/bybit-delta-neutral > /tmp/bybit_dn.log 2>&1
```

--------------------------------

### Configure automatic purging with LiveExecutionEngineConfig

Source: https://nautilustrader.io/docs/latest/concepts/cache

Configure automatic bulk purges in live trading. All purge intervals default to `None`, which disables the corresponding loop. Set an interval to enable a loop and set its buffer or lookback to control how recent entries remain protected. This example uses the recommended starting values from the live-trading configuration guide.

```python
from nautilus_trader.config import LiveExecutionEngineConfig

exec_engine = LiveExecutionEngineConfig(
    purge_closed_orders_interval_mins=15,
    purge_closed_orders_buffer_mins=60,
    purge_closed_positions_interval_mins=15,
    purge_closed_positions_buffer_mins=60,
    purge_account_events_interval_mins=15,
    purge_account_events_lookback_mins=60,
)
```

--------------------------------

### Verify Cap'n Proto Version

Source: https://nautilustrader.io/docs/latest/developer_guide/environment_setup

Verifies the installed Cap'n Proto version matches the shared catalog. If Homebrew or Chocolatey provides an older version, install from source or see the Cap'n Proto installation guide.

```bash
capnp --version
```

--------------------------------

### Backtest setup for BBMeanReversion on AX

Source: https://nautilustrader.io/docs/latest/tutorials/fx_mean_reversion_ax

Imports required modules, creates a BacktestEngine with a netting OMS and margin account, adds the AX venue with a MakerTakerFeeModel, adds instrument and data, configures the BBMeanReversion strategy with parameters from the configuration table, and runs the backtest.

```python
import sys
from decimal import Decimal
from pathlib import Path

from nautilus_trader.backtest import BacktestEngine
from nautilus_trader.common import LogLevel
from nautilus_trader.config import BacktestEngineConfig
from nautilus_trader.config import LoggerConfig
from nautilus_trader.execution import MakerTakerFeeModel
from nautilus_trader.model import AccountType
from nautilus_trader.model import BarType
from nautilus_trader.model import Money
from nautilus_trader.model import OmsType
from nautilus_trader.model import TraderId
from nautilus_trader.model import Venue

sys.path.insert(0, str(Path("examples/live/architect_ax")))

from strategies import BBMeanReversion
from strategies import BBMeanReversionConfig

engine = BacktestEngine(
    BacktestEngineConfig(
        trader_id=TraderId.from_str("BACKTESTER-001"),
        logging=LoggerConfig(stdout_level=LogLevel.INFO),
    ),
)

AX = Venue("AX")
engine.add_venue(
    venue=AX,
    oms_type=OmsType.NETTING,
    account_type=AccountType.MARGIN,
    base_currency=USD,
    starting_balances=[Money.from_str("100000 USD")],
    fee_model=MakerTakerFeeModel(
        maker_rate=Decimal("0.0002"),
        taker_rate=Decimal("0.0005"),
    ),
)

engine.add_instrument(EURUSD_PERP)
engine.add_data(ticks)

strategy = BBMeanReversion(
    config=BBMeanReversionConfig(
        instrument_id=instrument_id,
        bar_type=BarType.from_str("EURUSD-PERP.AX-1-MINUTE-MID-INTERNAL"),
        trade_size=Decimal("1"),
        bb_period=20,
        bb_std=2.0,
        rsi_period=14,
        rsi_buy_threshold=30.0,
        rsi_sell_threshold=70.0,
    ),
)
engine.add_strategy(strategy)
engine.run()
```

--------------------------------

### Sync dependencies with make sync

Source: https://nautilustrader.io/docs/latest/developer_guide/environment_setup

Syncs development and test dependencies from the repository root after following the installation guide.

```bash
make sync
```

--------------------------------

### Run Python example with uv

Source: https://nautilustrader.io/docs/latest/getting_started/installation

Runs a Python example with the project environment. Connects to Lighter Testnet and streams market data; stop with Ctrl+C.

```bash
uv run --project python --no-sync python examples/live/lighter/data_tester.py
```

--------------------------------

### Documentation examples fail to import errors

Source: https://nautilustrader.io/docs/latest/getting_started/installation

Error messages that occur when running 2.x documentation against a 1.x install. These indicate a version mismatch.

```text
ImportError: cannot import name 'OrderSide' from 'nautilus_trader.model'
ImportError: cannot import name 'BacktestEngine' from 'nautilus_trader.backtest'
TypeError: Struct types cannot define __init__
```

--------------------------------

### Run the backtest example binary

Source: https://nautilustrader.io/docs/latest/tutorials/hurst_vpin_kraken

Runs the pre-built example binary for the Hurst-VPIN backtest on Kraken data. It reads the default CSV files from /tmp/tardis_kraken/ and logs the output to /tmp/backtest.log.

```bash
make sync

RUST_LOG=info cargo run -p nautilus-kraken --features examples \
    --example kraken-hurst-vpin-backtest --release > /tmp/backtest.log 2>&1

BACKTEST_LOG=/tmp/backtest.log \
    uv run --project python --no-sync \
        python docs/tutorials/assets/hurst_vpin_kraken/render_panels.py
```

--------------------------------

### Run Betfair Backtest Example

Source: https://nautilustrader.io/docs/latest/tutorials/backtest_book_imbalance_betfair

Commands to run the Betfair backtest example. Use the debug build for development, the release build for performance, and specify a custom data file or use the shipped sample file.

```bash
# Debug build
cargo run -p nautilus-betfair --features examples --example betfair-backtest

# Release build (recommended)
cargo run -p nautilus-betfair --features examples --release --example betfair-backtest

# Custom data file
cargo run -p nautilus-betfair --features examples --release --example betfair-backtest -- path/to/file.gz

# Shipped sample file
cargo run -p nautilus-betfair --features examples --release --example betfair-backtest -- test_data/betfair/1-166811431.bz2
```

--------------------------------

### Reinstall with --pre for 2.x

Source: https://nautilustrader.io/docs/latest/getting_started/installation

Reinstall NautilusTrader with the --pre flag to get the 2.x pre-release version when the stable 1.x line was installed.

```bash
uv pip install -U --pre nautilus_trader
```

--------------------------------

### Retrieve instrument from cache

Source: https://nautilustrader.io/docs/latest/concepts/instruments

Retrieves an instrument from the central cache using an InstrumentId. The example creates an InstrumentId from a string and calls cache.instrument() to get the instrument object.

```rust
use nautilus_model::identifiers::InstrumentId;

let instrument_id = InstrumentId::from("ETHUSDT-PERP.BINANCE");
let instrument = cache.instrument(&instrument_id);
```

--------------------------------

### Install and verify adapter wheel in fresh environment

Source: https://nautilustrader.io/docs/latest/developer_guide/python_adapters

Creates a fresh virtual environment, installs the adapter wheel and a standard non-editable NautilusTrader wheel using absolute paths, then runs a verifier script. On Windows, use the virtual environment's Scripts/python.exe path.

```bash
python -m venv /tmp/adapter-check
/tmp/adapter-check/bin/python -m pip install /absolute/path/nautilus_trader.whl /absolute/path/adapter.whl
/tmp/adapter-check/bin/python -I /absolute/path/verify_adapter.py
```

--------------------------------

### Configure BacktestEngine with CASH account

Source: https://nautilustrader.io/docs/latest/concepts/backtesting/accounts-and-margin

Low-level API example using BacktestEngine to add a venue with CASH account type and MakerTakerFeeModel. Starting balances are specified as Money objects.

```python
from decimal import Decimal

from nautilus_trader.backtest import BacktestEngine
from nautilus_trader.config import BacktestEngineConfig
from nautilus_trader.execution import MakerTakerFeeModel
from nautilus_trader.model import AccountType
from nautilus_trader.model import Money
from nautilus_trader.model import OmsType
from nautilus_trader.model import Venue

engine = BacktestEngine(BacktestEngineConfig())
engine.add_venue(
    venue=Venue("BINANCE"),
    oms_type=OmsType.NETTING,
    account_type=AccountType.CASH,
    starting_balances=[Money.from_str("10_000 USDT")],
    fee_model=MakerTakerFeeModel(
        maker_rate=Decimal("0.001"),
        taker_rate=Decimal("0.001"),
    ),
)
```

--------------------------------

### Configure BacktestVenueConfig with MARGIN account and StandardMarginModel

Source: https://nautilustrader.io/docs/latest/concepts/backtesting/accounts-and-margin

High-level API example using BacktestVenueConfig with MARGIN account type and StandardMarginModel to reserve fixed margin percentages. Starting balances are strings.

```python
from decimal import Decimal

from nautilus_trader.config import BacktestVenueConfig
from nautilus_trader.execution import MakerTakerFeeModel
from nautilus_trader.model import AccountType
from nautilus_trader.model import BookType
from nautilus_trader.model import OmsType
from nautilus_trader.model import StandardMarginModel

venue = BacktestVenueConfig(
    name="SIM",
    oms_type=OmsType.NETTING,
    account_type=AccountType.MARGIN,
    book_type=BookType.L1_MBP,
    starting_balances=["1_000_000 USD"],
    margin_model=StandardMarginModel(),
    fee_model=MakerTakerFeeModel(
        maker_rate=Decimal("0"),
        taker_rate=Decimal("0"),
    ),
)
```

--------------------------------

### Initialize development services

Source: https://nautilustrader.io/docs/latest/developer_guide/environment_setup

Starts PostgreSQL, Redis, and pgAdmin containers and initializes the NautilusTrader database schema. Run from the repository root.

```bash
make init-services
```
Tokens:
Raw