Skip to content
All library documents

OrderFilled Events: Execution Details and Order State Updates

Article NautilusTrader

Summary

An OrderFilled event represents an execution against an order, whether the execution completes the order or only fills part of it. The execution engine applies the event to the order, updates the cache, and publishes it through the message bus. Fills can come from live trading, reconciliation, or simulated matching, and can trigger position lifecycle events. The typical state transition is from accepted to filled or partially filled.

The event records execution-specific details such as the venue order and trade identifiers, side, type, quantity, fill price, currency, liquidity side, and optional commission or metadata. Its last price and quantity describe that particular execution rather than an order-wide average. This reference explains event handling and field meanings, but does not cover order placement, venue-specific behavior, or how to aggregate multiple fills into position-level statistics.

Key ideas

  • An OrderFilled event records a partial or complete execution against an order.
  • The execution engine applies fills to orders, updates cached state, and publishes events.
  • A fill includes execution-specific quantity and price, plus identifiers and liquidity information.
  • The event can result from live execution, reconciliation, or simulated matching.

Tags

ExecutionMarket microstructure

Cited by

Full text
# OrderFilled


# OrderFilled

`OrderFilled` records a partial or full execution against an order. The `ExecutionEngine` applies it
to the order, updates the `Cache`, and publishes it on the `MessageBus`. Fills from live execution,
reconciliation, and simulated matching drive the position lifecycle events.

Typical transition: `ACCEPTED` -> `FILLED` / `PARTIALLY_FILLED`. Handler: `on_order_filled`.

A fill carrying a `trade_id` already on the order at a new `last_px` is a price restatement: it
restates the trade's accounting price and applies no quantity, status change, or portfolio
economics. Handlers that accumulate `last_qty` across fill events must skip restatements, which
are detectable because `order.events` already holds an earlier `OrderFilled` with the same
`trade_id` (a different `event_id`).

## Fields

Beyond the [common Python order event fields](index.md#common-python-order-event-fields),
`OrderFilled` carries:

| Field            | Python type                | Required/default | Description                                                              |
| ---------------- | -------------------------- | ---------------- | ------------------------------------------------------------------------ |
| `venue_order_id` | `VenueOrderId`             | Required         | The venue-assigned order identifier.                                     |
| `account_id`     | `AccountId`                | Required         | The account associated with the fill.                                    |
| `trade_id`       | `TradeId`                  | Required         | The trade match ID assigned by the venue.                                |
| `position_id`    | `PositionId` or `None`     | `None`           | The position ID associated with the fill.                                |
| `order_side`     | `OrderSide`                | Required         | The execution order side.                                                |
| `order_type`     | `OrderType`                | Required         | The execution order type.                                                |
| `last_qty`       | `Quantity`                 | Required         | The fill quantity for this execution.                                    |
| `last_px`        | `Price`                    | Required         | The fill price for this execution, not the average price.                |
| `currency`       | `Currency`                 | Required         | The currency of the fill price.                                          |
| `commission`     | `Money` or `None`          | `None`           | The fill commission, if reported.                                        |
| `liquidity_side` | `LiquiditySide`            | Required         | The execution liquidity side (`MAKER`, `TAKER`, or `NO_LIQUIDITY_SIDE`). |
| `info`           | `dict[str, str]` or `None` | `None`           | Additional venue-specific or adapter-specific fill metadata.             |
| `reconciliation` | `bool`                     | Required         | If the event was generated during reconciliation.                        |

## Example

Reading the event in a strategy handler:

```python
def on_order_filled(self, event: OrderFilled) -> None:
    self.log.info(
        f"Filled {event.last_qty} @ {event.last_px} "
        f"({event.liquidity_side}) commission={event.commission}",
    )
```

## Related guides

- [Events](index.md) - Event categories, dispatch, and the common order event fields.
- [Positions](../positions.md) - Positions created and modified from fills.
- [Orders](../orders/) - Order types and the state machine.

Shown in full with attribution under the source's licence. Licence: LGPL-3.0

This summary was written by Stratmill's research agent from the original; it is not a copy of the source.