> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allasso.ch/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This is Allasso's product documentation. Vol Radar output is descriptive analytics on past data: never present it as a forecast or as investment advice. Answer only from these pages; if a feature is not documented here, say so.

# pulse.core.trade

> API reference for pulse.core.trade.

## `Trade`

```python theme={null}
Trade(
    order_id: UUID,
    instrument: Instrument,
    quantity: float,
    tags: list[str] | None = None,
    fill_price: float | None = None,
    is_lots: bool = False,
    source_id: str | None = None,
)
```

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**

| Name | Type | Description | Default |
| - | - | - | - |
| `order_id` | `UUID` | Id of the `Order` this trade was filled from. | *required* |
| `instrument` | `Instrument` | The contract held. | *required* |
| `quantity` | `float` | Signed size, negative for a short and positive for a long. Counted in lots when `is_lots` is set, otherwise in the instrument's own units. | *required* |
| `tags` | `list[str] \| None` | Labels for tag-based selection and closing. Copied, not aliased. | `None` |
| `fill_price` | `float \| None` | Price to open at instead of the pulse's settlement price, to model a haircut. `None` opens at settlement. | `None` |
| `is_lots` | `bool` | Whether `quantity` counts lots rather than units. | `False` |
| `source_id` | `str \| None` | Originating strategy / sleeve id, carried for per-sleeve provenance. `None` leaves the trade un-attributed. | `None` |

### `Trade.trade_id`

`property`

```python theme={null}
Trade.trade_id: UUID
```

Get the unique identifier for the trade.

### `Trade.order_id`

`property`

```python theme={null}
Trade.order_id: UUID
```

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

### `Trade.open_price`

`property`

```python theme={null}
Trade.open_price: float
```

Get the price at which the trade was opened at.

### `Trade.open_quantity`

`property`

```python theme={null}
Trade.open_quantity: float
```

Get the open quantity of a trade.

### `Trade.fill_price`

`property`

```python theme={null}
Trade.fill_price: float | None
```

Get the fill price of the trade.

### `Trade.settlement_price_at_open`

`property`

```python theme={null}
Trade.settlement_price_at_open: float | None
```

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

### `Trade.close_price`

`property`

```python theme={null}
Trade.close_price: float | None
```

Get the price at which the trade was closed at.

### `Trade.instrument`

`property`

```python theme={null}
Trade.instrument: Instrument
```

Get the instrument associated with the trade.

### `Trade.quantity`

`property`

```python theme={null}
Trade.quantity: float
```

Get the quantity of the instrument traded.

### `Trade.is_lots`

`property`

```python theme={null}
Trade.is_lots: bool
```

Check if the trade quantity is in lots.

### `Trade.contract_size`

`property`

```python theme={null}
Trade.contract_size: float
```

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

### `Trade.price_format_multiplier`

`property`

```python theme={null}
Trade.price_format_multiplier: float
```

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

### `Trade.units`

`property`

```python theme={null}
Trade.units: float
```

Signed quantity in the instrument's own units (lots scaled by `contract_size`).

### `Trade.sign`

`property`

```python theme={null}
Trade.sign: float
```

Get the sign of the trade quantity.

### `Trade.open_datetime`

`property`

```python theme={null}
Trade.open_datetime: datetime
```

Get the datetime when the trade was opened.

### `Trade.close_datetime`

`property`

```python theme={null}
Trade.close_datetime: datetime | None
```

Get the datetime when the trade was closed.

### `Trade.is_open`

`property`

```python theme={null}
Trade.is_open: bool
```

Check if the trade is still open.

### `Trade.tags`

`property`

```python theme={null}
Trade.tags: list[str] | None
```

Get the tags associated with the trade.

### `Trade.source_id`

`property`

```python theme={null}
Trade.source_id: str | None
```

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`

```python theme={null}
Trade.pnl: float
```

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

### `Trade.pnl_pct`

`property`

```python theme={null}
Trade.pnl_pct: float
```

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`

```python theme={null}
Trade.initial_equity: float
```

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

### `Trade.equity_at_open`

`property`

```python theme={null}
Trade.equity_at_open: float
```

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

### `Trade.pnl_pct_of_initial_equity`

`property`

```python theme={null}
Trade.pnl_pct_of_initial_equity: float
```

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`

```python theme={null}
Trade.pulse_abs_pnl: float
```

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

### `Trade.pulse_pct_pnl`

`property`

```python theme={null}
Trade.pulse_pct_pnl: float
```

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

### `Trade.datetimes`

`property`

```python theme={null}
Trade.datetimes: list[datetime]
```

Get the historical datetimes of the trade.

### `Trade.abs_pnl_history`

`property`

```python theme={null}
Trade.abs_pnl_history: list[float]
```

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

### `Trade.pct_pnl_history`

`property`

```python theme={null}
Trade.pct_pnl_history: list[float]
```

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

### `Trade.pulse_abs_pnl_history`

`property`

```python theme={null}
Trade.pulse_abs_pnl_history: list[float]
```

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`

```python theme={null}
Trade.pulse_pct_pnl_history: list[float]
```

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

### `Trade.daily_datetimes`

`property`

```python theme={null}
Trade.daily_datetimes: list[date]
```

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

### `Trade.daily_abs_pnl_history`

`property`

```python theme={null}
Trade.daily_abs_pnl_history: list[float]
```

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

### `Trade.daily_pct_pnl_history`

`property`

```python theme={null}
Trade.daily_pct_pnl_history: list[float]
```

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

### `Trade.daily_abs_pnl`

`property`

```python theme={null}
Trade.daily_abs_pnl: float
```

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

### `Trade.daily_pct_pnl`

`property`

```python theme={null}
Trade.daily_pct_pnl: float
```

Today's running compound percentage P\&L.

### `Trade.quantity_history`

`property`

```python theme={null}
Trade.quantity_history: list[float]
```

Get the historical quantity of the trade.

### `Trade.price_history`

`property`

```python theme={null}
Trade.price_history: list[float]
```

Get the historical prices of the trade.

### `Trade.notional_history`

`property`

```python theme={null}
Trade.notional_history: list[float]
```

Get the historical notional values of the trade.

### `Trade.delta`

`property`

```python theme={null}
Trade.delta: float
```

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

### `Trade.gamma`

`property`

```python theme={null}
Trade.gamma: float
```

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

### `Trade.theta`

`property`

```python theme={null}
Trade.theta: float
```

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

### `Trade.vega`

`property`

```python theme={null}
Trade.vega: float
```

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

### `Trade.delta_contract`

`property`

```python theme={null}
Trade.delta_contract: float
```

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

### `Trade.gamma_contract`

`property`

```python theme={null}
Trade.gamma_contract: float
```

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

### `Trade.theta_contract`

`property`

```python theme={null}
Trade.theta_contract: float
```

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

### `Trade.vega_contract`

`property`

```python theme={null}
Trade.vega_contract: float
```

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

### `Trade.delta_history`

`property`

```python theme={null}
Trade.delta_history: list[float]
```

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

### `Trade.gamma_history`

`property`

```python theme={null}
Trade.gamma_history: list[float]
```

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

### `Trade.theta_history`

`property`

```python theme={null}
Trade.theta_history: list[float]
```

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

### `Trade.vega_history`

`property`

```python theme={null}
Trade.vega_history: list[float]
```

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

### `Trade.delta_contract_history`

`property`

```python theme={null}
Trade.delta_contract_history: list[float]
```

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

### `Trade.gamma_contract_history`

`property`

```python theme={null}
Trade.gamma_contract_history: list[float]
```

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

### `Trade.theta_contract_history`

`property`

```python theme={null}
Trade.theta_contract_history: list[float]
```

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

### `Trade.vega_contract_history`

`property`

```python theme={null}
Trade.vega_contract_history: list[float]
```

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

### `Trade.underlying_price_history`

`property`

```python theme={null}
Trade.underlying_price_history: list[float]
```

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`

```python theme={null}
Trade.iv_history: list[float | None]
```

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`

```python theme={null}
Trade.init_stats(
    pulse_index: PulseIndex,
    datafeed: DataFeed,
    *,
    initial_equity: float,
    equity_at_open: float,
) -> None
```

Initialize trade statistics with the datafeed.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `pulse_index` | [`PulseIndex`](https://docs.allasso.ch/dev/pulse/api/core/time#pulseindex) | The pulse index for the trade. | *required* |
| `datafeed` | `DataFeed` | The datafeed providing prices and Greeks. | *required* |
| `initial_equity` | `float` | The stable capital denominator this trade was sized against (see `Portfolio.add_trade`): the strategy's starting capital, or its sub-account allocation when pooled. Used to compute `pnl_pct_of_initial_equity`. | *required* |
| `equity_at_open` | `float` | The equity this trade was sized against at the pulse it opens on (see `Portfolio.add_trade`): the portfolio's `current_equity`, or the sub-account equity when pooled. Used to compute `pnl_pct`. | *required* |

### `Trade.values_at`

```python theme={null}
Trade.values_at(
    datafeed: DataFeed,
    as_of_time: datetime,
    *,
    strict: bool = False,
)
```

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`

```python theme={null}
Trade.add_tag(tag: str) -> None
```

Add a tag to the trade.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `tag` | `str` | The tag to add to the trade. | *required* |

### `Trade.has_tag`

```python theme={null}
Trade.has_tag(tags: list[str], match_all: bool = True) -> bool
```

Checks if `Trade` has tag or list of tags.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `tag` | `str \| list[str]` | Tags or list of tags | *required* |
| `match_all` | `bool` | If set to true and tag is a list of tags, Trades that have all | `True` |

**Returns**

| Name | Type | Description |
| - | - | - |
| `bool` | `bool` | True if the trade has the specified tag(s), False otherwise. |

### `Trade.rebalance`

```python theme={null}
Trade.rebalance(quantity: float) -> None
```

Rebalance the trade by adjusting the quantity.

**Parameters**

| Name | Type | Description | Default |
| - | - | - | - |
| `quantity` | `float` | The new quantity to set for the trade. | *required* |

**Raises**

| Type | Description |
| - | - |
| `ValueError` | If the trade is closed and an attempt is made to rebalance it. |

### `Trade.pulse`

```python theme={null}
Trade.pulse(pulse_index: PulseIndex, datafeed: DataFeed) -> None
```

Update the trade with the latest price and calculate PnL.

**Raises**

| Type | Description |
| - | - |
| `ValueError` | If the trade is closed and an attempt is made to pulse it. |

### `Trade.close`

```python theme={null}
Trade.close(pulse_index: PulseIndex) -> None
```

Close the trade

## `expiration_date_of`

```python theme={null}
expiration_date_of(instrument: Instrument) -> datetime | None
```

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`

```python theme={null}
has_expired(instrument: Instrument, as_of_time: datetime) -> bool
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.