Rust edition: this page follows the live DeepWiki structure but treats the current Rust crates as implementation authority. Non-Rust surfaces are identified at their boundary and are not presented as Rust APIs.

Contingent Orders and Order Manager

Relevant Rust source files

• crates/execution/src/order_emulator/emulator.rs

Purpose and Scope

This page documents the contingent order system and the OrderManager component in NautilusTrader. Contingent orders are orders whose submission or cancellation depends on the state of other orders (e.g., bracket orders, OTO, OCO). The OrderManager coordinates order lifecycle events, manages command routing, and enforces contingency relationships.

Related pages:

• For basic order lifecycle management, see ExecutionEngine Architecture (5.1)
• For order emulation and local trigger logic, see OrderEmulator and Complex Orders (5.3)
• For high-level execution algorithms, see Execution Algorithms (5.4)

---

Contingent Order Fundamentals

Contingent orders are orders that have functional relationships with other orders. NautilusTrader supports primary contingency types defined in the ContingencyType enum:

ContingencyType	Behavior
OTO	One-Triggers-Other: Child orders are only submitted after the parent order fills.
OCO	One-Cancels-Other: When one order in a group fills, all other orders in the group are canceled.
OUO	One-Updates-Other: When one order fills, other orders in the group are modified.

---

ContingencyType Details

One-Triggers-Other (OTO)

OTO orders remain dormant until their parent order executes. This is commonly used for profit targets and stop losses that should only activate after an entry order fills.

Processing logic:

• Child orders are held locally and not submitted to the venue initially.
• The OrderManager caches the SubmitOrder commands for these child orders.
• When the parent fills, child orders are released for submission.
• The OrderManager tracks target quantities for OTO release using internal state mappings.

One-Cancels-Other (OCO)

OCO groups allow only one order in the group to fill. Once any order executes, all others are canceled.

Processing logic:

• All orders in the group are submitted simultaneously or held in emulation.
• The first fill triggers the cancellation of remaining orders via CancelOrder commands.
• The OrderEmulator handles OCO logic during its matching cycle, coordinating with the OrderManager

---

OrderManager Architecture

The OrderManager component coordinates order lifecycle management, enforces contingency relationships, and routes commands to appropriate handlers. It is utilized by both the ExecutionEngine and the OrderEmulator.

OrderManager Modes

The diagram below shows how OrderManager associates system names with code entities during initialization within the OrderEmulator.

Code_Entity_Space

OrderEmulator_Context

initializes

executes

calls

impl

OrderEmulator

OrderManager

OrderManagerAction

OrderManager (Rust)

_submit_order_commands

_oto_target_quantities

cache_submit_order_command

OrderManager Initialization: The OrderManager is initialized with a reference to the system clock and cache. In the OrderEmulator, it is created with active_local=true to handle local order triggers

Key Responsibilities

1. Command Caching: Stores SubmitOrder commands for orders waiting on contingency conditions
2. OTO Quantity Tracking: Tracks target quantities for OTO orders to ensure correct release upon partial fills.
3. Command Retrieval: Provides methods to retrieve or remove cached commands once conditions are met.
4. State Management: Handles resets to clear stateful values like cached commands and OTO quantities during system restarts or strategy reloads.

---

Order Lists and Batching

An OrderList groups multiple orders together with a shared OrderListId. This is the primary mechanism for submitting complex contingent structures (like brackets) as a single atomic batch.

OrderList Implementation

The OrderList is a container for a group of related orders. It is frequently used in SubmitOrderList commands

OrderList groups a list identity, instrument, strategy, and ordered client-order identifiers so contingent behavior can be audited and managed as one intent.

Submission and Validation

• Validation: The system ensures the list is not empty and contains no duplicate ClientOrderIds before processing.
• Batch Submission: Strategies send a group of orders to the execution engine via SubmitOrderList
• Venue Consistency: Execution clients generally require that all orders in an OrderList share the same venue for routing

---

Contingent Order Processing Flow

Submission Flow in OrderEmulator

The OrderEmulator uses its OrderManager to process incoming commands. When a SubmitOrder command arrives, it is routed through the manager to check for contingencies before being added to the matching core.

Order emulation asks OrderManager for OTO/OCO/OUO actions, caches the originating command, and releases, updates or cancels linked orders through the same canonical command path.

---

Strategy Integration

Strategies manage contingent orders by constructing relationships between parent and child orders using OrderList.

Bracket Order Pattern

1. Create a primary order (e.g., LimitOrder) to act as the entry.
2. Create secondary orders (e.g., LimitOrder for profit target and StopMarketOrder for stop loss).
3. Assign the primary order's ID as the parent_order_id for the secondary orders.
4. Set contingency_type to ContingencyType::OTO for the children.
5. Combine all orders into an OrderList and submit via SubmitOrderList.

Order Lifecycle Events

The ExecutionEngine and OrderEmulator publish events such as OrderAccepted, OrderFilled, and OrderCanceled The OrderManager listens for these events to trigger the release of OTO children or the cancellation of OCO siblings