Order Book

NautilusTrader implements its order books in Rust. OrderBook maintains public market depth for an instrument. OwnOrderBook tracks your own orders separately so filtered views can subtract them from public liquidity.

Book types

OrderBook instances are maintained per instrument for both backtesting and live trading:

• L3_MBO: Level 3 market-by-order (MBO) data. Tracks every order at every price level, keyed by order ID. On each book side, an order ID maps to exactly one price level: re-adding an ID at a different price moves the order to the new level. MBP-style input uses a price-derived ID. A zero order ID likewise signals missing identity, except that top-of-book input uses the order side as its ID.
• L2_MBP: Level 2 market-by-price (MBP) data. Aggregates orders by price level (one entry per price).
• L1_MBP: Level 1 market-by-price (MBP) top-of-book data, also known as best bid and offer (BBO). Captures only the best prices.

Subscribing to book data

Strategies and actors subscribe to order book updates through the following methods. Subscriptions and handlers are part of the Python strategy/actor layer:

from nautilus_trader.model import BookType
from nautilus_trader.model import OrderBook
from nautilus_trader.model import OrderBookDeltas
from nautilus_trader.model import OrderBookDepth


# Incremental book deltas
self.subscribe_book_deltas(instrument_id, BookType.L2_MBP)

# Depth snapshots (adapter default; venue limits apply)
self.subscribe_book_depth(instrument_id, BookType.L2_MBP, managed=False)

# Full book snapshots at a timed interval
self.subscribe_book_at_interval(instrument_id, BookType.L2_MBP, interval_ms=1000)

Each subscription type delivers data to the corresponding handler:

def on_book_deltas(self, deltas: OrderBookDeltas) -> None: ...


def on_book_depth(self, depth: OrderBookDepth) -> None: ...


def on_book(self, order_book: OrderBook) -> None: ...

Managed books and shared subscriptions

The data engine maintains one cached OrderBook per instrument. A managed subscription selects its update source: OrderBookDeltas or OrderBookDepth. Delta and interval subscriptions can share a delta-managed book. A managed depth subscription cannot coexist with managed deltas or an interval subscription for the same instrument; the engine rejects the conflicting request.

To receive depth callbacks alongside managed deltas or interval books, set managed=False on the depth subscription, as shown above. Those callbacks do not update the cached book. With a depth-only subscription, use managed=True to maintain the cached book from depth snapshots.

Consumers sharing a source must agree on client, book type, depth, and subscription parameters. depth=None selects the adapter default; it does not match an explicit depth as a wildcard. Different clients may use different configurations when all consumers of that source are unmanaged. Unsubscribing one consumer preserves the source while other consumers still need it.

Interval delivery subscribes to deltas and publishes the cached book on a timer. OrderBookDepth events do not update that delta-managed book, including during backtests. For depth-only replay, use subscribe_book_depth and on_book_depth. To use interval delivery, supply OrderBookDeltas, converting depth snapshots to snapshot-flagged deltas before replay when needed. During a feed outage or recovery, the interval timer can continue publishing the last cached book.

Accessing the book

The OrderBook exposes top-of-book accessors:

let best_bid: Option<Price> = book.best_bid_price();
let best_ask: Option<Price> = book.best_ask_price();
let spread: Option<f64> = book.spread();
let midpoint: Option<f64> = book.midpoint();

Analysis methods

The OrderBook supports market depth analysis and execution simulation:

// Average fill price for a given quantity
let avg_fill_px = book.get_avg_px_for_quantity(quantity, OrderSide::Buy);

// Average price, filled quantity, and worst price for a target exposure
let (avg_px, filled_qty, worst_px) =
    book.get_avg_px_qty_for_exposure(target_exposure, OrderSide::Buy);

// Cumulative quantity available at or better than a price
let qty = book.get_quantity_for_price(price, OrderSide::Buy);

// Quantity at a specific price level only
let qty = book.get_quantity_at_level(price, OrderSide::Buy, 2);

// Simulate fills against the book
let fills: Vec<(Price, Quantity)> = book.simulate_fills(&order);

// All crossed levels regardless of order quantity
let levels = book.get_all_crossed_levels(OrderSide::Buy, price, 2);

Integrity checks

Call book_check_integrity to validate that the book state is consistent with its type:

• L1_MBP: No more than one level per side.
• L2_MBP: No more than one order per price level.
• L3_MBO: No additional per-level constraint; multiple orders may share a price.
• All types: Best bid must not exceed best ask (crossed book). Locked markets (bid == ask) are considered valid.

This is an explicit check: applying a delta does not call it. The Rust apply_delta and apply_deltas methods separately validate the incoming instrument ID against the book and return BookIntegrityError::InstrumentMismatch on mismatch.

For a nonzero order ID, a delta whose side is None first tries to resolve the side from the ladder cache. If no side is cached, an Add returns BookIntegrityError::NoOrderSide, while an Update or Delete is skipped. If the ID exists on both sides, an Add returns BookIntegrityError::AmbiguousOrderSide, while an Update or Delete is skipped with a warning.

Out-of-order deltas and depth snapshots are applied rather than rejected, so a venue that replays or reorders events still reaches the state those events describe. Only the book metadata is protected: ts_last never regresses, and sequence never regresses except across the full clears described below. A stale update logs one warning for each field that regressed, sequence and ts_event independently, and how often it logs depends on how the update arrives:

• Incremental deltas: Once per stale delta.
• Snapshot deltas: Once per snapshot, whether it arrives as an F_SNAPSHOT batch or as a single F_SNAPSHOT delta, since every delta in a rebuild shares the snapshot's sequence and timestamp.
• Depth snapshots: Once, since an OrderBookDepth replaces the book in a single update.

Some venue feeds restart their sequence counter when they clear the book. A full book clear without the F_SNAPSHOT flag is checked against the old sequence high-water, then the clear's sequence becomes the new high-water. Later deltas are compared from that value rather than from a value received before the clear. Snapshot-flagged clears preserve the current high-water. The public clear() method uses the new behavior, while clear_bids() and clear_asks() preserve the current high-water.

A snapshot report describes the incoming snapshot, so it does not depend on whether each of its deltas reaches the book. An L1_MBP book driven by quotes or trades is the exception to all of this: a stale QuoteTick or TradeTick is skipped with a warning and leaves the book unchanged.

Pretty printing

Both OrderBook and OwnOrderBook provide a pprint method that returns the book as a human-readable table:

println!("{}", book.pprint(5, None));
println!("{}", book.pprint(5, Some(Decimal::new(1, 2)))); // group_size = 0.01

The group_size parameter buckets price levels into coarser groups for instruments with fine tick sizes. The output is a formatted table with bids on the left, prices in the center, and asks on the right.

Own order book

The OwnOrderBook tracks your own working orders separately from the public book. Market making and other quoting strategies use it to estimate available liquidity at each price level after subtracting their own orders.

Execution engines maintain own books when manage_own_order_books is enabled. The cache updates an existing own book as order events change state. Eligible orders have a price, do not use IOC or FOK time in force, and are not held by the order emulator. Emulated orders never rest in the public book, so they join only when released. Quote-quantity orders join once an update converts their quantity to base units. Terminal events may still clean up an existing own book entry, even when the order would not otherwise be eligible for tracking.

Order lifecycle

The OwnOrderBook tracks orders through their lifecycle. Orders are added during submission or materialized from reconciliation. Orders sent to an external execution client join on their first order event. Nonterminal states such as OrderStatus::Accepted, OrderStatus::PendingUpdate, OrderStatus::PendingCancel, and OrderStatus::PartiallyFilled update the entry. The closed states OrderStatus::Denied, OrderStatus::Rejected, OrderStatus::Canceled, OrderStatus::Expired, OrderStatus::Filled, and OrderStatus::Voided remove it.

Each OwnBookOrder carries:

• trader_id: Trader ID that owns the order.
• client_order_id: Client order ID used to reconcile the own book with cache state.
• venue_order_id: Venue order ID when one has been assigned.
• side, price, and size: Order side, price, and remaining (leaves) quantity.
• order_type and time_in_force: Order metadata retained for inspection.
• status: Current order status, such as SUBMITTED, ACCEPTED, or PENDING_CANCEL.
• ts_last: Timestamp of the latest order event applied to this own-book order.
• ts_accepted: Timestamp when the venue accepted the order, or zero before acceptance.
• ts_submitted: Timestamp when the order was submitted, or zero before submission.
• ts_init: Timestamp when the order was initialized.

The status and ts_accepted fields drive the optional filters described in Status and time filtering.

Auditing

The audit_open_orders method reconciles an own book against a set of valid client order IDs. Any own-book order not in the provided set is removed with a warning. Cache::audit_own_order_books builds this set from open, in-flight, and active-local orders so non-terminal entries remain during normal event-processing and venue-latency windows. Live systems can run this audit periodically through the own-books audit interval.

Querying

// Check if a specific order is tracked
let in_book = own_book.is_order_in_book(&client_order_id);

// Get all tracked order IDs per side
let bid_ids = own_book.bid_client_order_ids();
let ask_ids = own_book.ask_client_order_ids();

// Aggregated quantities per price level
let bid_qty = own_book.bid_quantity(None, None, None, None, None);
let ask_qty = own_book.ask_quantity(None, None, None, None, None);

// Pretty print
println!("{}", own_book.pprint(5, None));

Filtered views

Subtract your own orders from the public book to see net available liquidity:

// Filtered maps of price -> quantity (own orders subtracted)
let net_bids = book.bids_filtered_as_map(Some(10), Some(&own_book), None, None, None);
let net_asks = book.asks_filtered_as_map(Some(10), Some(&own_book), None, None, None);

// Full filtered OrderBook with all analysis methods available
let filtered = book.filtered_view(Some(&own_book), Some(10), None, None, None);
let avg_px = filtered.get_avg_px_for_quantity(quantity, OrderSide::Buy);

The filtered_view method returns a new OrderBook with your own sizes subtracted, giving access to the full set of analysis methods (spread, midpoint, get_avg_px_for_quantity, etc.) on the net book.

Status and time filtering

Filtered views support optional status and time-based filtering for own orders:

let statuses = AHashSet::from([OrderStatus::Accepted]);

// Only subtract ACCEPTED orders (ignore SUBMITTED, PENDING_CANCEL, etc.)
let filtered = book.filtered_view(Some(&own_book), None, Some(&statuses), None, None);

The accepted_buffer_ns parameter provides a grace period. When ts_now is set, the view includes an own order only when ts_accepted + accepted_buffer_ns <= ts_now. This excludes recently accepted orders that may not yet appear in the public book feed. The time check applies regardless of order status, so combine it with a status filter to exclude non-accepted orders. Omitting ts_now disables acceptance-time filtering, and a positive accepted_buffer_ns requires ts_now.

// Only subtract orders accepted at least 500ms ago
let filtered = book.filtered_view(
    Some(&own_book),
    None,
    None,
    Some(500_000_000),
    Some(clock.timestamp_ns().as_u64()),
);

Binary markets

Binary markets can expose complementary outcome instruments, such as Polymarket YES and NO tokens. For a known complementary pair, the parity transform maps a price p on one outcome to 1 - p on the other. Under this transform, a NO bid at 0.40 becomes a YES ask at 0.60.

The OwnOrderBook::combined_with_opposite method handles this transformation, merging orders from both outcome instruments into a view for the first book:

let yes_own = own_yes_book
    .cloned()
    .unwrap_or_else(|| OwnOrderBook::new(yes_instrument_id));

let no_own = own_no_book
    .cloned()
    .unwrap_or_else(|| OwnOrderBook::new(no_instrument_id));

// Merge NO orders with the parity price transform (1 - price)
let combined = yes_own.combined_with_opposite(&no_own).unwrap();

// Filter the public YES book using the combined own book
let filtered = book.filtered_view(Some(&combined), None, None, None, None);

The transformation works as follows:

• NO asks at price p become bids at price 1 - p in the combined book.
• NO bids at price p become asks at price 1 - p in the combined book.