Events

Nautilus is event-driven: every state change in the system is represented by an event object that flows through the MessageBus to strategy and actor handlers. This guide covers the event types, how they are dispatched, and how order fills produce position events.

Event categories

Handler dispatch

When an event reaches a strategy, the system calls handlers in a fixed priority order. The first matching handler runs, then the next level, so you can handle events at whatever granularity you need.

Order events

1. Specific handler (e.g. on_order_filled)
2. on_order_event (receives all order events)
3. on_event (receives everything)

Position events

1. Specific handler (e.g. on_position_opened)
2. on_position_event (receives all position events)
3. on_event (receives everything)

Time events

Timers and alerts produce TimeEvent objects. Pass a callback when calling set_timer or set_time_alert to direct events to your own method. If you omit the callback, a callback previously registered under the same name is used when present; otherwise the event is delivered to on_event instead.

Order events

Each order event corresponds to a state transition in the order state machine. The ExecutionEngine applies the event to the order, updates the Cache, and publishes it on the MessageBus. The table below shows the primary transitions; partially filled and triggered orders support additional transitions documented in the full order state flow.

Common order event fields

All order events share these fields:

Each order event's page lists the type-specific fields it adds beyond this common set, plus which optional common fields are populated. For example, OrderFilled adds last_qty, last_px, trade_id, and commission. OrderFillVoided identifies the corrected trade and carries its cumulative voided quantity.

:::tip Override on_order_event to handle all order events in one place. The specific handlers fire first, so you can combine both approaches. :::

Position events

Position events are a direct consequence of fill events. The ExecutionEngine processes each OrderFilled, updates or creates a position, and emits the corresponding position event.

An OrderFillVoided rebuilds the cached position from its effective fill history. It does not emit an opposite fill or synthesize a position event.

From fill to position: the causal chain

The following diagram shows how a single OrderFilled event produces a position event. This is the key link between order management and position tracking.

sequenceDiagram
    participant Venue as Venue
    participant EE as ExecutionEngine
    participant Cache as Cache
    participant Strategy as Strategy

    Venue-->>EE: OrderFilled
    EE->>EE: apply fill to order
    EE->>Cache: update order state
    EE->>EE: determine position ID

    alt No existing position
        EE->>Cache: add new Position
        EE->>Strategy: PositionOpened
    else Position open, not closed by fill
        EE->>Cache: update Position
        EE->>Strategy: PositionChanged
    else Fill closes the position
        EE->>Cache: update Position
        EE->>Strategy: PositionClosed
    end

Step by step:

1. Fill arrives. The ExecutionEngine receives an OrderFilled event from the venue adapter.
2. Order state updates. The engine applies the fill to the order object and writes the updated order to the Cache.
3. Position ID resolved. The engine determines which position this fill belongs to, based on OMS type and strategy configuration.
4. Position created or updated. Three outcomes:
   • No position exists for this ID: the engine creates a Position from the fill, adds it to the Cache, and emits PositionOpened.
   • Position exists and remains open after the fill: the engine applies the fill to the position, updates the Cache, and emits PositionChanged.
   • Position exists and closes (quantity reaches zero): the engine applies the fill, updates the Cache, and emits PositionClosed.
5. Flip case. When a fill reverses the position (e.g. long 10 filled sell 15), the engine splits the fill into two parts: one that closes the original position (PositionClosed) and one that opens the new position (PositionOpened).

Position event fields

Every position event exposes all of these fields (they are defined on the PositionEvent base). A check mark means the field carries a meaningful value for that event; a dash means it is left at its zero or default (for example avg_px_close and duration_ns before a position closes).

Tracing orders to positions

The Cache provides methods to navigate between orders and positions:

# From a position, find all orders that contributed fills
orders = self.cache.orders_for_position(position.id)

# From an order, find the position it belongs to
position = self.cache.position_for_order(order.client_order_id)

# The opening order is stored directly on the position
opening_order_id = position.opening_order_id

Account events

AccountState events represent balance and margin snapshots. They fire when:

• The venue reports an account update (via the execution client).
• The Portfolio recalculates account state after a position update (for margin accounts with calculate_account_state enabled).

Account state contains balances, margins, account type, and base currency. The Portfolio subscribes to these events internally to maintain exposure and balance tracking. See AccountState for the full field list.

Event subscriptions

Beyond strategy handlers, actors can subscribe to specific event streams for instruments they do not trade. These subscriptions use the MessageBus directly and do not involve the DataEngine.

These are useful for monitoring actors that track execution quality or fill rates across strategies without participating in order management.

For details and examples, see Order event subscriptions.

Related guides

• Orders - Order types and state machine.
• Positions - Position lifecycle and PnL.
• Execution - Execution flow and risk checks.
• Strategies - Handler implementations in strategies.
• Architecture - Data and execution flow patterns.