topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/execution/sim_broker.py

@@ -0,0 +1,1436 @@
+"""SimBroker: deterministic execution simulation behind the ``Broker`` protocol.
+
+Implements the SAME structural protocol ``AsyncTopstepClient`` satisfies, so a
+strategy wired to a SimBroker runs unchanged live. The broker owns order
+lifecycle, OCO/bracket linkage, trailing-stop recomputation, position netting,
+P&L (exact Decimal), and wires every equity change through the Combine rule
+kernel — including intrabar breach detection along the deterministic price
+path, and forced liquidation with its own (worse) slippage plus Topstep's
+$10/contract automatic-liquidation fee.
+
+Accounting: positions are FIFO lots with an exact Decimal COST BASIS. Every
+stored lot price is on the tick grid; unrealized P&L is division-free
+(``core.money.position_unrealized``), so scale-ins can never produce an
+off-grid average or rounding dust. Per-half-turn ``profit_and_loss`` uses FIFO
+lot attribution (documented assumption pending gateway calibration —
+docs/DESIGN.md §15).
+
+Key correctness properties:
+  - No look-ahead: orders participate in a bar only if accepted at/before its
+    open (the fill model's ``accepted_ts`` firewall); trailing stops likewise
+    only ratchet from bars the order actually lived through; bracket children
+    created on an intrabar fill first participate the NEXT bar.
+  - Deterministic intrabar resolution: fills and rule-breach liquidations are
+    ordered along ONE shared pessimistic price path by TRIGGER level (never by
+    slippage-adjusted fill prices), and equity is re-checked AT each fill
+    point after it applies (slippage + fees can themselves breach).
+  - Every rejection is the SDK's ``APIError`` with the gateway's error code.
+
+Documented Tier-0 divergences from live (see docs/DESIGN.md §13.8): market
+orders — including ``positions.close``/``partial_close`` — fill at the NEXT
+bar's open (not instantly); stored bars are not live tape-built bars;
+``wait_for_fill`` raises ``UnsupportedInBacktestError``; STOP_LIMIT and
+JOIN_BID/JOIN_ASK are rejected (they need quote data, Tier-1+).
+"""
+
+# pyright: reportPrivateUsage=false
+# (the Sim*Api facades cooperate with SimBroker internals within this module by design)
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any, Literal
+
+from topstep_sdk import (
+    AggregateBarUnit,
+    APIError,
+    HalfTradeModel,
+    OrderModel,
+    OrderSide,
+    OrderStatus,
+    OrderType,
+    PlaceOrderBracket,
+    PositionModel,
+    PositionType,
+)
+from topstep_sdk.models.history import AggregateBarModel
+
+from ..core.ids import IdGenerator
+from ..core.instruments import InstrumentSpec
+from ..core.money import is_on_grid, position_unrealized, round_to_tick, to_ticks
+from ..core.time import TOPSTEP_SESSION, SessionTimes, dt_to_ns, ns_to_dt, trading_day_of
+from ..fills.path import build_path
+from ..protocols import (
+    Bar,
+    Fill,
+    FillModel,
+    Liquidity,
+    MarketContext,
+    PricePath,
+    WorkingOrder,
+)
+from ..rules.kernel import Breach, BreachKind, CombineKernel, Verdict
+from .rejections import UnsupportedInBacktestError, reject_cancel, reject_modify, reject_place
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from ..protocols import Clock, FeeModel
+
+__all__ = [
+    "SimBroker",
+    "SimBrokerConfig",
+    "SimHistoryApi",
+    "SimOrderApi",
+    "SimPositionApi",
+    "UserEvent",
+]
+
+UserEvent = OrderModel | HalfTradeModel | PositionModel
+"""Events queued for strategy dispatch (mirrors the SDK user hub payloads)."""
+
+_TERMINAL = {
+    OrderStatus.FILLED,
+    OrderStatus.CANCELLED,
+    OrderStatus.REJECTED,
+    OrderStatus.EXPIRED,
+}
+
+
+class SimBrokerConfig:
+    """Tunables that are broker-level (not fill-model-level)."""
+
+    __slots__ = (
+        "forced_liq_slippage_ticks",
+        "history_depth",
+        "liquidation_fee_per_contract",
+        "max_trail_ticks",
+    )
+
+    def __init__(
+        self,
+        *,
+        forced_liq_slippage_ticks: int = 2,
+        liquidation_fee_per_contract: Decimal = Decimal("10"),
+        max_trail_ticks: int = 1000,
+        history_depth: int = 20_000,
+    ) -> None:
+        self.forced_liq_slippage_ticks = forced_liq_slippage_ticks
+        self.liquidation_fee_per_contract = liquidation_fee_per_contract
+        self.max_trail_ticks = max_trail_ticks
+        self.history_depth = history_depth
+
+
+class _Lot:
+    """One FIFO entry lot; ``price`` is always on the tick grid."""
+
+    __slots__ = ("price", "qty")
+
+    def __init__(self, price: Decimal, qty: int) -> None:
+        self.price = price
+        self.qty = qty
+
+
+class _Position:
+    """Netted position as FIFO lots with an exact cost basis (no divisions)."""
+
+    __slots__ = ("contract_id", "direction", "lots", "opened_ts", "position_id")
+
+    def __init__(
+        self,
+        *,
+        position_id: int,
+        contract_id: str,
+        direction: int,
+        opened_ts: int,
+    ) -> None:
+        self.position_id = position_id
+        self.contract_id = contract_id
+        self.direction = direction  # +1 long, -1 short
+        self.lots: list[_Lot] = []
+        self.opened_ts = opened_ts
+
+    @property
+    def qty(self) -> int:
+        return sum(lot.qty for lot in self.lots)
+
+    @property
+    def cost(self) -> Decimal:
+        """Exact sum(entry_price * qty) over open lots."""
+        return sum((lot.price * lot.qty for lot in self.lots), Decimal(0))
+
+    def display_avg(self, spec: InstrumentSpec) -> Decimal:
+        """Average entry for display (``PositionModel.average_price``).
+
+        Quantized to tick/100 so a repeating decimal (three lots averaging to
+        thirds) never leaks into a reported field; NEVER used in P&L math.
+        """
+        quantum = spec.tick_size / 100
+        return (self.cost / self.qty).quantize(quantum)
+
+
+class _PendingBrackets:
+    __slots__ = ("sl_ticks", "tp_ticks")
+
+    def __init__(self, sl_ticks: int | None, tp_ticks: int | None) -> None:
+        self.sl_ticks = sl_ticks  # signed offset from entry
+        self.tp_ticks = tp_ticks
+
+
+def _as_decimal(value: float | Decimal) -> Decimal:
+    return value if isinstance(value, Decimal) else Decimal(str(value))
+
+
+def _side_dir(side: OrderSide | int) -> int:
+    return 1 if int(side) == int(OrderSide.BUY) else -1
+
+
+class SimBroker:
+    """Deterministic simulated venue satisfying the ``Broker`` protocol."""
+
+    def __init__(
+        self,
+        *,
+        account_id: int,
+        instruments: Mapping[str, InstrumentSpec],
+        fill_model: FillModel,
+        fee_model: FeeModel,
+        kernel: CombineKernel,
+        clock: Clock,
+        ids: IdGenerator | None = None,
+        config: SimBrokerConfig | None = None,
+        session: SessionTimes = TOPSTEP_SESSION,
+    ) -> None:
+        self._account_id = account_id
+        self._instruments = dict(instruments)
+        self._fill_model = fill_model
+        self._fee_model = fee_model
+        self._kernel = kernel
+        self._clock = clock
+        self._ids = ids or IdGenerator()
+        self._config = config or SimBrokerConfig()
+        self._session = session
+
+        self._balance: Decimal = kernel.params.starting_balance
+        self._orders: dict[int, WorkingOrder] = {}
+        self._brackets: dict[int, _PendingBrackets] = {}
+        self._oco: dict[int, int] = {}  # order id -> OCO sibling id (both directions)
+        self._positions: dict[str, _Position] = {}
+        self._last_bar: dict[str, Bar] = {}
+        self._history: dict[str, list[Bar]] = {}
+        self._events: list[UserEvent] = []
+        self._trades: list[HalfTradeModel] = []
+        # Rejected placements, by gateway error_code. A strategy that silently
+        # swallows APIError (the SymbolStrategy sugar routes it to on_reject,
+        # whose default is a no-op) otherwise produces a clean-looking report
+        # in which nothing was ever executed. Surfaced on BacktestResult.
+        self._rejections: dict[int, int] = {}
+        self._used_tags: set[str] = set()
+        self._halted = False
+
+    # ------------------------------------------------------------------
+    # Broker protocol surface
+    # ------------------------------------------------------------------
+
+    @property
+    def orders(self) -> SimOrderApi:
+        return SimOrderApi(self)
+
+    @property
+    def positions(self) -> SimPositionApi:
+        return SimPositionApi(self)
+
+    @property
+    def history(self) -> SimHistoryApi:
+        return SimHistoryApi(self)
+
+    @property
+    def rejections(self) -> dict[int, int]:
+        """Count of rejected placements, keyed by gateway ``error_code``."""
+        return dict(self._rejections)
+
+    # ------------------------------------------------------------------
+    # Engine-facing surface
+    # ------------------------------------------------------------------
+
+    @property
+    def account_id(self) -> int:
+        return self._account_id
+
+    @property
+    def instruments(self) -> dict[str, InstrumentSpec]:
+        return dict(self._instruments)
+
+    @property
+    def balance(self) -> Decimal:
+        return self._balance
+
+    @property
+    def kernel(self) -> CombineKernel:
+        return self._kernel
+
+    @property
+    def trades(self) -> tuple[HalfTradeModel, ...]:
+        return tuple(self._trades)
+
+    @property
+    def dead(self) -> bool:
+        return self._kernel.verdict is Verdict.FAILED or self._halted
+
+    def drain_events(self) -> list[UserEvent]:
+        events, self._events = self._events, []
+        return events
+
+    def equity(self) -> Decimal:
+        """Realized balance + open P&L marked at each contract's last close."""
+        total = self._balance
+        for cid, pos in self._positions.items():
+            last = self._last_bar.get(cid)
+            if last is not None:
+                total += self._unrealized(pos, last.close)
+        return total
+
+    def on_bar(self, bar: Bar) -> None:
+        """Phase-1 matching: trailing ratchet, path walk with interleaved
+
+        fill/breach resolution, then the end-of-bar equity check.
+        """
+        cid = bar.bar_type.contract_id
+        spec = self._instruments.get(cid)
+        if spec is None:
+            raise KeyError(f"bar for unknown contract {cid!r}: register it in `instruments`")
+
+        prev = self._last_bar.get(cid)
+        self._ratchet_trailing(cid, prev, spec)
+
+        if self._kernel.verdict is not Verdict.FAILED:
+            self._walk_bar(bar, spec, prev)
+
+        self._last_bar[cid] = bar
+        bucket = self._history.setdefault(cid, [])
+        bucket.append(bar)
+        if len(bucket) > self._config.history_depth:
+            del bucket[: len(bucket) - self._config.history_depth]
+
+    def flatten_all(self, ts_ns: int, *, reason: str) -> None:
+        """Topstep auto-flatten enforcement (16:10 ET / day roll): market-dump
+
+        every position with forced slippage AND the automatic-liquidation fee,
+        then cancel every working order. Strategy-initiated exits should
+        happen earlier via ``positions.close`` (which does NOT pay this fee).
+        """
+        for cid in list(self._positions):
+            last = self._last_bar.get(cid)
+            if last is None:  # pragma: no cover - position implies a seen bar
+                continue
+            self._close_position_at(
+                cid,
+                last.close,
+                ts_ns,
+                note=reason,
+                slippage_ticks=self._config.forced_liq_slippage_ticks,
+                liquidation=True,
+            )
+        self._cancel_all_working(ts_ns)
+
+    def session_close(self, ts_ns: int) -> None:
+        """EOD hook: report the closed balance to the rule kernel (MLL ratchet)."""
+        self._kernel.on_session_close(ts_ns, self._balance)
+
+    # ------------------------------------------------------------------
+    # Bar walk: deterministic intrabar fill/breach interleaving
+    # ------------------------------------------------------------------
+
+    def _walk_bar(self, bar: Bar, spec: InstrumentSpec, prev: Bar | None) -> None:
+        cid = bar.bar_type.contract_id
+        pos = self._positions.get(cid)
+        path = build_path(bar, 0 if pos is None else pos.direction)
+        ctx = MarketContext(
+            ts_event=bar.ts_event,
+            ts_init=bar.ts_init,
+            instrument=spec,
+            bar=bar,
+            prev_close=None if prev is None else prev.close,
+        )
+
+        # Candidate fills are computed once against the bar-start order book
+        # (no new orders can join mid-bar: children created on an intrabar fill
+        # carry accepted_ts stamps that defer them to the next bar). Ordering
+        # is by TRIGGER level along the path — never slippage-adjusted prices.
+        candidates: list[tuple[tuple[int, Decimal], Fill]] = []
+        for order in self._orders_on(cid):
+            for fill in self._fill_model.try_fill(order, ctx, path):
+                trigger = fill.trigger_price if fill.trigger_price is not None else fill.price
+                candidates.append((self._path_key(path, fill.seq, trigger), fill))
+        candidates.sort(key=lambda item: (item[0][0], item[0][1], item[1].order_id))
+
+        cursor: tuple[int, Decimal] = (0, Decimal(0))
+        for key, fill in candidates:
+            order = self._orders.get(fill.order_id)
+            if order is None or order.status is not OrderStatus.OPEN:
+                continue  # cancelled mid-walk (OCO sibling)
+            if self._breach_before(bar, spec, path, cursor, key):
+                return  # account liquidated (MLL) or day-locked flatten (DLL)
+            self._apply_fill(order, fill, spec)
+            cursor = key
+            if self.dead:
+                return
+            # Slippage + fees from the fill itself can push equity through a
+            # threshold AT this very point — check before walking on.
+            if self._breach_at_price(bar, spec, fill.price):
+                return
+        end_key = (len(path) - 1, Decimal(0))
+        self._breach_before(bar, spec, path, cursor, end_key)
+
+    def _path_key(self, path: PricePath, seq: int, price: Decimal) -> tuple[int, Decimal]:
+        """Total order along the path: (segment index, distance from segment start)."""
+        start = path[seq].price
+        return (seq, abs(price - start))
+
+    def _breach_at_price(self, bar: Bar, spec: InstrumentSpec, mark: Decimal) -> bool:
+        """Equity check with the CURRENT state marking this contract at ``mark``."""
+        cid = bar.bar_type.contract_id
+        pos = self._positions.get(cid)
+        equity = self._balance + self._unrealized_except(cid)
+        if pos is not None:
+            equity += self._unrealized(pos, mark)
+        breach = self._kernel.check_equity(bar.ts_event, equity)
+        if breach is not None:
+            self._execute_breach(breach, cid, mark if pos is not None else None, bar.ts_event)
+            return True
+        return False
+
+    def _breach_before(
+        self,
+        bar: Bar,
+        spec: InstrumentSpec,
+        path: PricePath,
+        cursor: tuple[int, Decimal],
+        until: tuple[int, Decimal],
+    ) -> bool:
+        """Detect and execute the FIRST rule breach at/before ``until``.
+
+        Walks path segments from ``cursor`` to ``until`` with the CURRENT
+        position/balance, finds the earliest grid price where equity reaches
+        the MLL floor (or DLL threshold), and executes the forced action
+        there. Ties at ``until`` (a fill at the exact breach price) resolve to
+        the BREACH — Topstep liquidates the moment equity touches the limit
+        (documented conservative choice). Returns True if action was taken.
+        """
+        cid = bar.bar_type.contract_id
+        pos = self._positions.get(cid)
+
+        if pos is None:
+            # Flat in this contract: equity is constant along the path.
+            return self._breach_at_price(bar, spec, bar.open)
+
+        other_unreal = self._unrealized_except(cid)
+        last_seg = min(until[0], len(path) - 2)
+        for seg in range(cursor[0], last_seg + 1):
+            seg_start = path[seg].price
+            seg_end = path[seg + 1].price
+            hit = self._segment_trigger(pos, spec, other_unreal, seg_start, seg_end)
+            if hit is None:
+                continue
+            distance = abs(hit - seg_start)
+            key = (seg, distance)
+            if key < cursor:
+                continue  # already walked past this point
+            if key > until:
+                return False  # first breach lies beyond the next fill
+            equity = self._balance + other_unreal + self._unrealized(pos, hit)
+            breach = self._kernel.check_equity(bar.ts_event, equity)
+            if breach is not None:
+                self._execute_breach(breach, cid, hit, bar.ts_event)
+                return True
+        return False
+
+    def _active_thresholds(self) -> list[Decimal]:
+        """Equity levels at which a rule action fires (MLL floor, DLL line)."""
+        levels = [self._kernel.floor]
+        dll = self._kernel.params.dll
+        if dll is not None and not self._kernel.day_locked:
+            levels.append(self._kernel.day_start_balance - dll)
+        return levels
+
+    def _segment_trigger(
+        self,
+        pos: _Position,
+        spec: InstrumentSpec,
+        other_unreal: Decimal,
+        seg_start: Decimal,
+        seg_end: Decimal,
+    ) -> Decimal | None:
+        """Earliest price along [seg_start -> seg_end] where equity reaches an
+
+        active threshold, or None. Prices print on the tick grid, so the
+        trigger is the first grid level whose equity is at/below a threshold.
+        Solved from the exact cost basis with a SINGLE Decimal division, so a
+        threshold landing exactly on the grid is computed exactly.
+        """
+        point_value = spec.point_value
+        qty = pos.qty
+        cost = pos.cost
+        direction = pos.direction
+        best: Decimal | None = None
+        descending = seg_end < seg_start
+        for level in self._active_thresholds():
+            # equity(p) = balance + other + (p*qty - cost)*dir*pv  <= level
+            # =>  p*  =  (level - balance - other + cost*dir*pv) / (qty*dir*pv)
+            numerator = level - self._balance - other_unreal + cost * direction * point_value
+            raw = numerator / (qty * direction * point_value)
+            if direction > 0:
+                trigger = round_to_tick(raw, spec.tick_size, mode="down")
+                if seg_start <= trigger:
+                    hit = seg_start  # already at/below the threshold entering the segment
+                elif descending and seg_end <= trigger:
+                    hit = trigger  # crossed while moving down
+                else:
+                    continue
+            else:
+                trigger = round_to_tick(raw, spec.tick_size, mode="up")
+                if seg_start >= trigger:
+                    hit = seg_start
+                elif not descending and seg_end >= trigger:
+                    hit = trigger
+                else:
+                    continue
+            if best is None or abs(hit - seg_start) < abs(best - seg_start):
+                best = hit
+        return best
+
+    def _execute_breach(
+        self, breach: Breach, cid: str, trigger_price: Decimal | None, ts_ns: int
+    ) -> None:
+        """Forced action: MLL -> liquidate everything (account dead);
+
+        DLL -> flatten and lock the day (account survives). Both are market
+        dumps: forced slippage + the automatic-liquidation fee apply.
+        """
+        slip = self._config.forced_liq_slippage_ticks
+        note = "forced_liquidation" if breach.kind is BreachKind.MLL else "dll_flatten"
+        pos = self._positions.get(cid)
+        if pos is not None and trigger_price is not None:
+            self._close_position_at(
+                cid, trigger_price, ts_ns, note=note, slippage_ticks=slip, liquidation=True
+            )
+        for other_cid in list(self._positions):
+            last = self._last_bar.get(other_cid)
+            if last is not None:
+                self._close_position_at(
+                    other_cid, last.close, ts_ns, note=note, slippage_ticks=slip, liquidation=True
+                )
+        self._cancel_all_working(ts_ns)
+        if breach.kind is BreachKind.MLL:
+            self._halted = True
+
+    # ------------------------------------------------------------------
+    # Fill application, netting, P&L
+    # ------------------------------------------------------------------
+
+    def _apply_fill(self, order: WorkingOrder, fill: Fill, spec: InstrumentSpec) -> None:
+        if not is_on_grid(fill.price, spec.tick_size):  # hard invariant
+            raise AssertionError(f"fill off tick grid: {fill.price} tick={spec.tick_size}")
+
+        qty = fill.qty
+        if order.reduce_only:
+            # Reduce-only orders (bracket children, position closes) can never
+            # open or flip exposure: clamp to the live position, cancel if none.
+            pos = self._positions.get(order.contract_id)
+            if pos is None or pos.direction == _side_dir(order.side):
+                self._cancel_order_internal(order.order_id, fill.ts_event)
+                return
+            qty = min(qty, pos.qty)
+
+        fees, commissions = self._fee_model.fee(spec, order.side, qty, fill.liquidity)
+        realized = self._net_into_position(order, fill.price, qty, fill.ts_event, spec)
+        if realized is not None:
+            self._balance += realized
+        self._balance -= fees + commissions
+
+        order.filled_qty += qty
+        if order.avg_fill_price is None:
+            order.avg_fill_price = fill.price
+        else:  # Tier-0 emits single fills; weighted for future partial-fill tiers
+            total = order.filled_qty
+            prior = order.avg_fill_price * (total - qty)
+            order.avg_fill_price = ((prior + fill.price * qty) / total).quantize(
+                spec.tick_size / 100
+            )
+        if order.remaining == 0 or order.reduce_only:
+            order.status = OrderStatus.FILLED
+        self._emit_order(order)
+
+        trade = HalfTradeModel(
+            id=self._ids.next(),
+            account_id=self._account_id,
+            contract_id=order.contract_id,
+            price=fill.price,
+            fees=fees,
+            side=order.side,
+            size=qty,
+            voided=False,
+            order_id=order.order_id,
+            creation_timestamp=ns_to_dt(fill.ts_event),
+            profit_and_loss=realized,
+            commissions=commissions,
+        )
+        self._trades.append(trade)
+        self._events.append(trade)
+        self._kernel.on_trade_activity(fill.ts_event)
+
+        sibling_id = self._oco.get(order.order_id)
+        if sibling_id is not None:
+            self._cancel_order_internal(sibling_id, fill.ts_event)
+
+        pending = self._brackets.pop(order.order_id, None)
+        if pending is not None and order.status is OrderStatus.FILLED:
+            self._create_bracket_children(order, fill, spec, pending)
+
+        pos = self._positions.get(order.contract_id)
+        if pos is None:
+            self._cancel_reduce_only(order.contract_id, fill.ts_event)
+        else:
+            self._emit_position(pos, spec)
+
+    def _net_into_position(
+        self, order: WorkingOrder, price: Decimal, qty: int, ts_event: int, spec: InstrumentSpec
+    ) -> Decimal | None:
+        """Apply a fill to the netted FIFO position. Returns gross realized P&L
+
+        for the closing portion (None for a pure opening fill). FIFO lot
+        attribution keeps every stored price on-grid and every P&L exact.
+        """
+        cid = order.contract_id
+        fill_dir = _side_dir(order.side)
+        pos = self._positions.get(cid)
+
+        if pos is None or pos.direction == fill_dir:
+            if pos is None:
+                pos = _Position(
+                    position_id=self._ids.next(),
+                    contract_id=cid,
+                    direction=fill_dir,
+                    opened_ts=ts_event,
+                )
+                self._positions[cid] = pos
+            pos.lots.append(_Lot(price, qty))
+            return None
+
+        realized = Decimal(0)
+        remaining = qty
+        point_value = spec.point_value
+        while remaining > 0 and pos.lots:
+            lot = pos.lots[0]
+            closed = min(remaining, lot.qty)
+            realized += (price - lot.price) * pos.direction * closed * point_value
+            lot.qty -= closed
+            remaining -= closed
+            if lot.qty == 0:
+                pos.lots.pop(0)
+        if not pos.lots:
+            del self._positions[cid]
+            if remaining > 0:  # flip: remainder opens the other way at fill price
+                flipped = _Position(
+                    position_id=self._ids.next(),
+                    contract_id=cid,
+                    direction=fill_dir,
+                    opened_ts=ts_event,
+                )
+                flipped.lots.append(_Lot(price, remaining))
+                self._positions[cid] = flipped
+        return realized
+
+    def _close_position_at(
+        self,
+        cid: str,
+        ref_price: Decimal,
+        ts_ns: int,
+        *,
+        note: str,
+        slippage_ticks: int = 0,
+        liquidation: bool = False,
+    ) -> None:
+        """Immediate market close of the whole position, ``slippage_ticks``
+
+        adverse to the reference price. ``liquidation=True`` adds Topstep's
+        $10/contract automatic-liquidation fee. Used ONLY by enforcement paths
+        (16:10 flatten, MLL/DLL breach) — strategy closes go through resting
+        reduce-only market orders like any other order.
+        """
+        pos = self._positions.get(cid)
+        if pos is None:
+            return
+        spec = self._instruments[cid]
+        mode: Literal["down", "up"] = "down" if pos.direction > 0 else "up"
+        px = round_to_tick(ref_price, spec.tick_size, mode=mode)
+        px -= pos.direction * slippage_ticks * spec.tick_size
+        side = OrderSide.SELL if pos.direction > 0 else OrderSide.BUY
+        qty = pos.qty
+        order = WorkingOrder(
+            order_id=self._ids.next(),
+            account_id=self._account_id,
+            contract_id=cid,
+            side=side,
+            type=OrderType.MARKET,
+            size=qty,
+            accepted_ts=ts_ns,
+            reduce_only=True,
+            custom_tag=note,
+        )
+        self._orders[order.order_id] = order
+
+        fees, commissions = self._fee_model.fee(spec, side, qty, Liquidity.TAKER)
+        if liquidation:
+            fees += self._config.liquidation_fee_per_contract * qty
+        realized = self._net_into_position(order, px, qty, ts_ns, spec)
+        if realized is not None:
+            self._balance += realized
+        self._balance -= fees + commissions
+        order.filled_qty = qty
+        order.avg_fill_price = px
+        order.status = OrderStatus.FILLED
+        self._emit_order(order)
+        trade = HalfTradeModel(
+            id=self._ids.next(),
+            account_id=self._account_id,
+            contract_id=cid,
+            price=px,
+            fees=fees,
+            side=side,
+            size=qty,
+            voided=False,
+            order_id=order.order_id,
+            creation_timestamp=ns_to_dt(ts_ns),
+            profit_and_loss=realized,
+            commissions=commissions,
+        )
+        self._trades.append(trade)
+        self._events.append(trade)
+        self._kernel.on_trade_activity(ts_ns)
+        self._cancel_reduce_only(cid, ts_ns)
+
+    # ------------------------------------------------------------------
+    # Brackets, trailing, cancellation
+    # ------------------------------------------------------------------
+
+    def _create_bracket_children(
+        self, entry: WorkingOrder, fill: Fill, spec: InstrumentSpec, pending: _PendingBrackets
+    ) -> None:
+        """OCO stop-loss / take-profit children at signed-tick offsets from the
+
+        actual entry fill price. accepted_ts = fill time -> active next bar.
+        Gateway shape: only the TP carries ``linked_order_id`` (-> its SL);
+        the OCO pairing itself lives in the broker's internal map.
+        """
+        sl_id = self._ids.next() if pending.sl_ticks is not None else None
+        tp_id = self._ids.next() if pending.tp_ticks is not None else None
+        exit_side = OrderSide.SELL if _side_dir(entry.side) > 0 else OrderSide.BUY
+
+        if pending.sl_ticks is not None and sl_id is not None:
+            sl = WorkingOrder(
+                order_id=sl_id,
+                account_id=self._account_id,
+                contract_id=entry.contract_id,
+                side=exit_side,
+                type=OrderType.STOP,
+                size=fill.qty,
+                accepted_ts=fill.ts_event,
+                stop_price=fill.price + pending.sl_ticks * spec.tick_size,
+                parent_order_id=entry.order_id,
+                reduce_only=True,
+            )
+            self._orders[sl_id] = sl
+            self._emit_order(sl)
+        if pending.tp_ticks is not None and tp_id is not None:
+            tp = WorkingOrder(
+                order_id=tp_id,
+                account_id=self._account_id,
+                contract_id=entry.contract_id,
+                side=exit_side,
+                type=OrderType.LIMIT,
+                size=fill.qty,
+                accepted_ts=fill.ts_event,
+                limit_price=fill.price + pending.tp_ticks * spec.tick_size,
+                parent_order_id=entry.order_id,
+                linked_order_id=sl_id,  # TP -> SL only (live-verified shape)
+                reduce_only=True,
+            )
+            self._orders[tp_id] = tp
+            self._emit_order(tp)
+        if sl_id is not None and tp_id is not None:
+            self._oco[sl_id] = tp_id
+            self._oco[tp_id] = sl_id
+
+    def _ratchet_trailing(self, cid: str, prev: Bar | None, spec: InstrumentSpec) -> None:
+        """Ratchet trailing stops from the PREVIOUS bar's extremes — but only
+
+        for orders that existed during that bar (``accepted_ts <=
+        prev.ts_event``); extremes from before the order was placed must
+        never move its stop (that would be look-back, not trailing).
+        """
+        if prev is None:
+            return
+        for order in self._orders_on(cid):
+            if order.type is not OrderType.TRAILING_STOP or order.trail_distance_ticks is None:
+                continue
+            if order.accepted_ts > prev.ts_event:
+                continue  # the order did not live through `prev`
+            distance = order.trail_distance_ticks * spec.tick_size
+            current = order.trail_stop_price
+            if order.side is OrderSide.SELL:  # protects a long: trail below highs
+                candidate = prev.high - distance
+                if current is None or candidate > current:
+                    order.trail_stop_price = candidate
+            else:  # protects a short: trail above lows
+                candidate = prev.low + distance
+                if current is None or candidate < current:
+                    order.trail_stop_price = candidate
+
+    def _cancel_order_internal(self, order_id: int, ts_ns: int) -> None:
+        order = self._orders.get(order_id)
+        if order is None or order.status in _TERMINAL:
+            return
+        order.status = OrderStatus.CANCELLED
+        self._brackets.pop(order_id, None)
+        sibling = self._oco.pop(order_id, None)
+        if sibling is not None:
+            self._oco.pop(sibling, None)
+        self._emit_order(order)
+
+    def _cancel_all_working(self, ts_ns: int) -> list[int]:
+        cancelled: list[int] = []
+        for oid, order in list(self._orders.items()):
+            if order.status is OrderStatus.OPEN:
+                self._cancel_order_internal(oid, ts_ns)
+                cancelled.append(oid)
+        return cancelled
+
+    def _cancel_reduce_only(self, cid: str, ts_ns: int) -> None:
+        """Position fully closed: protective/reduce-only orders die with it."""
+        for oid, order in list(self._orders.items()):
+            if order.contract_id == cid and order.reduce_only and order.status is OrderStatus.OPEN:
+                self._cancel_order_internal(oid, ts_ns)
+
+    # ------------------------------------------------------------------
+    # Marks, events, model construction
+    # ------------------------------------------------------------------
+
+    def _unrealized(self, pos: _Position, mark: Decimal) -> Decimal:
+        spec = self._instruments[pos.contract_id]
+        return position_unrealized(
+            cost=pos.cost,
+            qty=pos.qty,
+            mark=mark,
+            direction=pos.direction,
+            point_value=spec.point_value,
+        )
+
+    def _unrealized_except(self, cid: str) -> Decimal:
+        total = Decimal(0)
+        for other_cid, pos in self._positions.items():
+            if other_cid == cid:
+                continue
+            last = self._last_bar.get(other_cid)
+            if last is not None:
+                total += self._unrealized(pos, last.close)
+        return total
+
+    def _orders_on(self, cid: str) -> list[WorkingOrder]:
+        return [
+            o
+            for o in self._orders.values()
+            if o.contract_id == cid and o.status is OrderStatus.OPEN
+        ]
+
+    def _emit_order(self, order: WorkingOrder) -> None:
+        self._events.append(self._order_model(order))
+
+    def _emit_position(self, pos: _Position, spec: InstrumentSpec) -> None:
+        self._events.append(self._position_model(pos, spec))
+
+    def _position_model(self, pos: _Position, spec: InstrumentSpec) -> PositionModel:
+        return PositionModel(
+            id=pos.position_id,
+            account_id=self._account_id,
+            contract_id=pos.contract_id,
+            type=PositionType.LONG if pos.direction > 0 else PositionType.SHORT,
+            size=pos.qty,
+            average_price=pos.display_avg(spec),
+            creation_timestamp=ns_to_dt(pos.opened_ts),
+        )
+
+    def _order_model(self, order: WorkingOrder) -> OrderModel:
+        spec = self._instruments[order.contract_id]
+        trail_ticks = order.trail_distance_ticks
+        return OrderModel(
+            id=order.order_id,
+            account_id=order.account_id,
+            contract_id=order.contract_id,
+            status=order.status,
+            type=order.type,
+            side=order.side,
+            size=order.size,
+            creation_timestamp=ns_to_dt(order.accepted_ts),
+            update_timestamp=self._clock.now(),
+            limit_price=order.limit_price,
+            stop_price=order.stop_price,
+            fill_volume=order.filled_qty,
+            filled_price=order.avg_fill_price,
+            custom_tag=order.custom_tag,
+            trail_distance=trail_ticks,
+            # Live gateway returns the trail DISTANCE as a price offset here,
+            # not the absolute stop level (SDK OrderModel field docs).
+            trail_price=None if trail_ticks is None else trail_ticks * spec.tick_size,
+            parent_order_id=order.parent_order_id,
+            linked_order_id=order.linked_order_id,
+        )
+
+    # ------------------------------------------------------------------
+    # Order entry (validation mirrors the gateway)
+    # ------------------------------------------------------------------
+
+    def _pretrade_checks(self, contract_id: str, size: int) -> InstrumentSpec:
+        spec = self._instruments.get(contract_id)
+        if spec is None:
+            reject_place(8, f"unknown contract {contract_id!r}")
+        if size <= 0:
+            reject_place(2, f"size must be positive, got {size}")
+        if self.dead:
+            reject_place(4, "account failed the combine (MLL breached)")
+        if self._kernel.day_locked:
+            reject_place(4, "daily loss limit reached: trading locked until 18:00 ET")
+        now = self._clock.now_ns()
+        if self._session.in_no_trade_window(now):
+            reject_place(5, "no-trade window 16:10-18:00 ET")
+        if trading_day_of(now).weekday() >= 5:
+            reject_place(5, "market closed (weekend)")
+        return spec
+
+    def _check_position_cap(self, spec: InstrumentSpec, size: int) -> None:
+        """Conservative account-wide cap: |net| + working opening orders."""
+        units = sum(
+            abs(p.qty) * self._instruments[cid].cap_units for cid, p in self._positions.items()
+        )
+        units += sum(
+            o.remaining * self._instruments[o.contract_id].cap_units
+            for o in self._orders.values()
+            if o.status is OrderStatus.OPEN and not o.reduce_only
+        )
+        if units + size * spec.cap_units > self._kernel.max_position_micro_units():
+            reject_place(
+                4,
+                f"position cap exceeded: {self._kernel.max_position_micro_units()} "
+                "micro-units (minis count 10, micros 1; working orders included)",
+            )
+
+    def _resolve_brackets(
+        self,
+        side: OrderSide,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None,
+        stop_loss_ticks: int | None,
+        take_profit_ticks: int | None,
+    ) -> _PendingBrackets | None:
+        def norm(
+            raw: PlaceOrderBracket | dict[str, int] | None,
+            magnitude: int | None,
+            *,
+            is_sl: bool,
+            name: str,
+        ) -> int | None:
+            if raw is not None and magnitude is not None:
+                raise ValueError(f"pass either {name}_bracket or {name}_ticks, not both")
+            if magnitude is not None:
+                mag = abs(int(magnitude))
+                if is_sl:
+                    return -mag if side is OrderSide.BUY else mag
+                return mag if side is OrderSide.BUY else -mag
+            if raw is None:
+                return None
+            ticks = raw.ticks if isinstance(raw, PlaceOrderBracket) else int(raw["ticks"])
+            if ticks == 0:
+                reject_place(2, f"{name} bracket ticks must be non-zero")
+            long = side is OrderSide.BUY
+            wrong_sign = (is_sl and ((long and ticks > 0) or (not long and ticks < 0))) or (
+                not is_sl and ((long and ticks < 0) or (not long and ticks > 0))
+            )
+            if wrong_sign:
+                reject_place(2, f"{name} bracket has the wrong sign for {side.name}")
+            return ticks
+
+        sl = norm(stop_loss_bracket, stop_loss_ticks, is_sl=True, name="stop_loss")
+        tp = norm(take_profit_bracket, take_profit_ticks, is_sl=False, name="take_profit")
+        if sl is None and tp is None:
+            return None
+        return _PendingBrackets(sl, tp)
+
+    def _validate_trailing(
+        self, contract_id: str, spec: InstrumentSpec, trail_d: Decimal
+    ) -> tuple[int, Decimal]:
+        last = self._last_bar.get(contract_id)
+        if last is None:
+            reject_place(2, "TRAILING_STOP requires market data for the trail anchor")
+        distance_px = abs(last.close - trail_d)
+        trail_distance = to_ticks(distance_px, spec.tick_size)
+        if trail_distance == 0 or trail_distance > self._config.max_trail_ticks:
+            reject_place(
+                2,
+                f"trail distance {trail_distance} ticks outside (0, "
+                f"{self._config.max_trail_ticks}]",
+            )
+        return trail_distance, trail_d
+
+    def _place(self, account_id: int, contract_id: str, **kwargs: Any) -> int:
+        """Count rejections at the one choke point every order path funnels through.
+
+        Every public entry (``place``/``buy``/``sell``, the sugar helpers, and
+        the bracket children) reaches the gateway mirror below. Tallying here —
+        rather than at each ``reject_place`` site — means a new rejection reason
+        cannot be added without being counted.
+        """
+        try:
+            return self._place_checked(account_id, contract_id, **kwargs)
+        except APIError as error:
+            code = -1 if error.error_code is None else error.error_code
+            self._rejections[code] = self._rejections.get(code, 0) + 1
+            raise
+
+    def _place_checked(
+        self,
+        account_id: int,
+        contract_id: str,
+        *,
+        side: OrderSide | int,
+        type: OrderType | int,
+        size: int,
+        limit_price: float | Decimal | None,
+        stop_price: float | Decimal | None,
+        trail_price: float | Decimal | None,
+        custom_tag: str | None,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None,
+        stop_loss_ticks: int | None,
+        take_profit_ticks: int | None,
+        reduce_only: bool = False,
+    ) -> int:
+        if account_id != self._account_id:
+            reject_place(1, f"unknown account {account_id}")
+        if int(side) not in (0, 1):
+            reject_place(2, f"invalid order side {side!r} (BUY/BID=0, SELL/ASK=1)")
+        spec = self._pretrade_checks(contract_id, size)
+        side_e = OrderSide(int(side))
+        type_e = OrderType(int(type))
+
+        if custom_tag is not None:
+            if custom_tag in self._used_tags:
+                reject_place(2, f"custom_tag {custom_tag!r} already used (must be unique)")
+            self._used_tags.add(custom_tag)
+
+        if not reduce_only:
+            self._check_position_cap(spec, size)
+
+        limit_d = None if limit_price is None else _as_decimal(limit_price)
+        stop_d = None if stop_price is None else _as_decimal(stop_price)
+        trail_d = None if trail_price is None else _as_decimal(trail_price)
+        price_fields = (("limit_price", limit_d), ("stop_price", stop_d), ("trail_price", trail_d))
+        for label, px in price_fields:
+            if px is not None and not is_on_grid(px, spec.tick_size):
+                reject_place(2, f"{label} {px} is off the {spec.tick_size} tick grid")
+
+        trail_distance: int | None = None
+        trail_stop: Decimal | None = None
+        if type_e is OrderType.LIMIT and limit_d is None:
+            reject_place(2, "LIMIT order requires limit_price")
+        elif type_e is OrderType.STOP and stop_d is None:
+            reject_place(2, "STOP order requires stop_price")
+        elif type_e is OrderType.STOP_LIMIT:
+            reject_place(2, "STOP_LIMIT is not supported by the Tier-0 bar fill model")
+        elif type_e in (OrderType.JOIN_BID, OrderType.JOIN_ASK):
+            reject_place(
+                2,
+                "JOIN_BID/JOIN_ASK need live quote data (Tier-1+); "
+                "unsupported at Tier-0 (documented divergence)",
+            )
+        elif type_e is OrderType.TRAILING_STOP:
+            if trail_d is None:
+                reject_place(2, "TRAILING_STOP requires trail_price (absolute anchor)")
+            trail_distance, trail_stop = self._validate_trailing(contract_id, spec, trail_d)
+        elif type_e not in (OrderType.MARKET, OrderType.LIMIT, OrderType.STOP):
+            reject_place(2, f"order type {type_e.name} is not placeable")
+
+        pending = self._resolve_brackets(
+            side_e, stop_loss_bracket, take_profit_bracket, stop_loss_ticks, take_profit_ticks
+        )
+
+        order = WorkingOrder(
+            order_id=self._ids.next(),
+            account_id=self._account_id,
+            contract_id=contract_id,
+            side=side_e,
+            type=type_e,
+            size=size,
+            accepted_ts=self._clock.now_ns(),
+            limit_price=limit_d,
+            stop_price=stop_d,
+            trail_stop_price=trail_stop,
+            trail_distance_ticks=trail_distance,
+            custom_tag=custom_tag,
+            reduce_only=reduce_only,
+        )
+        self._orders[order.order_id] = order
+        if pending is not None:
+            self._brackets[order.order_id] = pending
+        self._emit_order(order)
+        return order.order_id
+
+    def _modify(
+        self,
+        account_id: int,
+        order_id: int,
+        *,
+        size: int | None,
+        limit_price: float | Decimal | None,
+        stop_price: float | Decimal | None,
+        trail_price: float | Decimal | None,
+    ) -> None:
+        if account_id != self._account_id:
+            reject_modify(1, f"unknown account {account_id}")
+        order = self._orders.get(order_id)
+        if order is None or order.status in _TERMINAL:
+            reject_modify(2, f"order {order_id} not found or terminal")
+        spec = self._instruments[order.contract_id]
+        if size is not None:
+            if size <= 0 or size < order.filled_qty:
+                reject_modify(3, f"invalid size {size}")
+            order.size = size
+        for label, value in (("limit_price", limit_price), ("stop_price", stop_price)):
+            if value is not None:
+                px = _as_decimal(value)
+                if not is_on_grid(px, spec.tick_size):
+                    reject_modify(3, f"{label} {px} is off the tick grid")
+                if label == "limit_price":
+                    order.limit_price = px
+                else:
+                    order.stop_price = px
+        if trail_price is not None:
+            px = _as_decimal(trail_price)
+            if not is_on_grid(px, spec.tick_size):
+                reject_modify(3, f"trail_price {px} is off the tick grid")
+            last = self._last_bar.get(order.contract_id)
+            if last is None:
+                reject_modify(3, "no market data to re-anchor trailing stop")
+            distance = to_ticks(abs(last.close - px), spec.tick_size)
+            if distance == 0 or distance > self._config.max_trail_ticks:
+                reject_modify(
+                    3,
+                    f"trail distance {distance} ticks outside (0, {self._config.max_trail_ticks}]",
+                )
+            order.trail_distance_ticks = distance
+            order.trail_stop_price = px
+        self._emit_order(order)
+
+    def _cancel(self, account_id: int, order_id: int) -> None:
+        if account_id != self._account_id:
+            reject_cancel(1, f"unknown account {account_id}")
+        order = self._orders.get(order_id)
+        if order is None or order.status in _TERMINAL:
+            reject_cancel(2, f"order {order_id} not found or terminal")
+        self._cancel_order_internal(order_id, self._clock.now_ns())
+
+    def _submit_reduce_market(self, contract_id: str, size: int) -> int:
+        """A resting reduce-only MARKET order (positions.close/partial_close):
+
+        fills at the next bar's open through the normal walk, exactly like any
+        other market order — the documented Tier-0 execution model.
+        """
+        pos = self._positions[contract_id]
+        side = OrderSide.SELL if pos.direction > 0 else OrderSide.BUY
+        return self._place(
+            self._account_id,
+            contract_id,
+            side=side,
+            type=OrderType.MARKET,
+            size=size,
+            limit_price=None,
+            stop_price=None,
+            trail_price=None,
+            custom_tag=None,
+            stop_loss_bracket=None,
+            take_profit_bracket=None,
+            stop_loss_ticks=None,
+            take_profit_ticks=None,
+            reduce_only=True,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Protocol-facing facades (thin async views over the broker internals)
+# ---------------------------------------------------------------------------
+
+
+class SimOrderApi:
+    __slots__ = ("_b",)
+
+    def __init__(self, broker: SimBroker) -> None:
+        self._b = broker
+
+    async def place(
+        self,
+        account_id: int,
+        contract_id: str,
+        *,
+        side: OrderSide | int,
+        type: OrderType | int,
+        size: int,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+        custom_tag: str | None = None,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+    ) -> int:
+        return self._b._place(
+            account_id,
+            contract_id,
+            side=side,
+            type=type,
+            size=size,
+            limit_price=limit_price,
+            stop_price=stop_price,
+            trail_price=trail_price,
+            custom_tag=custom_tag,
+            stop_loss_bracket=stop_loss_bracket,
+            take_profit_bracket=take_profit_bracket,
+            stop_loss_ticks=stop_loss_ticks,
+            take_profit_ticks=take_profit_ticks,
+        )
+
+    async def buy(
+        self,
+        account_id: int,
+        contract_id: str,
+        size: int,
+        *,
+        type: OrderType | int = OrderType.MARKET,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+        custom_tag: str | None = None,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+    ) -> int:
+        return await self.place(
+            account_id,
+            contract_id,
+            side=OrderSide.BUY,
+            type=type,
+            size=size,
+            limit_price=limit_price,
+            stop_price=stop_price,
+            trail_price=trail_price,
+            custom_tag=custom_tag,
+            stop_loss_bracket=stop_loss_bracket,
+            take_profit_bracket=take_profit_bracket,
+            stop_loss_ticks=stop_loss_ticks,
+            take_profit_ticks=take_profit_ticks,
+        )
+
+    async def sell(
+        self,
+        account_id: int,
+        contract_id: str,
+        size: int,
+        *,
+        type: OrderType | int = OrderType.MARKET,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+        custom_tag: str | None = None,
+        stop_loss_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        take_profit_bracket: PlaceOrderBracket | dict[str, int] | None = None,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+    ) -> int:
+        return await self.place(
+            account_id,
+            contract_id,
+            side=OrderSide.SELL,
+            type=type,
+            size=size,
+            limit_price=limit_price,
+            stop_price=stop_price,
+            trail_price=trail_price,
+            custom_tag=custom_tag,
+            stop_loss_bracket=stop_loss_bracket,
+            take_profit_bracket=take_profit_bracket,
+            stop_loss_ticks=stop_loss_ticks,
+            take_profit_ticks=take_profit_ticks,
+        )
+
+    async def modify(
+        self,
+        account_id: int,
+        order_id: int,
+        *,
+        size: int | None = None,
+        limit_price: float | Decimal | None = None,
+        stop_price: float | Decimal | None = None,
+        trail_price: float | Decimal | None = None,
+    ) -> None:
+        self._b._modify(
+            account_id,
+            order_id,
+            size=size,
+            limit_price=limit_price,
+            stop_price=stop_price,
+            trail_price=trail_price,
+        )
+
+    async def cancel(self, account_id: int, order_id: int) -> None:
+        self._b._cancel(account_id, order_id)
+
+    async def cancel_all(self, account_id: int) -> list[int]:
+        if account_id != self._b._account_id:
+            reject_cancel(1, f"unknown account {account_id}")
+        return self._b._cancel_all_working(self._b._clock.now_ns())
+
+    async def search_open(self, account_id: int) -> list[OrderModel]:
+        if account_id != self._b._account_id:
+            raise APIError("AccountNotFound", error_code=1)
+        return [
+            self._b._order_model(o)
+            for o in self._b._orders.values()
+            if o.status is OrderStatus.OPEN
+        ]
+
+    async def get(self, account_id: int, order_id: int) -> OrderModel | None:
+        if account_id != self._b._account_id:
+            return None  # the gateway reports OrderNotFound for foreign accounts
+        order = self._b._orders.get(order_id)
+        return None if order is None else self._b._order_model(order)
+
+    async def wait_for_fill(
+        self,
+        account_id: int,
+        order_id: int,
+        *,
+        timeout: float = 30.0,  # noqa: ASYNC109 - mirrors the SDK signature
+        poll_interval: float = 1.0,
+    ) -> OrderModel:
+        order = self._b._orders.get(order_id) if account_id == self._b._account_id else None
+        if order is not None and order.status in _TERMINAL:
+            return self._b._order_model(order)
+        raise UnsupportedInBacktestError(
+            "wait_for_fill cannot busy-poll under a deterministic TestClock; "
+            "handle fills in Strategy.on_order/on_fill callbacks instead (the "
+            "parity-safe idiom in both sim and live)."
+        )
+
+
+class SimPositionApi:
+    __slots__ = ("_b",)
+
+    def __init__(self, broker: SimBroker) -> None:
+        self._b = broker
+
+    async def search_open(self, account_id: int) -> list[PositionModel]:
+        if account_id != self._b._account_id:
+            raise APIError("AccountNotFound", error_code=1)
+        return [
+            self._b._position_model(p, self._b._instruments[cid])
+            for cid, p in self._b._positions.items()
+        ]
+
+    async def close(self, account_id: int, contract_id: str) -> None:
+        if account_id != self._b._account_id:
+            raise APIError("AccountNotFound", error_code=1)
+        pos = self._b._positions.get(contract_id)
+        if pos is None:
+            raise APIError("PositionNotFound", error_code=2)
+        self._b._submit_reduce_market(contract_id, pos.qty)
+
+    async def partial_close(self, account_id: int, contract_id: str, size: int) -> None:
+        if account_id != self._b._account_id:
+            raise APIError("AccountNotFound", error_code=1)
+        pos = self._b._positions.get(contract_id)
+        if pos is None:
+            raise APIError("PositionNotFound", error_code=2)
+        if size <= 0 or size > pos.qty:
+            raise APIError("InvalidCloseSize", error_code=5)
+        self._b._submit_reduce_market(contract_id, size)
+
+    async def close_all(self, account_id: int) -> list[str]:
+        if account_id != self._b._account_id:
+            raise APIError("AccountNotFound", error_code=1)
+        closed: list[str] = []
+        for cid, pos in list(self._b._positions.items()):
+            self._b._submit_reduce_market(cid, pos.qty)
+            closed.append(cid)
+        return closed
+
+
+class SimHistoryApi:
+    __slots__ = ("_b",)
+
+    def __init__(self, broker: SimBroker) -> None:
+        self._b = broker
+
+    async def retrieve_bars(
+        self,
+        contract_id: str,
+        *,
+        unit: AggregateBarUnit | int,
+        unit_number: int,
+        start_time: datetime | str,
+        end_time: datetime | str,
+        limit: int = 1000,
+        live: bool = False,
+        include_partial_bar: bool = False,
+    ) -> list[AggregateBarModel]:
+        """Serve ONLY already-seen bars (zero look-ahead), newest-first like the
+
+        gateway (bars stamped at open time, matching the SDK model). The
+        requested ``unit``/``unit_number`` must match the feed's native bar
+        spec — Tier-0 does no resampling and refuses to silently serve wrong
+        aggregation. ``start_time``/``end_time`` filter when passed as
+        datetimes (ISO strings accepted for parity but treated as unbounded).
+        """
+        if limit > 20_000:
+            raise ValueError(f"limit {limit} exceeds the gateway maximum of 20000")
+        bars = self._b._history.get(contract_id, [])
+        if bars:
+            native = bars[-1].bar_type
+            if (int(unit), unit_number) != (int(native.unit), native.unit_number):
+                raise ValueError(
+                    f"Tier-0 history serves only the feed's native bar spec "
+                    f"({native.unit.name} x{native.unit_number}); requested "
+                    f"{AggregateBarUnit(int(unit)).name} x{unit_number}. "
+                    "Resampling arrives with the multi-timeframe data layer."
+                )
+        start_ns = dt_to_ns(start_time) if isinstance(start_time, datetime) else None
+        end_ns = dt_to_ns(end_time) if isinstance(end_time, datetime) else None
+        out: list[AggregateBarModel] = []
+        for bar in reversed(bars):
+            if len(out) >= limit:
+                break
+            if start_ns is not None and bar.ts_event < start_ns:
+                break  # history is time-ascending; everything earlier is out of range
+            if end_ns is not None and bar.ts_event > end_ns:
+                continue
+            out.append(
+                AggregateBarModel(
+                    t=ns_to_dt(bar.ts_event),
+                    o=bar.open,
+                    h=bar.high,
+                    l=bar.low,
+                    c=bar.close,
+                    v=bar.volume,
+                )
+            )
+        return out