Execution

NautilusTrader coordinates order submission, risk checks, venue execution, reconciliation, and position updates across multiple strategies and venues. This page explains the components and message flows that support execution.

Use the execution guides according to the question you need to answer:

The main execution-related components include:

• Strategy
• ExecutionAlgorithm
• OrderEmulator
• RiskEngine
• ExecutionEngine
• ExecutionClient

Execution flow

A Strategy builds on data actor capabilities and adds methods for managing orders and execution:

• submit_order(...)
• submit_order_list(...)
• modify_order(...)
• cancel_order(...)
• cancel_orders(...)
• cancel_all_orders(...)
• close_position(...)
• close_all_positions(...)
• query_account(...)
• query_order(...)

These methods send point-to-point execution commands over the message bus. Order creation also publishes events such as OrderInitialized.

Commands follow different routes:

• submit_order(...) routes to OrderEmulator for emulated orders, to an ExecutionAlgorithm when exec_algorithm_id is set, and to the RiskEngine otherwise.
• submit_order_list(...) follows the same branching behavior based on emulation and exec_algorithm_id.
• modify_order(...) routes to the OrderEmulator for emulated orders, to an ExecutionAlgorithm when the order has an exec_algorithm_id and is still active within the local system, and to the RiskEngine otherwise.
• Cancel and query commands can route directly to the OrderEmulator, ExecutionAlgorithm, or ExecutionEngine, depending on the command and order state.

New orders typically enter one of these paths:

Strategy -> OrderEmulator or ExecutionAlgorithm or RiskEngine

The downstream flow is:

OrderEmulator -> ExecutionAlgorithm or ExecutionEngine

ExecutionAlgorithm -> RiskEngine -> ExecutionEngine -> ExecutionClient

Execution paths branch by emulation and algorithm routing before reaching the execution engine and client.

Order management system (OMS)

An order management system (OMS) type determines how orders map to positions for an instrument. Strategies and venues, whether simulated or live, each use an OMS type defined by the OmsType enum.

The OmsType enum has three variants:

• UNSPECIFIED: The strategy uses the venue's OMS type.
• NETTING: Positions combine into one position per instrument and strategy.
• HEDGING: Multiple positions per instrument and strategy can remain open.

When the strategy and venue OMS types differ, the ExecutionEngine assigns or overrides position_id values on OrderFilled events. A virtual position exists in NautilusTrader but not as a separate venue position.

If a fill resolves to a cached position for a different instrument, the ExecutionEngine logs an error and drops the fill. The order remains non-terminal so a subsequent valid fill can be applied.

OMS configuration

When a strategy omits oms_type or uses UNSPECIFIED, the ExecutionEngine follows the venue's OMS type without overriding venue position_id values. Configure a backtest venue with the OMS type used by the venue being modeled.

Venue position modes may require adapter-specific configuration. For example, see Binance Futures hedge mode.

Custom position IDs and NETTING

Custom position IDs are only valid under HEDGING OMS. NETTING has one position per instrument and strategy, with a deterministic ID of the form {instrument_id}-{strategy_id}.

The ExecutionEngine enforces this at submit time. If the effective OMS resolves to NETTING and submit_order (or submit_order_list) is called with a position_id that does not match {instrument_id}-{strategy_id}, the order is denied with an OrderDenied event explaining the mismatch.

This rule still permits the common closing idiom: Strategy.close_position(position) forwards position.id, which under NETTING is exactly the deterministic ID, so it is accepted. To label or partition positions with arbitrary IDs, configure the strategy with oms_type=HEDGING.

For submit_order_list, the engine additionally denies any mixed-instrument list when a position_id is supplied, regardless of OMS. A position belongs to a single instrument, so the combination is rejected with an explicit OrderDenied reason. See Order lists for the broader set of mixed-instrument caveats.

Position replay across NETTING cycles

Under NETTING the engine reuses one position ID across close and reopen cycles, so a position's replay log can accumulate every fill ever applied to that ID. The ExecutionEngineConfig.carry_replay_events_on_reopen option controls whether that log survives a reopen:

Live trading pins the option True: LiveExecutionEngineConfig always carries the replay log, so a venue OrderFillVoided referencing an earlier cycle still resolves. The simulated venue never emits fill voids, so backtests take the bounded default. Enable it explicitly for a custom or external execution client that can correct a fill from a prior cycle; without the carried log the engine finds no matching position fragment and rejects the correction.

Realized-PnL snapshots follow the correction. A fill void that reaches an earlier cycle rebuilds the position across the cycle boundary, moving the boundaries its archived snapshots describe, so the engine settles those snapshots into the corrected history's own closed cycles and realized PnL counts each cycle once. A void confined to the current cycle leaves the archive intact. See Position snapshotting.

Risk engine

The RiskEngine is a component of every Nautilus system, including backtest, sandbox, and live environments. It sits on the submit and modify path, and it also receives order events such as OrderReleased from the OrderEmulator. Cancel and query commands route directly to other execution components and do not pass through the RiskEngine.

Unless bypassed in RiskEngineConfig, the engine validates:

• Price and trigger-price precision for the instrument.
• Positive prices, unless the instrument allows negative prices (options, futures spreads, option spreads, and spot commodities).
• Quantity precision and base-quantity minimum and maximum bounds.
• GTD orders have not already expired.
• reduce_only orders do not increase the referenced position.
• Engine-level max_notional_per_order limits and the instrument's min_notional and max_notional fields.
• Cash-account balance impact for non-margin accounts.
• Submit and modify rate limits.
• Trading-state restrictions (ACTIVE, HALTED, REDUCING).

If a submit-time risk check fails, the system generates an OrderDenied event with a standardized reason code. If a modify-time risk check fails, it generates an OrderModifyRejected event.

Whole-position conditional exits

Some execution clients support conditional exits whose venue determines the closing quantity from the open position when the trigger fires. Nautilus orders still carry a placeholder quantity for local validation. The full_position_exit_venues setting on RiskEngineConfig and LiveRiskEngineConfig identifies venues whose execution clients enforce these semantics. It defaults to empty.

An order qualifies for the placeholder exemption only when all of these conditions hold:

• The order is submitted individually, not in an order list.
• Its venue is listed in full_position_exit_venues.
• It uses a supported futures or perpetual instrument.
• It is a StopMarket or MarketIfTouched order with a trigger price and close_position=true.
• It has a positive placeholder quantity and sets reduce_only=true.
• The command, order, and linked cached position use the same instrument and position ID.
• The linked position is open, the order side closes it, and the placeholder quantity does not exceed the position quantity.

For a qualifying exit, the risk engine treats checks as follows:

Only allowlist a venue when its downstream execution client enforces whole-position closing. See Binance Futures close-position orders for a supported configuration.

Trading state

The states become progressively more restrictive:

In REDUCING, an individual SubmitOrder is eligible only when the order sets reduce_only=true, the command and order identify the same instrument, and the supplied position ID matches the order's cached open position. The order side must oppose the position, and the submitted quantity must not exceed the cached position quantity. Order lists and modifications are denied.

The risk engine applies these rules before forwarding commands to execution.

See the RiskEngineConfig API reference for configuration details.

Execution algorithms

An ExecutionAlgorithm receives primary orders selected by exec_algorithm_id and can split them into smaller spawned orders. NautilusTrader supports custom algorithms and includes a native Rust TWAP implementation.

See Execution algorithms for TWAP configuration, custom algorithms, spawned-order behavior, and cache queries.

Cancel-all routing

Strategy.cancel_all_orders(...) supports strategy-scoped and broad cancellation:

Broad mode delegates before the strategy inspects its cache. The command therefore reaches the resolved execution client even when NautilusTrader has no matching local order. This allows a venue bulk-cancel endpoint to remove an order that exists at the venue but is missing from the local cache. When the adapter provides such an endpoint, the single command can also reduce cancel request volume.

For a local execution client, the ExecutionEngine resolves the root command to exactly one client in this order:

1. The explicit client_id, when it identifies a registered local client.
2. The client registered for the instrument's venue.
3. The default execution client.

The engine then creates fresh child commands for the selected client and its account:

• One CancelAllOrders for the execution client, covering matching venue orders.
• One CancelAllOrders for the OrderEmulator, covering matching emulated orders.
• One CancelOrder per eligible active-local execution-algorithm order.

Broad mode selects one client before fan-out; it never broadcasts across all execution clients. Call cancel_all_orders(...) once per client to cancel across several clients.

Every child has a new command ID, copies the root parameters, correlates to the root operation, and records the root command as its cause. Instrument and optional side filters apply to every local route. The selected execution account also bounds matching-engine cancellation, including orders in SUBMITTED and other cancelable in-flight states.

Client ownership applies to local emulated and execution-algorithm orders:

• Orders already assigned to another client remain untouched.
• When the root omits client_id, matching unassigned orders are claimed by the client selected by the engine before local cancellation.
• When the root supplies client_id, unassigned orders remain untouched because the engine cannot infer that they belong to the explicit client.
• An emulated order matches its traded instrument, even when another instrument supplies its trigger.

An explicitly configured external execution client receives the original root command unchanged. The external client owns any fan-out needed behind that boundary.

Command outcomes

Execution commands distinguish definitive local failures, definitive venue results, and unknown live outcomes. An unknown outcome remains in flight for stream updates, polling, queries, or reconciliation. Retry exhaustion can later apply a synthetic terminal reconciliation event.

See Execution policies for the evidence classes, delivery and retry limits, persistence boundary, and terminal reconciliation provenance. See Runtime checks for the continuous reconciliation procedure.

Order denied reasons

A local denial (OrderDenied) carries a standardized CATEGORY_CONDITION reason code and may include a diagnostic suffix. Only the leading code is canonical. Messages use these forms:

• CODE when the denial needs no diagnostic suffix.
• CODE: value for one typed value or a free-text diagnostic.
• CODE: key=value, key=value when multiple typed values need disambiguation.
• CODE: value; free text when one typed value precedes a free-text diagnostic.

The table covers local denials emitted by execution algorithms and clients as well as the risk and execution engines. These codes are the source of truth for locally denied orders. Venue-confirmed OrderRejected events instead carry the venue-provided meaning, while synthetic reconciliation rejections use the reasons documented under Terminal reconciliation provenance. Adapters remove protocol wrappers and bound untrusted venue text before emission without replacing it with a standardized local denial code.

Price and quantity checks can also emit these code-led reasons on OrderModifyRejected:

• PRICE_PRECISION_EXCEEDS_MAXIMUM
• PRICE_NOT_POSITIVE
• QUANTITY_PRECISION_EXCEEDS_MAXIMUM
• QUANTITY_EXCEEDS_MAXIMUM
• QUANTITY_BELOW_MINIMUM

For price reasons, field is PRICE or TRIGGER_PRICE and names the rejected command field. Other modification rejection reasons remain free-form; OrderDeniedCode does not classify them.

OrderRejected.due_post_only is true only when venue evidence proves that a post-only order would cross or immediately match. Other venue rejections leave it false.

Own order books

When manage_own_order_books is enabled, the ExecutionEngine maintains a market-by-order (MBO/L3) view of your working orders for each instrument. Strategies can subtract these orders from the public book to estimate net available liquidity. See Own order book for lifecycle, queries, filtering, and auditing.

Safe cancellation queries

When querying an own order book for cancellation candidates, exclude PENDING_CANCEL from the status filter.

Overfills

An overfill occurs when an order's cumulative filled quantity exceeds its original quantity. For example, fills totaling 110 units overfill a 100-unit order by 10 units.

How overfills occur

The engine observes an overfill when reported quantities exceed the order quantity. This can represent a genuine venue result, duplicate delivery under different trade IDs, or inconsistent venue reporting. Quantity alone does not identify the cause.

Live fills can arrive through two channels:

• Real-time fill events arriving via WebSocket.
• Periodic reconciliation polling the venue for fill history and position status.

Stable trade_id values let the engine deduplicate the same fill across both channels. If the logical fill arrives with different IDs, the engine treats the reports as distinct. See Continuous reconciliation for configuration details.

System behavior

The ExecutionEngine checks for potential overfills before applying each fill event by comparing the order's current filled_qty plus the incoming last_qty against the original quantity.

The allow_overfills configuration option (default: False) controls how overfills are handled:

When overfills are allowed, the order's overfill_qty field tracks the excess quantity. The order transitions to FILLED status and leaves_qty is clamped to zero.

Duplicate fill detection

The Order model enforces one applied fill per trade_id. Order.apply() returns an error when the same ID already exists on the order.

Core engine path

Before applying a fill, the ExecutionEngine calls Order.is_duplicate_fill(), which compares:

• trade_id
• order_side
• last_px
• last_qty

An exact match is skipped with a warning. If the trade_id matches but another field differs, the four-field check does not classify the fill as an exact duplicate. Order.apply() then rejects the reused ID, and the engine logs and drops the fill.

Reconciliation path

The reconciliation path checks trade_id before generating an OrderFilled event. It drops a report when that ID already exists on the order, regardless of its price or quantity.

Synthetic and inferred reconciliation fills use deterministic IDs. Replaying the same inputs after a restart therefore produces the same trade_id and is deduplicated.

Configuration

For live trading, enable overfill tolerance in the LiveExecutionEngineConfig:

from nautilus_trader.config import LiveExecutionEngineConfig

config = LiveExecutionEngineConfig(
    allow_overfills=True,
)

Fill corrections

Some venues can later reduce or invalidate a fill. Nautilus records this as an OrderFillVoided event, never as an opposite-side fill. The event identifies the original trade and carries the cumulative voided quantity and fee correction.

The execution engine rebuilds the affected order and positions and refreshes portfolio position and PnL caches before publishing the correction to strategies and execution algorithms. Adapters that support fill corrections request an authoritative account refresh after a void.

Adapters must publish the referenced fill before a reopened correction or a partial correction that leaves the order executable. Without a local fill, a non-reopened correction makes the whole order terminal, even when voided_qty is less than the order quantity. A later working status report does not reopen VOIDED. See the complete OrderFillVoided contract.

How voided fills occur

A void is a venue action on a trade it already reported. The causes recur across asset classes:

• Erroneous execution review: the venue nullifies a print that is substantially inconsistent with the market at the time of execution, or one caused by an exchange system fault.
• Settlement failure: a matched trade fails to settle, so the fill never takes economic effect.
• Event invalidation: the underlying event is abandoned or a competitor is withdrawn, so matched positions carry no exposure.
• Post-trade restatement: the venue restates the quantity or fees of a trade during clearing.

The event does not restate the fill price, so a venue price adjustment is not expressible as a single correction.

A break reaches the client differently by venue. FIX venues signal one through ExecType <150> values H (trade cancel) and G (trade correct). Venues that notify out of band leave the break to surface through execution reconciliation.

Venue references

Each venue publishes the conditions under which it acts:

Nautilus adapters emit OrderFillVoided where the venue publishes the void on a stream the adapter consumes: Betfair from the order change message sv field, and Polymarket from the user channel trade status.

Related guides

• Events: Order and position event types and dispatch.
• Execution algorithms: TWAP, custom algorithms, and spawned orders.
• Execution policies: Delivery, state, persistence, and recovery boundaries.
• Execution reconciliation: Live state recovery and runtime consistency checks.
• Order book: Public and own order book behavior.
• Orders: Order types and management.
• Positions: Position tracking from executions.
• Strategies: Order submission from strategies.