NautilusTrader
ConceptsOrders

Orders

NautilusTrader provides a common model for order types, execution instructions, and contingency relationships across trading venues.

Overview

All order types derive from two fundamentals: Market and Limit orders. Market orders seek immediate execution at the best available price. Non-marketable Limit orders rest in the order book at a specified price until matched, while marketable Limit orders can take liquidity.

NautilusTrader supports nine order types (the OrderType enum values), summarized under Order types with a dedicated guide for each.

NautilusTrader provides a unified API, but order and instruction support varies by venue and adapter. An adapter may deny an unsupported request before submission, or the venue may reject it. Check the target integration's capabilities before relying on an option.

Terminology

  • Aggressive: an order whose type is MARKET, or one that executes as a marketable order and takes liquidity.
  • Passive: an order that rests without taking liquidity.
  • Active local: an order that stays within the local system boundary at one of these non-terminal statuses:
    • INITIALIZED
    • EMULATED
    • RELEASED
  • In-flight: an order at one of the following statuses:
    • SUBMITTED
    • PENDING_UPDATE
    • PENDING_CANCEL
  • Open: an order at one of the following non-terminal statuses:
    • ACCEPTED
    • TRIGGERED
    • PENDING_UPDATE
    • PENDING_CANCEL
    • PARTIALLY_FILLED
  • Closed: an order at one of the following terminal statuses:
    • DENIED
    • REJECTED
    • CANCELED
    • EXPIRED
    • FILLED
    • VOIDED

Overlapping groups: open and closed are not opposites.

  • PENDING_UPDATE and PENDING_CANCEL are both open and in-flight: the order is working at the venue while a modify or cancel request is outstanding.
  • Four statuses are neither open nor closed: INITIALIZED, EMULATED, and RELEASED are active local, and SUBMITTED is in-flight until the venue acknowledges the order.

Open and closed are not complements

Test for a finished order with is_closed, never by negating is_open. An order at one of the four statuses above is not open, but it is not finished either. Each order is SUBMITTED immediately after submission, so code which treats "not open" as done abandons orders the venue is still processing. Use is_inflight for the awaiting-venue case.

Order state flow

Primary transitions: the diagram shows the order lifecycle and primary state transitions. Each status appears once, so PENDING_UPDATE and PENDING_CANCEL are drawn under In-Flight although they are also open.

The diagram shows the primary transitions, while the order model validates the complete transition set for recovery and venue edge cases. An order status describes local state, not the evidence that produced it. See Execution policies for command outcome classes, event provenance, delivery limits, and reconciliation policy.

Fills after expiry: fills still update the order and position.

  • A partial fill leaves the order EXPIRED.
  • A fill that completes its quantity changes it to FILLED.

If a fill arrives after the most recent expiry and the order is still EXPIRED or FILLED, Nautilus records the next OrderExpired. This event leaves the order's status and timestamps unchanged. The event stays in the order's history, and the execution engine publishes it to strategy handlers. Further expiry events are rejected until another fill arrives.

Order status definitions

StatusDescription
INITIALIZEDOrder is instantiated within the Nautilus system.
DENIEDOrder was denied by Nautilus for being invalid, unprocessable, or exceeding a risk limit.
EMULATEDOrder is being emulated by the OrderEmulator component.
RELEASEDOrder was released from the OrderEmulator component.
SUBMITTEDOrder was submitted to the venue (awaiting acknowledgement).
ACCEPTEDOrder was acknowledged by the venue as received and valid (may now be working).
REJECTEDOrder is terminal as rejected. reconciliation and reason provide the available provenance.
CANCELEDOrder is terminal as canceled. Status alone does not identify venue, local, or policy cause.
EXPIREDOrder reached its GTD expiration (terminal).
TRIGGEREDA stop-limit, trailing-stop-limit, or limit-if-touched order triggered on the venue.
PENDING_UPDATEOrder is pending a modification request on the venue.
PENDING_CANCELOrder is pending a cancellation request on the venue.
PARTIALLY_FILLEDOrder has been partially filled on the venue.
FILLEDOrder has been completely filled (terminal).
VOIDEDOrder is terminal after an authoritative fill correction.

Execution instructions

Execution instructions specify conditions and restrictions on how a venue processes an order. Support varies by venue and adapter.

Time in force

Time in force specifies how long an order stays active before any unfilled quantity is canceled.

  • GTC (Good Till Cancel): The order stays active until canceled by the trader or the venue.
  • IOC (Immediate or Cancel / Fill and Kill): The order executes immediately, with any unfilled portion canceled.
  • FOK (Fill or Kill): The order executes immediately in full or not at all.
  • GTD (Good Till Date): The order stays active until a specified expiration date and time.
  • DAY (Good for session/day): The order stays active until the end of the current trading session.
  • AT_THE_OPEN (OPG): The order is only active at the open of the trading session.
  • AT_THE_CLOSE: The order is only active at the close of the trading session.

Expire time

Use expire_time with GTD to specify when the order expires and leaves the venue's order book or order management system.

Post-only

An order marked post_only may provide liquidity but must not take it. A venue normally rejects or cancels the order if it would execute immediately. Market makers can use this instruction to target maker fees.

Reduce-only

An order marked reduce_only may reduce an existing position but must not increase exposure or open a position while flat. Exact behavior varies by venue.

Simulated reduce-only behavior: the Nautilus SimulatedExchange applies these rules.

  • It cancels the order when the associated position becomes flat.
  • It reduces the order quantity as the associated position shrinks.

Display quantity

The display_qty specifies how much of an order is visible on the limit order book. An order with a smaller displayed quantity than its total quantity is commonly called an iceberg order. A display quantity of zero makes the order hidden when the venue supports that behavior.

Trigger type

The trigger type, also known as a trigger method, specifies the market price used to trigger a conditional order.

An absent trigger type is represented by None and is invalid for an order that requires one.

  • DEFAULT: Uses the venue's default trigger type.
  • LAST_PRICE: Uses the last traded price.
  • BID_ASK: Uses the ask for BUY orders and the bid for SELL orders.
  • DOUBLE_LAST: Requires two consecutive matching last prices.
  • DOUBLE_BID_ASK: Requires two consecutive matching bid or ask prices, based on the order side.
  • LAST_OR_BID_ASK: Uses either the last price or the side-appropriate bid or ask.
  • MID_POINT: Uses the midpoint between the bid and ask.
  • MARK_PRICE: Uses the venue's mark price for the instrument.
  • INDEX_PRICE: Uses the venue's index price for the instrument.

Trailing offset type

The trailing offset type specifies how a trailing order calculates its trigger offset from the applicable market price.

An absent trailing offset type is represented by None and is invalid for a trailing order.

  • PRICE: Uses a price difference.
  • BASIS_POINTS: Uses a percentage difference in basis points, where 100 basis points equals 1%.
  • TICKS: Uses a number of ticks.
  • PRICE_TIER: Uses a venue-specific price tier.

Contingent orders

Contingency relationships can hold child orders until a parent activates or fills, cancel linked orders, or reduce their quantities. See Advanced orders for the available models and their constraints.

Order factory

Use the built-in OrderFactory to create orders. Each Python Strategy exposes one as self.order_factory. The Rust strategy API exposes it through self.order().

The factory assigns the trader and strategy IDs, and generates client order and initialization IDs when needed. It records the initial timestamp and applies defaults for the selected order type.

The examples in these guides create orders from a Strategy context.

See the OrderFactory API reference for further details.

Order types

NautilusTrader supports the following order types. Each links to a dedicated guide with a code example. Optional parameters are marked with a comment showing the default value.

Order typeCategoryDescription
MARKETAggressiveTrades the quantity immediately at the best available price.
LIMITPassiveRests in the book and trades only at the limit price or better.
STOP_MARKETConditionalOnce the trigger price is hit, places a Market order.
STOP_LIMITConditionalOnce the trigger price is hit, places a Limit order at the set price.
MARKET_TO_LIMITHybridSubmits as Market. Any remainder rests as a Limit at the fill price.
MARKET_IF_TOUCHEDConditionalOnce the trigger price is touched, places a Market order.
LIMIT_IF_TOUCHEDConditionalOnce the trigger price is touched, places a Limit order at the set price.
TRAILING_STOP_MARKETConditional trailingTrails the trigger by an offset, then places a Market order.
TRAILING_STOP_LIMITConditional trailingTrails the trigger by an offset, then places a Limit order.

FIX OrdType mapping

FIX mapping: each type maps to the nearest FIX 5.0 SP2 OrdType <40> value, where the protocol defines one.

Order typeFIX OrdType <40>
Market1 (Market)
Limit2 (Limit)
Stop-Market3 (Stop)
Stop-Limit4 (Stop Limit)
Market-To-LimitK (Market With Left Over as Limit)
Market-If-TouchedJ (Market If Touched)
Limit-If-Touchedno dedicated value †
Trailing-Stop-Market3 (Stop) + trailing peg
Trailing-Stop-Limit4 (Stop Limit) + trailing peg

† FIX defines no dedicated OrdType for Limit-If-Touched. It is commonly sent as 4 (Stop Limit) with a favorable trigger. Trailing stops likewise have no dedicated value and are modeled as 3/4 plus trailing peg fields.

Advanced orders

Orders can be grouped into lists and linked with contingency relationships (OTO, OCO, OUO), and bracket orders attach take-profit and stop-loss children to an entry. See the Advanced orders guide for order lists, contingency types, validation rules, and brackets.

Emulated orders

NautilusTrader can locally emulate order types that a venue does not natively support, using only MARKET and LIMIT orders for actual execution. See the Emulated orders guide for the emulation lifecycle, supported types, querying, and best practices.

  • Events - Order events, position events, and handler dispatch.
  • Execution - Order execution and fill handling.
  • Positions - Positions created from order fills.
  • Strategies - Order management from strategies.
Edit on GitHub

Execution Reconciliation

Execution reconciliation aligns the venue's actual order and position state with the system's internal event-sourced state. Use this guide to understand...

Advanced orders

Order lists group related orders, while contingency metadata describes how fills, cancellations, or updates should affect linked orders. The component that...

On this page

OrdersOverviewTerminologyOrder state flowOrder status definitionsExecution instructionsTime in forceExpire timePost-onlyReduce-onlyDisplay quantityTrigger typeTrailing offset typeContingent ordersOrder factoryOrder typesFIX OrdType mappingAdvanced ordersEmulated ordersRelated guides