> ## 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.

# Orders, trades and the broker

> An Order is an intent to trade; a Trade is the filled position that results. The Broker turns one into the other. In a backtest the broker is the SimulationBroker, which fills market orders only.

An `Order` is an intent to trade; a `Trade` is the filled position that results. The `Broker` turns
one into the other. In a backtest the broker is the `SimulationBroker`, which fills market orders only.

## Placing an order

From inside `on_update()` you place orders with the strategy helpers:

```python theme={null}
self.buy(underlying_id, instrument_type, expiration_date, strike, quantity, tags=["entry"])
self.sell(underlying_id, instrument_type, expiration_date, strike, quantity, tags=["entry"])
```

Both build an instrument and forward to the broker. `buy` always sends a positive quantity; `sell`
always sends a negative one - so the sign of a trade's `quantity` tells you the direction. For full
control (or to pass a pre-built `Option` / `Future`) call the broker directly:

```python theme={null}
self.broker.create_order(self.pulse_index, instrument, quantity, tags=None, fill_price=None, is_lots=False)
```

| Argument | Meaning |
| - | - |
| `quantity` | Signed size. **Positive = buy, negative = sell.** Zero raises. |
| `tags` | Labels carried onto the resulting `Trade`, used for grouping and bulk closing. |
| `fill_price` | Override price. When `None`, the trade fills at the instrument's price on the fill pulse. |
| `is_lots` | `True` sizes in whole contracts; `False` (default) sizes in underlying units. |

`is_lots=True` means the quantity is a number of contracts, and the position's unit count is
`quantity * contract_size`. With `is_lots=False` the quantity is already in underlying units.

## How fills work

The `SimulationBroker` fills every open order during the broker step of the **same** pulse that
`on_update()` placed it on. The resulting `Trade.open_datetime` equals that pulse's `last_pulse`, and
the trade is priced at the market data for that pulse.

> [!NOTE]
>
> **Same-pulse fills, no slippage**
>
> There is no one-pulse delay and no slippage: an order placed this pulse is filled this pulse at the
> price you just looked at. Only market orders exist. To model a delay, place the order on a later
> pulse yourself. (The `Broker.create_order` docstring still reads "next pulse"; the simulation broker
> actually fills same-pulse.)
>
> Filling at the close you just saw is the standard "trade-at-close" assumption. It is harmless for
> slow, path-driven strategies (monthly rolls, theta harvesting), where the underlying's move dwarfs
> the entry tick; it matters more for signal-timing or higher-frequency strategies, which implicitly
> assume they can transact at the exact print their signal fired on. For those, place the order on the
> next pulse, or set `fill_price=` to apply a slippage haircut.

## The Trade

A filled `Order` becomes a `Trade`, which the portfolio reprices every pulse.

| Member | Meaning |
| - | - |
| `is_open` | `True` until the trade is closed. |
| `quantity` / `sign` | Signed size and its direction (`+1` / `-1`). |
| `tags` / `has_tag(...)` / `add_tag(...)` | Labels for grouping and querying. |
| `pnl` | Cumulative dollar PnL since open. |
| `pnl_pct` | `pnl / abs(equity_at_open)` - return on the equity held when the trade opened. |
| `pnl_pct_of_initial_equity` | `pnl / abs(initial_equity)` - return on a fixed base, comparable across trades. |
| `close(pulse_index)` | Mark the trade to close at the end of the current pulse. |

Each trade keeps per-pulse histories aligned to its `datetimes`: `abs_pnl_history`, `pct_pnl_history`,
`pulse_abs_pnl_history`, `price_history`, `notional_history`, the greek histories with the
`underlying_price_history` and `iv_history` they were taken against, and daily roll-ups
(`daily_abs_pnl_history`, `daily_pct_pnl_history`).

> [!NOTE]
>
> **Closing fills like any other action**
>
> `close(...)` flags the trade; the portfolio books the close at the end of the pulse. An expired
> instrument is closed automatically at its last price.

## Managing trades by tag

Tags set on entry are the handle for managing groups later:

```python theme={null}
self.get_trades_by_tags(["hedge"])      # open trades carrying the tag
self.close_trades_by_tags(["hedge"])     # close every open trade carrying the tag
self.close_all()                         # close every open trade
```

Both query helpers take `match_all` (default `False`): `False` matches a trade with any of the tags,
`True` requires all of them.

**Related:** [Architecture and the pulse loop](https://docs.allasso.ch/dev/pulse/concepts/architecture.md) · [Timing](https://docs.allasso.ch/dev/pulse/concepts/timing.md) ·
[Portfolio, equity and PnL](https://docs.allasso.ch/dev/pulse/concepts/portfolio-pnl.md) · [Greeks](https://docs.allasso.ch/dev/pulse/concepts/greeks.md)


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