Skip to content

Martingale42/nautilus-dev / skills/nt-trading

nt-trading

Verified

Use when working with strategy logic, order execution, risk management, position/portfolio tracking, or exec algorithms in NautilusTrader.

FileKindSize
SKILL.mdskill md18.0 KB
references/api/.gitkeepother0 B
references/api/accounting.mdmarkdown888 B
references/api/events.mdmarkdown543 B
references/api/execution.mdmarkdown1.3 KB
references/api/orders.mdmarkdown1.8 KB
references/api/portfolio.mdmarkdown380 B
references/api/position.mdmarkdown162 B
references/api/risk.mdmarkdown359 B
references/api/trading.mdmarkdown680 B
references/architecture_patterns.mdmarkdown16.2 KB
references/concepts/.gitkeepother0 B
references/concepts/actors.mdmarkdown14.9 KB
references/concepts/execution.mdmarkdown23.1 KB
references/concepts/orders.mdmarkdown42.6 KB
references/concepts/portfolio.mdmarkdown6.7 KB
references/concepts/positions.mdmarkdown17.2 KB
references/concepts/rust.mdmarkdown16.1 KB
references/concepts/strategies.mdmarkdown25.7 KB
references/examples/.gitkeepother0 B
references/examples/actor_data/README.mdmarkdown653 B
references/examples/actor_data/run_example.pyscript3.9 KB
references/examples/actor_data/strategy.pyscript5.6 KB
references/examples/actor_signals/README.mdmarkdown669 B
references/examples/actor_signals/run_example.pyscript3.9 KB
references/examples/actor_signals/strategy.pyscript4.8 KB
references/examples/crypto_ema_cross_ethusdt_trade_ticks.pyexecutablescript5.3 KB
references/examples/fx_ema_cross_audusd_bars_from_ticks.pyexecutablescript4.2 KB
references/examples/msgbus/README.mdmarkdown1.0 KB
references/examples/msgbus/run_example.pyscript3.9 KB
references/examples/msgbus/strategy.pyscript4.5 KB
references/examples/rust_trading/examples/actors/imbalance/actor.rsscript6.5 KB
references/examples/rust_trading/examples/actors/imbalance/config.rsscript2.8 KB
references/examples/rust_trading/examples/mod.rsscript963 B
references/examples/rust_trading/examples/strategies/ema_cross.rsscript4.9 KB
references/examples/rust_trading/examples/strategies/ema_cross/config.rsscript3.7 KB
references/examples/rust_trading/examples/strategies/ema_cross/strategy.rsscript4.6 KB
references/examples/rust_trading/examples/strategies/grid_mm.rsscript31.0 KB
references/examples/rust_trading/examples/strategies/grid_mm/config.rsscript6.9 KB
references/examples/rust_trading/examples/strategies/grid_mm/strategy.rsscript13.3 KB
references/examples/rust_trading/examples/strategies/mod.rsscript1.1 KB
references/guides/.gitkeepother0 B
references/guides/rust_patterns.mdmarkdown17.2 KB
references/guides/testing.mdmarkdown7.9 KB
references/guides/troubleshooting_rust.mdmarkdown12.3 KB
references/guides/write_rust_actor.mdmarkdown3.9 KB
references/guides/write_rust_strategy.mdmarkdown4.7 KB
templates/.gitkeepother0 B
templates/actor.pyscript2.1 KB
templates/exec_algorithm.pyscript2.4 KB
templates/strategy.pyscript3.8 KB
---
name: nt-trading
description: "Use when working with strategy logic, order execution, risk management, position/portfolio tracking, or exec algorithms in NautilusTrader."
---

# nt-trading

## What This Skill Covers

NautilusTrader **trading domain** — strategy logic, order execution, risk management, and portfolio/position tracking.

**Python modules**: `trading/`, `execution/`, `risk/`, `accounting/`, `portfolio/`
**Rust crates**: `nautilus_trading`, `nautilus_execution`, `nautilus_risk`, `nautilus_portfolio`

## When To Use

- Writing or modifying a `Strategy` or `Actor`
- Configuring order execution (order types, time-in-force, exec algorithms)
- Setting up risk management (risk engine config, margin models)
- Working with positions, portfolio queries, or accounting
- Building custom execution algorithms (`ExecAlgorithm`)
- Order lifecycle handling (`submit_order`, `cancel_order`, `modify_order`)

## When NOT To Use

- **Custom indicators or signal generation** → use `nt-signals`
- **Fill models or simulated exchange** → use `nt-backtest`
- **Adapter configuration** → use `nt-adapters`
- **Domain model types (instruments, identifiers)** → use `nt-model`
- **Data persistence or catalog** → use `nt-data`
- **Live node system setup** → use `nt-live`

## Python Usage

### Strategy

Subclass `Strategy` from `nautilus_trader.trading.strategy`:

```python
from nautilus_trader.trading.strategy import Strategy
from nautilus_trader.config import StrategyConfig

class MyStrategyConfig(StrategyConfig, frozen=True):
    instrument_id: str = None
    bar_type: str = None

class MyStrategy(Strategy):
    def __init__(self, config: MyStrategyConfig):
        super().__init__(config)
        # Store config, initialize state

    def on_start(self):
        # Subscribe to data, register indicators
        self.subscribe_bars(self.bar_type)

    def on_bar(self, bar):
        # Core trading logic
        pass

    def on_quote_tick(self, tick):
        pass

    def on_trade_tick(self, tick):
        pass

    def on_order_filled(self, event):
        # Post-fill logic
        pass

    def on_position_changed(self, event):
        pass

    def on_stop(self):
        # Cleanup
        pass
```

**Key order methods** (inherited from `Actor` → `Strategy`):
- `self.submit_order(order)` — submit to execution
- `self.cancel_order(order)` — cancel open order
- `self.modify_order(order, quantity=None, price=None, trigger_price=None)` — modify open order
- `self.cancel_all_orders(instrument_id)` — cancel all for instrument
- `self.close_position(position)` — close position with market order
- `self.close_all_positions(instrument_id)` — close all for instrument

**Order creation** (via `OrderFactory` on `self.order_factory`):
- `self.order_factory.market(instrument_id, side, quantity)`
- `self.order_factory.limit(instrument_id, side, quantity, price)`
- `self.order_factory.stop_market(instrument_id, side, quantity, trigger_price)`
- `self.order_factory.stop_limit(instrument_id, side, quantity, price, trigger_price)`
- `self.order_factory.trailing_stop_market(instrument_id, side, quantity, trailing_offset, ...)`

### Actor

Subclass `Actor` from `nautilus_trader.trading.actor` for non-trading components (data processing, signal publishing, monitoring):

```python
from nautilus_trader.trading.actor import Actor
from nautilus_trader.config import ActorConfig

class MyActor(Actor):
    def __init__(self, config: ActorConfig):
        super().__init__(config)

    def on_start(self):
        self.subscribe_data(...)

    def on_bar(self, bar):
        # Process data, publish signals via msgbus
        self.publish_signal(name="my_signal", value=signal_value)
```

### Risk & Execution Configuration

```python
from nautilus_trader.config import ExecEngineConfig, RiskEngineConfig

exec_config = ExecEngineConfig(
    load_cache=True,
    allow_cash_positions=True,
)

risk_config = RiskEngineConfig(
    bypass=False,
    max_order_submit_rate="100/00:00:01",  # 100 per second
    max_order_modify_rate="100/00:00:01",
    max_notional_per_order={"GBP/USD.SIM": 1_000_000},
)
```

## Python Extension

### Custom ExecAlgorithm

Subclass `ExecAlgorithm` from `nautilus_trader.execution.algorithm`:

```python
from nautilus_trader.execution.algorithm import ExecAlgorithm

class MyExecAlgorithm(ExecAlgorithm):
    def on_start(self):
        pass

    def on_order(self, order):
        # Custom execution logic — split, time-slice, etc.
        self.submit_order(order)

    def on_stop(self):
        pass
```

Register in config:
```python
exec_algorithms=[MyExecAlgorithm.fully_qualified_name()]
```

### Custom Margin/Position Sizing

Extend risk calculations by subclassing margin models or implementing custom position sizing logic in your Strategy.

## Rust Usage

NautilusTrader has a complete Rust implementation (v2 Rust) that runs without Python. Strategies and actors are written in pure Rust, compiled to standalone binaries.

### Rust Strategy

A strategy owns a `StrategyCore` and implements `DataActor` for data handling. The `nautilus_strategy!` macro wires up `Deref`/`DerefMut` and the `Strategy` trait.

```rust
use nautilus_common::actor::DataActor;
use nautilus_model::{
    data::QuoteTick,
    enums::OrderSide,
    identifiers::{InstrumentId, StrategyId},
    types::Quantity,
};
use nautilus_trading::{nautilus_strategy, strategy::{Strategy, StrategyConfig, StrategyCore}};

pub struct MyStrategy {
    core: StrategyCore,
    instrument_id: InstrumentId,
    trade_size: Quantity,
}

impl MyStrategy {
    pub fn new(instrument_id: InstrumentId) -> Self {
        let config = StrategyConfig {
            strategy_id: Some(StrategyId::from("MY_STRAT-001")),
            order_id_tag: Some("001".to_string()),
            ..Default::default()
        };
        Self {
            core: StrategyCore::new(config),
            instrument_id,
            trade_size: Quantity::from("1.0"),
        }
    }
}

// Generates Deref<Target = DataActorCore>, DerefMut, and Strategy trait impl
nautilus_strategy!(MyStrategy);

impl std::fmt::Debug for MyStrategy {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("MyStrategy").finish()
    }
}

impl DataActor for MyStrategy {
    fn on_start(&mut self) -> anyhow::Result<()> {
        self.subscribe_quotes(self.instrument_id, None, None);
        Ok(())
    }

    fn on_quote(&mut self, quote: &QuoteTick) -> anyhow::Result<()> {
        let order = self.core.order_factory().market(
            self.instrument_id,
            OrderSide::Buy,
            self.trade_size,
            None, None, None, None, None, None, None,
        );
        self.submit_order(order, None, None)?;
        Ok(())
    }
}
```

**Override Strategy hooks** (order/position event handlers) by passing a block to the macro. The block can override multiple handlers — keep heavy logic in methods on the impl block, not inside the macro:

```rust
use nautilus_model::events::{OrderRejected, OrderFilled, OrderCanceled};

nautilus_strategy!(MyStrategy, {
    fn on_order_rejected(&mut self, event: OrderRejected) {
        let reason = event.reason.to_string();
        if reason.contains("POST_ONLY") {
            log::info!("post-only reject (expected): {reason}");
        } else {
            log::warn!("order rejected: {reason}");
        }
    }

    fn on_order_filled(&mut self, event: OrderFilled) {
        if let Err(e) = self.handle_fill(&event) {
            log::error!("handle_fill failed: {e}");
        }
    }

    fn on_order_canceled(&mut self, event: OrderCanceled) {
        // ...
    }
});
```

Inside the block: `&mut self` and the event by value. Do not redefine
`core()` / `core_mut()` — the macro already generates them.

### Warmup pattern (`request_quotes` + `on_historical_*`)

When a strategy needs historical data before quoting (e.g. for indicator
seeding or calibration), use the request/historical-handler pair:

```rust
fn on_start(&mut self) -> anyhow::Result<()> {
    self.subscribe_quotes(self.cfg.instrument_id, None, None);
    self.subscribe_trades(self.cfg.instrument_id, None, None);

    let now_ns: u64 = self.core.clock().timestamp_ns().into();
    let start = UnixNanos::from(now_ns - 24 * 3_600_000_000_000); // 24h
    let end = UnixNanos::from(now_ns);

    self.warmup_quotes = Some(Vec::new());
    self.warmup_trades = Some(Vec::new());
    self.request_quotes(self.cfg.instrument_id, Some(start), Some(end), None, None, None)?;
    self.request_trades(self.cfg.instrument_id, Some(start), Some(end), None, None, None)?;
    Ok(())
}

fn on_historical_quotes(&mut self, quotes: &[QuoteTick]) -> anyhow::Result<()> {
    if let Some(buf) = self.warmup_quotes.as_mut() { buf.extend_from_slice(quotes); }
    self.maybe_run_warmup();
    Ok(())
}

fn on_historical_trades(&mut self, trades: &[TradeTick]) -> anyhow::Result<()> {
    if let Some(buf) = self.warmup_trades.as_mut() { buf.extend_from_slice(trades); }
    self.maybe_run_warmup();
    Ok(())
}
```

`maybe_run_warmup()` runs the seeding logic once both buffers have
arrived. **Backtest gotcha**: if the run starts at the catalog's earliest
data, `request_*` returns nothing — keep a rolling buffer in `on_quote` /
`on_trade` as a fallback.

### Daily timer for re-calibration

Use `clock().set_timer_ns()` to schedule a repeating timer at UTC
midnight (or any anchor). It fires deterministically in backtest:

```rust
pub const DAILY_TIMER: &str = "my_daily_timer";

fn on_start(&mut self) -> anyhow::Result<()> {
    let now_ns: u64 = self.core.clock().timestamp_ns().into();
    let next_midnight = next_utc_midnight_ns(now_ns);
    self.core.clock_mut().set_timer_ns(
        DAILY_TIMER,
        24 * 3_600_000_000_000,                  // interval
        UnixNanos::from(next_midnight),          // start
        None, None,                              // stop_time, callback
    )?;
    Ok(())
}

// Override on_time_event in DataActor impl, or in nautilus_strategy! block.
fn on_time_event(&mut self, event: &TimeEvent) -> anyhow::Result<()> {
    if event.name.as_str() == DAILY_TIMER {
        // run daily work
    }
    Ok(())
}
```

### Instrument resolution

Hardcoded `tick_size` / `size_precision` is a bug magnet — every
instrument differs. Resolve from the cache in `on_start`:

```rust
fn on_start(&mut self) -> anyhow::Result<()> {
    let inst = self.cache().instrument(&self.cfg.instrument_id)
        .ok_or_else(|| anyhow::anyhow!("instrument not in cache"))?;
    self.tick_size = inst.price_increment().as_f64();
    self.instrument = Some(inst.clone());
    Ok(())
}
```

In backtest: `add_instrument(...)` populates the cache. In live: the
adapter's `InstrumentProvider::initialize()` does it. Either way,
`on_start` is the right hook — it runs after both.

**Order creation** (via `self.core.order_factory()`):
- `market(instrument_id, side, quantity, ...)`
- `limit(instrument_id, side, quantity, price, ...)`
- `stop_market(instrument_id, side, quantity, trigger_price, ...)`
- `stop_limit(instrument_id, side, quantity, price, trigger_price, ...)`
- `market_if_touched(...)`, `limit_if_touched(...)`, `trailing_stop_market(...)`

**Order management** (via `Strategy` trait, available on `self`):

| Method | Action |
|---|---|
| `submit_order` | Submit a new order to the venue |
| `submit_order_list` | Submit a list of contingent orders |
| `modify_order` | Modify price, quantity, or trigger price |
| `cancel_order` | Cancel a specific order |
| `cancel_orders` | Cancel a filtered set of orders |
| `cancel_all_orders` | Cancel all orders for an instrument |
| `close_position` | Close a position with a market order |
| `close_all_positions` | Close all open positions |

### Rust Actor

An actor owns a `DataActorCore` and receives data/events without order management. The `nautilus_actor!` macro wires up `Deref`/`DerefMut`.

```rust
use nautilus_common::{nautilus_actor, actor::{DataActor, DataActorConfig, DataActorCore}};
use nautilus_model::{data::QuoteTick, identifiers::{ActorId, InstrumentId}};

pub struct SpreadMonitor {
    core: DataActorCore,
    instrument_id: InstrumentId,
}

impl SpreadMonitor {
    pub fn new(instrument_id: InstrumentId) -> Self {
        let config = DataActorConfig {
            actor_id: Some(ActorId::from("SPREAD_MON-001")),
            ..Default::default()
        };
        Self {
            core: DataActorCore::new(config),
            instrument_id,
        }
    }
}

nautilus_actor!(SpreadMonitor);

impl std::fmt::Debug for SpreadMonitor {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SpreadMonitor").finish()
    }
}

impl DataActor for SpreadMonitor {
    fn on_start(&mut self) -> anyhow::Result<()> {
        self.subscribe_quotes(self.instrument_id, None, None);
        Ok(())
    }

    fn on_quote(&mut self, quote: &QuoteTick) -> anyhow::Result<()> {
        let spread = quote.ask_price.as_f64() - quote.bid_price.as_f64();
        log::info!("Spread: {spread:.5}");
        Ok(())
    }
}
```

### DataActor Handler Table

All handlers have default no-op implementations. Override only what you need:

| Handler | Receives |
|---|---|
| `on_start` | Actor started |
| `on_stop` | Actor stopped |
| `on_quote` | `QuoteTick` |
| `on_trade` | `TradeTick` |
| `on_bar` | `Bar` |
| `on_book_deltas` | `OrderBookDeltas` |
| `on_book` | `OrderBook` (at interval) |
| `on_instrument` | `InstrumentAny` |
| `on_mark_price` | `MarkPriceUpdate` |
| `on_index_price` | `IndexPriceUpdate` |
| `on_funding_rate` | `FundingRateUpdate` |
| `on_option_greeks` | `OptionGreeks` |
| `on_option_chain` | `OptionChainSlice` |
| `on_instrument_status` | `InstrumentStatus` |
| `on_order_filled` | `OrderFilled` |
| `on_order_canceled` | `OrderCanceled` |
| `on_time_event` | `TimeEvent` |

### Running Rust Components

Three paths to run Rust strategies/actors:

1. **Pure Rust** — standalone binary, no Python runtime:
   ```rust
   let strategy = MyStrategy::new(instrument_id);
   node.add_strategy(strategy)?;
   node.run().await?;
   ```

2. **Native config from Python** — register built-in Rust strategies from Python:
   ```python
   from nautilus_trader.core.nautilus_pyo3.trading import GridMarketMakerConfig
   config = GridMarketMakerConfig(instrument_id=..., trade_size=...)
   node.add_native_strategy(config)
   ```

3. **Plugin loading** (planned) — load compiled `cdylib` crates at runtime.

### Guard Safety

When accessing other actors in callbacks:
- Look up actors by ID each time; do not cache an `ActorRef`
- Drop the guard before scope ends; never store in a field
- Never hold a guard across an `.await` point

## Rust Extension (PyO3 Path)

### Exposing Rust Strategies to Python

Use `#[pyclass]` configs with `add_native_strategy`/`add_native_actor` dispatch:

| Config | Strategy |
|---|---|
| `EmaCrossConfig` | `EmaCross` |
| `GridMarketMakerConfig` | `GridMarketMaker` |
| `DeltaNeutralVolConfig` | `DeltaNeutralVol` |

| Config | Actor |
|---|---|
| `BookImbalanceActorConfig` | `BookImbalanceActor` |

To add custom components to this path: add a `#[pyclass]` config and dispatch arm in `add_native_strategy` or `add_native_actor`.

### PyO3 Binding Conventions

- Use `#[pyclass]` and `#[pymethods]` for Python-visible types
- Register new modules in `crates/pyo3/src/lib.rs`
- Use `Python::attach(|py| { ... })` for callbacks that need the GIL
- Wrap FFI functions in `abort_on_panic(|| { ... })` — Rust panics must never unwind across FFI

## Key Conventions

### Order Lifecycle

Orders follow a strict state machine: `INITIALIZED → SUBMITTED → ACCEPTED → [PARTIALLY_FILLED] → FILLED | CANCELED | EXPIRED | REJECTED`. Never assume order state — always check via events.

### Position State

Positions transition: `OPENING → OPEN → CLOSING → CLOSED`. A position's `side` is determined by its net quantity. Hedge mode vs netting mode affects how fills create/modify positions.

### Live-Readiness Checklist

- Handle all order events (not just fills — also rejects, cancels, expirations)
- Implement `on_stop()` cleanup (cancel open orders, optionally close positions)
- Use `self.clock.timer_names` for timer management
- Check `self.portfolio.is_net_long()` / `is_net_short()` for position awareness
- Log state transitions at appropriate levels

### Testing

- Use `BacktestEngine` for strategy unit tests
- Verify order submission counts, fill events, position states
- Test edge cases: partial fills, rejects, disconnections
- See `references/guides/testing.md` for patterns

## References

- `references/concepts/` — strategies, actors, execution, orders, positions, portfolio, rust
- `references/api/` — trading, execution, risk, portfolio, accounting, orders, position, events
- `references/architecture_patterns.md` — **Cross-skill production reference**. Full strategy lifecycle (ingest → backtest → live), three-binary layout, onion architecture, atomic state, fail-fast philosophy. Load this first for any non-trivial Rust strategy work.
- `references/guides/` — testing patterns, write_rust_strategy, write_rust_actor, **rust_patterns** (architectural patterns from production Rust strategies), **troubleshooting_rust** (common Rust failure modes + diagnostic workflow)
- `references/examples/` — backtest examples (EMA cross, actor data/signals, msgbus), Rust strategies (ema_cross, grid_mm), Rust actors (imbalance)
- `templates/` — strategy.py, actor.py, exec_algorithm.py

### When to load which guide

- **Architectural decisions** (new strategy, refactor, lifecycle question) → `architecture_patterns.md` first.
- Building a new Rust strategy → `architecture_patterns.md` §10 build sequence, then `write_rust_strategy.md`, then `rust_patterns.md` for production patterns.
- Build/runtime errors, unexpected behavior → `troubleshooting_rust.md` (read the diagnostic workflow before guessing).
- Need to handle order events (rejects, fills, cancels) → `rust_patterns.md` §5 (override block).
- Need historical warmup or daily re-calibration → `rust_patterns.md` §2 and §3.
- Splitting a strategy into ingest / backtest / live binaries → `rust_patterns.md` §6 or `architecture_patterns.md` §1.
- Cross-skill troubleshooting (which skill / file owns this symptom) → `architecture_patterns.md` §8.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall