Position¶

class Position¶

Bases: object

Position(Instrument instrument, OrderFilled fill) -> None

Represents a position in a market.

The position ID may be assigned at the trading venue, or can be system generated depending on a strategies OMS (Order Management System) settings.

Parameters:

instrument (Instrument) – The trading instrument for the position.
fill (OrderFilled) – The order fill event which opened the position.

Raises:

ValueError – If instrument.id is not equal to fill.instrument_id.
ValueError – If fill.position_id is None.

account_id¶

The account ID associated with the position.

Returns:: AccountId

adjustments¶

Return the position adjustment events.

Return type:: list[PositionAdjusted]

apply(self, OrderFilled fill) → void¶

Applies the given order fill event to the position.

If the position is FLAT prior to applying fill, the position state is reset (clearing existing events, commissions, etc.) before processing the new fill.

Parameters:: fill (OrderFilled) – The order fill event to apply.
Raises:: KeyError – If fill.trade_id already applied to the position.

apply_adjustment(self, PositionAdjusted adjustment) → void¶

Applies a position adjustment event.

This method handles adjustments to position quantity or realized PnL that occur outside of normal order fills, such as: - Commission adjustments in base currency (crypto spot markets) - Funding payments (perpetual futures)

The adjustment event is stored in the position’s adjustment history for full audit trail.

Parameters:: adjustment (PositionAdjusted) – The position adjustment event to apply.

avg_px_close¶

The average close price.

Returns:: double

avg_px_open¶

The average open price.

Returns:: double

base_currency¶

The position base currency (if applicable).

Returns:: Currency or None

calculate_pnl(self, double avg_px_open, double avg_px_close, Quantity quantity) → Money¶

Return a calculated PnL in the instrument’s settlement currency.

Parameters:

avg_px_open (double) – The average open price.
avg_px_close (double) – The average close price.
quantity (Quantity) – The quantity for the calculation.

Returns:

Denominated in settlement currency.

Return type:

Money

client_order_ids¶

Return the client order IDs associated with the position.

Return type:: list[ClientOrderId]

Notes

Guaranteed not to contain duplicate IDs.

closing_order_id¶

The client order ID for the order which closed the position.

Returns:: ClientOrderId or None

closing_order_side(self) → OrderSide¶

Return the closing order side for the position.

If the position is FLAT then will return NO_ORDER_SIDE.

Return type:: OrderSide

commissions(self) → list¶

Return the total commissions generated by the position.

Return type:: list[Money]

cross_notional_value(self, Price price, Price quote_price, Price base_price, Currency target_currency) → Money¶

Return the current notional value of the position in a cross/target currency.

The quote_price is the Quote/Target conversion price, and base_price is the Base/Target conversion price.

Parameters:

price (Price) – The reference price for the calculation.
quote_price (Price) – The Quote/Target conversion price.
base_price (Price) – The Base/Target conversion price.
target_currency (Currency) – The target currency for conversion.

Return type:

Money

duration_ns¶

The total open duration in nanoseconds (zero unless closed).

Returns:: uint64_t

entry¶

The position entry order side.

Returns:: OrderSide

event_count¶

Return the count of order fill events applied to the position.

Return type:: int

events¶

Return the order fill events for the position.

Return type:: list[Event]

id¶

The position ID.

Returns:: PositionId

info(self) → str¶

Return a summary description of the position.

Return type:: str

instrument_class¶

The position instrument class.

Returns:: InstrumentClass

instrument_id¶

The position instrument ID.

Returns:: InstrumentId

is_closed¶

Return whether the position side is FLAT.

Return type:: bool

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

is_long¶

Return whether the position side is LONG.

Return type:: bool

is_open¶

Return whether the position side is not FLAT.

Return type:: bool

is_opposite_side(self, OrderSide side) → bool¶

Return a value indicating whether the given order side is opposite to the current position side.

Parameters:: side (OrderSide {BUY, SELL})
Returns:: True if side is opposite, else False.
Return type:: bool

is_short¶

Return whether the position side is SHORT.

Return type:: bool

is_spot_currency¶

If the instrument is a spot currency pair.

Returns:: bool

last_event¶

Return the last order fill event (if any after purging).

Return type:: OrderFilled or None

last_trade_id¶

Return the last trade match ID for the position (if any after purging).

Return type:: TradeId or None

multiplier¶

The multiplier for the positions instrument.

Returns:: Quantity

notional_value(self, Price price, Currency target_currency=None, Price conversion_price=None) → Money¶

Return the current notional value of the position, using a reference price for the calculation (e.g., bid, ask, mid, last, or mark).

For a standard (non-inverse) instrument, the notional is returned in the quote currency.
For an inverse instrument, the notional is returned in the base currency, with the calculation scaled by 1 / price.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

price (Price) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Returns:

Denominated in quote currency for standard instruments, or base currency if inverse.

Return type:

Money

opening_order_id¶

The client order ID for the order which opened the position.

Returns:: ClientOrderId

peak_qty¶

The peak directional quantity reached by the position.

Returns:: Quantity

price_precision¶

The price precision for the position.

Returns:: uint8

purge_events_for_order(self, ClientOrderId client_order_id) → None¶

Purge all order events for the given client order ID.

After purging, the position is rebuilt from remaining fills. If no fills remain, the position is reset to an empty shell with all history cleared (including timestamps), making it eligible for immediate cache cleanup.

Parameters:: client_order_id (ClientOrderId) – The client order ID for the events to purge.

quantity¶

The current open quantity.

Returns:: Quantity

quote_currency¶

The position quote currency.

Returns:: Currency

realized_pnl¶

The current realized PnL for the position (including commissions).

Returns:: Money or None

realized_return¶

The current realized return for the position.

Returns:: double

settlement_currency¶

The position settlement currency (for PnL).

Returns:: Currency

side¶

The current position side.

Returns:: PositionSide

static side_from_order_side(OrderSide side)¶

Return the position side resulting from the given order side (from FLAT).

Parameters:: side (OrderSide {BUY, SELL}) – The order side
Return type:: PositionSide

signed_decimal_qty(self)¶

Return a signed decimal representation of the position quantity.

If the position is LONG, the value is positive (e.g. Decimal(‘10.25’))

If the position is SHORT, the value is negative (e.g. Decimal(‘-10.25’))

If the position is FLAT, the value is zero (e.g. Decimal(‘0’))

Return type:: Decimal

signed_qty¶

The current signed quantity (positive for position side LONG, negative for SHORT).

Returns:: double

size_precision¶

The size precision for the position.

Returns:: uint8

strategy_id¶

The strategy ID associated with the position.

Returns:: StrategyId

symbol¶

Return the positions ticker symbol.

Return type:: Symbol

to_dict(self) → dict¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

total_pnl(self, Price price) → Money¶

Return the total PnL for the position, using a reference price for the calculation (e.g., bid, ask, mid, last, or mark).

Parameters:: price (Price) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
Returns:: Denominated in settlement currency.
Return type:: Money

trade_ids¶

Return the trade match IDs associated with the position.

Return type:: list[TradeId]

trader_id¶

The trader ID associated with the position.

Returns:: TraderId

ts_closed¶

UNIX timestamp (nanoseconds) when the position was closed (zero unless closed).

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

ts_last¶

UNIX timestamp (nanoseconds) when the last event occurred.

Returns:: uint64_t

ts_opened¶

UNIX timestamp (nanoseconds) when the position was opened.

Returns:: uint64_t

unrealized_pnl(self, Price price) → Money¶

Return the unrealized PnL for the position, using a reference price for the calculation (e.g., bid, ask, mid, last, or mark).

Parameters:: price (Price) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
Returns:: Denominated in settlement currency.
Return type:: Money

venue¶

Return the positions trading venue.

Return type:: Venue

venue_order_ids¶

Return the venue order IDs associated with the position.

Return type:: list[VenueOrderId]

Notes

Guaranteed not to contain duplicate IDs.