ContextQMD
Back to Nautilus Trader

PositionChanged

docs/concepts/events/position_changed.md

1.231.01.7 KB
Original Source

PositionChanged

PositionChanged represents a position having changed. The ExecutionEngine emits it when a subsequent fill changes an open position's quantity or side (see From fill to position). Handler: on_position_changed.

Fields

PositionChanged shares the position event field set. See Position event fields for the full matrix across the three events. The fields that distinguish PositionChanged:

FieldPython typeDescription
peak_qtyQuantityThe peak directional quantity reached by the position.
avg_px_closefloatThe average close price so far.
realized_returnfloatThe realized return for the position.
realized_pnlMoneyThe realized PnL for the position.
unrealized_pnlMoneyThe unrealized PnL for the position.

While the position remains open, closing_order_id is still None.

Example

Reading the event in a strategy handler:

python
def on_position_changed(self, event: PositionChanged) -> None:
    self.log.info(
        f"Changed {event.instrument_id} to {event.signed_qty} (realized={event.realized_pnl})",
    )
  • Events - Event categories, dispatch, and the fill-to-position chain.
  • Positions - Position lifecycle, aggregation, and PnL.
  • Orders - Orders whose fills open and close positions.