Skip to main content

Trade

One filled position in one instrument: what the broker turns an Order into. Construction is two-phase. __init__ records what was filled; Portfolio.add_trade then calls init_stats, which reads the opening mark off the datafeed and sets the prices, greeks, notional and history lists. Until it has run the trade cannot be pulsed and none of that marked state can be read. pulse marks the trade once per pulse thereafter, skipping the pulse it opened on. Parameters

Trade.trade_id

property
Get the unique identifier for the trade.

Trade.order_id

property
Get the unique identifier for the order associated with this trade.

Trade.open_price

property
Get the price at which the trade was opened at.

Trade.open_quantity

property
Get the open quantity of a trade.

Trade.fill_price

property
Get the fill price of the trade.

Trade.settlement_price_at_open

property
Get the settlement price at which the trade was opened at.

Trade.close_price

property
Get the price at which the trade was closed at.

Trade.instrument

property
Get the instrument associated with the trade.

Trade.quantity

property
Get the quantity of the instrument traded.

Trade.is_lots

property
Check if the trade quantity is in lots.

Trade.contract_size

property
Units per lot of the traded contract, read from the reference data at open.

Trade.price_format_multiplier

property
Factor turning the data layer’s raw price into the marking price, read at open.

Trade.units

property
Signed quantity in the instrument’s own units (lots scaled by contract_size).

Trade.sign

property
Get the sign of the trade quantity.

Trade.open_datetime

property
Get the datetime when the trade was opened.

Trade.close_datetime

property
Get the datetime when the trade was closed.

Trade.is_open

property
Check if the trade is still open.

Trade.tags

property
Get the tags associated with the trade.

Trade.source_id

property
Get the originating strategy / sleeve id, if any. Carried from the pulse.core.order.Order that filled into this trade. None for trades not attributed to a sleeve (e.g. classic single-strategy use).

Trade.pnl

property
Get the cumulative profit and loss of the trade. Returns the pnl of the trade in dollars.

Trade.pnl_pct

property
Cumulative PnL as a fraction of the account equity at trade open. pnl / abs(equity_at_open). Sizing-aware - tells you how this trade moved the account at the moment it was taken. Denominator is wrapped in abs so a gain on a negative-equity account still reads positive. Returns 0.0 if equity_at_open is 0.

Trade.initial_equity

property
Strategy starting capital, captured at trade open by Portfolio.add_trade.

Trade.equity_at_open

property
Portfolio current_equity at the pulse this trade opens on, captured by Portfolio.add_trade.

Trade.pnl_pct_of_initial_equity

property
Cumulative PnL as a fraction of the strategy’s starting capital. pnl / abs(initial_equity). Stable denominator across the run - directly comparable across trades. Returns 0.0 if initial_equity is 0.

Trade.pulse_abs_pnl

property
Get the last per-pulse absolute profit and loss of the trade.

Trade.pulse_pct_pnl

property
Get the last per-pulse percentage profit and loss of the trade.

Trade.datetimes

property
Get the historical datetimes of the trade.

Trade.abs_pnl_history

property
Get the historical cumulative profit and loss of the trade in currency.

Trade.pct_pnl_history

property
Get the historical cumulative profit and loss of the trade in percentage.

Trade.pulse_abs_pnl_history

property
Get the historical per-pulse profit and loss of the trade in currency. Length matches datetimes (one entry per pulse).

Trade.pulse_pct_pnl_history

property
Get the historical per-pulse profit and loss of the trade in percentage. Length matches datetimes (one entry per pulse).

Trade.daily_datetimes

property
Unique calendar dates the trade has been live, in chronological order.

Trade.daily_abs_pnl_history

property
Per-calendar-date absolute P&L (sum of pulse values within each date).

Trade.daily_pct_pnl_history

property
Per-calendar-date percentage P&L (compounded pulse pct returns within each date).

Trade.daily_abs_pnl

property
Today’s running absolute P&L tally (today = datetimes[-1].date()). For daily cadence this equals pulse_abs_pnl.

Trade.daily_pct_pnl

property
Today’s running compound percentage P&L.

Trade.quantity_history

property
Get the historical quantity of the trade.

Trade.price_history

property
Get the historical prices of the trade.

Trade.notional_history

property
Get the historical notional values of the trade.

Trade.delta

property
Get the per-unit delta of the trade. For futures this is 1.0.

Trade.gamma

property
Get the per-unit gamma of the trade. For futures this is 0.0.

Trade.theta

property
Get the per-unit theta of the trade. For futures this is 0.0.

Trade.vega

property
Get the per-unit vega of the trade. For futures this is 0.0.

Trade.delta_contract

property
Get the size-multiplied delta (per-unit delta * units).

Trade.gamma_contract

property
Get the size-multiplied gamma (per-unit gamma * units).

Trade.theta_contract

property
Get the size-multiplied theta (per-unit theta * units).

Trade.vega_contract

property
Get the size-multiplied vega (per-unit vega * units).

Trade.delta_history

property
Get the historical per-unit delta of the trade. Length matches datetimes (one entry per pulse).

Trade.gamma_history

property
Get the historical per-unit gamma of the trade. Length matches datetimes (one entry per pulse).

Trade.theta_history

property
Get the historical per-unit theta of the trade. Length matches datetimes (one entry per pulse).

Trade.vega_history

property
Get the historical per-unit vega of the trade. Length matches datetimes (one entry per pulse).

Trade.delta_contract_history

property
Get the historical size-multiplied delta of the trade. Length matches datetimes (one entry per pulse).

Trade.gamma_contract_history

property
Get the historical size-multiplied gamma of the trade. Length matches datetimes (one entry per pulse).

Trade.theta_contract_history

property
Get the historical size-multiplied theta of the trade. Length matches datetimes (one entry per pulse).

Trade.vega_contract_history

property
Get the historical size-multiplied vega of the trade. Length matches datetimes (one entry per pulse).

Trade.underlying_price_history

property
Get the historical raw price the greeks were taken against: an option’s underlying, a future’s or spot’s own price, before price_format_multiplier. Length matches datetimes (one entry per pulse).

Trade.iv_history

property
Get the historical implied vol of an option (decimal), None for a future or spot. Length matches datetimes (one entry per pulse).

Trade.init_stats

Initialize trade statistics with the datafeed. Parameters

Trade.values_at

The data layer’s row for this contract, or the last one it returned when it is dark. The single read point for a trade, so marking (_mark) and summarising (Strategy.calculate_trades_summary) cannot disagree about what a data gap means. Because the carried value is the record the data layer actually returned, a dark futures or spot leg keeps its real shape: it has no delta attribute, exactly as on a healthy pulse, so it stays out of the greek aggregates instead of being pulled into them by a stand-in. strict=True re-raises instead, for a caller that needs a real row: opening a trade needs a real price, and the framework’s shadow repricer wants an unpriceable leg to surface. Only the data layer’s own LookupError counts as “this contract is absent”. KeyError and IndexError are subclasses of it raised by faults inside the reader (a missing column, a bisect off a truncated file), so those propagate rather than being carried forward as a flat mark for the rest of the run.

Trade.add_tag

Add a tag to the trade. Parameters

Trade.has_tag

Checks if Trade has tag or list of tags. Parameters Returns

Trade.rebalance

Rebalance the trade by adjusting the quantity. Parameters Raises

Trade.pulse

Update the trade with the latest price and calculate PnL. Raises

Trade.close

Close the trade

expiration_date_of

The expiry of an option or future; None for spot, which never expires. The data-layer Instrument base carries no expiry (only the subtypes that have one do), so this is the one place the engine asks “does this contract expire, and when”.

has_expired

Whether instrument is past its expiry at as_of_time. Spot never expires. The single definition of the expiry predicate for the engine: Trade.pulse and Portfolio.__close_trades both ask through here, so they cannot drift apart on the boundary.
Last modified on November 4, 2026