# Account snapshots and execution events



Use snapshots to inspect current account state and callbacks to react to actual order changes. These values are created by the framework and are read-only.

[AccountSnapshot](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-accountsnapshot) · [PositionSnapshot](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-positionsnapshot) · [ClosedTradeStats](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-closedtradestats) · [OrderSnapshot](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-ordersnapshot) · [OrderSizingSnapshot](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-ordersizingsnapshot) · [OrderEvent](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-orderevent) · [Fill](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-fill) · [TradeAllocation](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-tradeallocation) · [RunSummary](https://docs.openbacktesting.com/reference/events/#openbacktesting-broker-runsummary)

## Log an execution and inspect the account

```python
from openbacktesting import Backtest, Strategy
from openbacktesting.test import GOOG

class ObserveExecution(Strategy):
    def init(self):
        self.fill_prices = []

    def next(self):
        if self.bar_index == 0:
            self.buy(qty=1)
        elif self.bar_index == 5:
            self.position.close()

    def on_order(self, event):
        order = event.snapshot
        self.log.info(f"{order.order_id}: {order.status}; {order.reason}")

    def on_fill(self, fill):
        self.fill_prices.append(fill.price)
        self.log.info(f"Executed {fill.qty} at {fill.price}; fee {fill.fee}")

    def on_finish(self, summary):
        self.log.info(f"Finished: {summary.reason}; equity {summary.account.equity}")

bt = Backtest(GOOG.iloc[:20], ObserveExecution)
result = bt.run()
print(result["_strategy"].fill_prices)
print(bt.get_logs()[-1])
```

`on_order` receives an event whose **snapshot** contains the order ID/status/reason. `on_fill` receives the actual execution directly. `on_finish` receives the final account and termination reason. A saved snapshot does not change when another fill occurs. Orders submitted in notifications cannot match recursively; `on_start` and `on_finish` do not permit trading.

## Read the current state

Inside `next()`, read `self.account.equity`, `.margin_available`, or `.fees_paid`; use `self.position.snapshot.long_qty/short_qty` for two-sided exposure. `self.closed_trade_stats.win_rate` is a fraction (0.5 means 50%) and is None before any closure. These counts describe closed portions, including partial exits.

## Values returned by trading and callbacks

These are read-only records, not objects you need to construct. `Order.snapshot` and `.sizing` describe status and the original sizing decision. `on_order(event)` receives an `OrderEvent`; `on_fill(fill)` receives a `Fill`. `on_finish(summary)` receives a `RunSummary`. Result ledgers expose the same facts as plain tables. Timestamps/bar positions identify when something happened; IDs join orders, fills, and trade allocations.

<a id="openbacktesting-broker-accountsnapshot"></a>



## AccountSnapshot

Single-currency linear margin account; balance is not securities settlement cash.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-accountsnapshot-balance"></a>`balance` | `float` | Initial balance plus realized gross P/L minus paid fees. |
| <a id="openbacktesting-broker-accountsnapshot-equity"></a>`equity` | `float` | Balance plus unrealized gross P/L. |
| <a id="openbacktesting-broker-accountsnapshot-realized-pnl-gross"></a>`realized_pnl_gross` | `float` | Realized price P/L before fees. |
| <a id="openbacktesting-broker-accountsnapshot-unrealized-pnl-gross"></a>`unrealized_pnl_gross` | `float` | Unrealized price P/L before fees. |
| <a id="openbacktesting-broker-accountsnapshot-fees-paid"></a>`fees_paid` | `float` | Total actual fees charged. |
| <a id="openbacktesting-broker-accountsnapshot-margin-used"></a>`margin_used` | `float` | Gross notional multiplied by the margin fraction. |
| <a id="openbacktesting-broker-accountsnapshot-margin-available"></a>`margin_available` | `float` | Remaining nonnegative margin capacity. |
| <a id="openbacktesting-broker-accountsnapshot-gross-notional"></a>`gross_notional` | `float` | Absolute notional across both directions. |
| <a id="openbacktesting-broker-accountsnapshot-net-notional"></a>`net_notional` | `float` | Signed net notional at the observation price. |

<a id="openbacktesting-broker-positionsnapshot"></a>



## PositionSnapshot

Net position, two-sided gross exposure, and explicit gross and net profit or loss.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-positionsnapshot-net-qty"></a>`net_qty` | `float` | Signed net asset quantity. |
| <a id="openbacktesting-broker-positionsnapshot-gross-qty"></a>`gross_qty` | `float` | Total absolute quantity across open lots. |
| <a id="openbacktesting-broker-positionsnapshot-long-qty"></a>`long_qty` | `float` | Total long quantity. |
| <a id="openbacktesting-broker-positionsnapshot-short-qty"></a>`short_qty` | `float` | Total short quantity. |
| <a id="openbacktesting-broker-positionsnapshot-long-avg-price"></a>`long_avg_price` | `float \| None` | Average entry price of the long leg, or None. |
| <a id="openbacktesting-broker-positionsnapshot-short-avg-price"></a>`short_avg_price` | `float \| None` | Average entry price of the short leg, or None. |
| <a id="openbacktesting-broker-positionsnapshot-avg-price"></a>`avg_price` | `float \| None` | Common entry basis, or None for flat/hedged exposure. |
| <a id="openbacktesting-broker-positionsnapshot-gross-notional"></a>`gross_notional` | `float` | Absolute notional across both directions. |
| <a id="openbacktesting-broker-positionsnapshot-net-notional"></a>`net_notional` | `float` | Signed net notional at the observation price. |
| <a id="openbacktesting-broker-positionsnapshot-unrealized-pnl-gross"></a>`unrealized_pnl_gross` | `float` | Unrealized price P/L before fees. |
| <a id="openbacktesting-broker-positionsnapshot-unrealized-pnl-net"></a>`unrealized_pnl_net` | `float` | Unrealized P/L after remaining entry fees. |
| <a id="openbacktesting-broker-positionsnapshot-entry-fees-remaining"></a>`entry_fees_remaining` | `float` | Entry fees allocated to still-open quantity. |
| <a id="openbacktesting-broker-positionsnapshot-return-fraction"></a>`return_fraction` | `float \| None` | Net return as a fraction; None if no common basis exists. |

### Attributes

| Attribute | Meaning |
| --- | --- |
| <a id="openbacktesting-broker-positionsnapshot-has-exposure"></a>`has_exposure` | A two-sided net-zero position still has gross exposure. |

<a id="openbacktesting-broker-closedtradestats"></a>



## ClosedTradeStats

Cumulative closed portions as of the read; fees are allocated, and unrealized profit or loss is excluded.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-closedtradestats-closed-count"></a>`closed_count` | `int` | Number of closed fragments, including partial exits. |
| <a id="openbacktesting-broker-closedtradestats-win-count"></a>`win_count` | `int` | Closed fragments with positive net P/L. |
| <a id="openbacktesting-broker-closedtradestats-loss-count"></a>`loss_count` | `int` | Closed fragments with negative net P/L. |
| <a id="openbacktesting-broker-closedtradestats-even-count"></a>`even_count` | `int` | Closed fragments with exactly zero net P/L. |
| <a id="openbacktesting-broker-closedtradestats-winning-profit"></a>`winning_profit` | `float` | Sum of positive closed-fragment net P/L. |
| <a id="openbacktesting-broker-closedtradestats-losing-amount"></a>`losing_amount` | `float` | Absolute sum of negative closed-fragment net P/L. |
| <a id="openbacktesting-broker-closedtradestats-net-profit"></a>`net_profit` | `float` | Total closed-fragment net P/L. |
| <a id="openbacktesting-broker-closedtradestats-average-profit"></a>`average_profit` | `float \| None` | Mean net P/L per closed fragment, or None without closures. |
| <a id="openbacktesting-broker-closedtradestats-win-rate"></a>`win_rate` | `float \| None` | Winning fraction from 0 to 1, or None without closures. |

<a id="openbacktesting-broker-ordersnapshot"></a>



## OrderSnapshot

Frozen order values at a state transition.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-ordersnapshot-order-id"></a>`order_id` | `str` | Order identifier within the run. |
| <a id="openbacktesting-broker-ordersnapshot-status"></a>`status` | `OrderStatus` | Current OrderStatus value. |
| <a id="openbacktesting-broker-ordersnapshot-filled-qty"></a>`filled_qty` | `float` | Executed quantity so far. |
| <a id="openbacktesting-broker-ordersnapshot-remaining-qty"></a>`remaining_qty` | `float` | Quantity still awaiting execution. |
| <a id="openbacktesting-broker-ordersnapshot-avg-fill-price"></a>`avg_fill_price` | `float \| None` | Average execution price, or None before a fill. |
| <a id="openbacktesting-broker-ordersnapshot-reason"></a>`reason` | `str \| None` | Reason for the recorded decision or termination. |
| <a id="openbacktesting-broker-ordersnapshot-triggered"></a>`triggered` | `bool` | Whether the stop trigger has activated. |

<a id="openbacktesting-broker-ordersizingsnapshot"></a>



## OrderSizingSnapshot

Sizing basis frozen at submission; budgets do not guarantee actual fill notional or fees.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-ordersizingsnapshot-mode"></a>`mode` | `Literal['qty', 'amount', 'percent']` | qty, amount, or percent. |
| <a id="openbacktesting-broker-ordersizingsnapshot-source"></a>`source` | `Literal['explicit', 'default']` | Whether sizing was explicit or supplied by the default. |
| <a id="openbacktesting-broker-ordersizingsnapshot-value"></a>`value` | `float` | Original size value; percent uses percentage points (20 means 20%). |
| <a id="openbacktesting-broker-ordersizingsnapshot-equity"></a>`equity` | `float` | Balance plus unrealized gross P/L. |
| <a id="openbacktesting-broker-ordersizingsnapshot-reference-price"></a>`reference_price` | `float` | Price used to calculate the requested quantity. |
| <a id="openbacktesting-broker-ordersizingsnapshot-budget"></a>`budget` | `float \| None` | Notional or risk budget; None for a pure quantity request. |
| <a id="openbacktesting-broker-ordersizingsnapshot-qty"></a>`qty` | `float` | Asset quantity in native units. |

<a id="openbacktesting-broker-orderevent"></a>



## OrderEvent

Immutable order event with time and phase.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-orderevent-sequence"></a>`sequence` | `int` | Monotonically ordered event position within the run. |
| <a id="openbacktesting-broker-orderevent-bar-index"></a>`bar_index` | `int` | Zero-based input bar position. |
| <a id="openbacktesting-broker-orderevent-timestamp"></a>`timestamp` | `object` | Market-data index value at the event. |
| <a id="openbacktesting-broker-orderevent-phase"></a>`phase` | `str` | Execution phase that produced the event. |
| <a id="openbacktesting-broker-orderevent-snapshot"></a>`snapshot` | `OrderSnapshot` | Frozen OrderSnapshot containing order_id, status, and reason. |

<a id="openbacktesting-broker-fill"></a>



## Fill

An actual execution; fees are recorded exactly once here.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-fill-fill-id"></a>`fill_id` | `str` | Actual execution identifier. |
| <a id="openbacktesting-broker-fill-order-id"></a>`order_id` | `str` | Order identifier within the run. |
| <a id="openbacktesting-broker-fill-sequence"></a>`sequence` | `int` | Monotonically ordered event position within the run. |
| <a id="openbacktesting-broker-fill-side"></a>`side` | `str` | Buy or sell direction. |
| <a id="openbacktesting-broker-fill-qty"></a>`qty` | `float` | Asset quantity in native units. |
| <a id="openbacktesting-broker-fill-price"></a>`price` | `float` | Actual execution price. |
| <a id="openbacktesting-broker-fill-fee"></a>`fee` | `float` | Fee charged or allocated to this execution. |
| <a id="openbacktesting-broker-fill-bar-index"></a>`bar_index` | `int` | Zero-based input bar position. |
| <a id="openbacktesting-broker-fill-timestamp"></a>`timestamp` | `object` | Market-data index value at the event. |
| <a id="openbacktesting-broker-fill-phase"></a>`phase` | `str` | Execution phase that produced the event. |
| <a id="openbacktesting-broker-fill-reason"></a>`reason` | `str` | Reason for the recorded decision or termination. |

<a id="openbacktesting-broker-tradeallocation"></a>



## TradeAllocation

Allocation of an execution quantity to entry lots or closed portions.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-tradeallocation-allocation-id"></a>`allocation_id` | `str` | Identifier of this allocation between a fill and a trade. |
| <a id="openbacktesting-broker-tradeallocation-fill-id"></a>`fill_id` | `str` | Actual execution identifier. |
| <a id="openbacktesting-broker-tradeallocation-trade-id"></a>`trade_id` | `str` | Lot identifier shared by its partial exits. |
| <a id="openbacktesting-broker-tradeallocation-entry-fill-id"></a>`entry_fill_id` | `str` | Execution that opened the lot. |
| <a id="openbacktesting-broker-tradeallocation-kind"></a>`kind` | `str` | Whether the fill allocation opens or closes a lot. |
| <a id="openbacktesting-broker-tradeallocation-qty"></a>`qty` | `float` | Asset quantity in native units. |
| <a id="openbacktesting-broker-tradeallocation-fee"></a>`fee` | `float` | Fee charged or allocated to this execution. |
| <a id="openbacktesting-broker-tradeallocation-entry-fee"></a>`entry_fee` | `float` | Entry fee allocated to this closed portion. |
| <a id="openbacktesting-broker-tradeallocation-realized-pnl-gross"></a>`realized_pnl_gross` | `float` | Realized price P/L before fees. |

<a id="openbacktesting-broker-runsummary"></a>



## RunSummary

Frozen summary for the finish hook; error text does not replace the original exception.

| Attribute | Type | Meaning |
| --- | --- | --- |
| <a id="openbacktesting-broker-runsummary-reason"></a>`reason` | `str` | Reason for the recorded decision or termination. |
| <a id="openbacktesting-broker-runsummary-account"></a>`account` | `AccountSnapshot` | Final AccountSnapshot for the run. |
| <a id="openbacktesting-broker-runsummary-error"></a>`error` | `str \| None` | Failure text, or None when no error was recorded. |

[Orders and positions](https://docs.openbacktesting.com/reference/trading/index.md) · [Strategy](https://docs.openbacktesting.com/reference/strategy/index.md) · [Results](https://docs.openbacktesting.com/guides/results/index.md)