topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/fills/__init__.py

@@ -0,0 +1 @@
+"""topstep_backtest.fills"""

topstep_backtest/fills/bar_fill.py

@@ -0,0 +1,268 @@
+"""Tier-0 bar-based fill model — the pessimistic execution realism layer.
+
+Anti-optimism is the whole point: whenever a bar leaves the fill ambiguous,
+this model resolves it AGAINST the trader. Concretely:
+
+* **Participation firewall (no look-ahead):** an order interacts with a bar
+  only if it was accepted at/before the bar's OPEN (``accepted_ts <=
+  bar.ts_event``). An order created on a bar's close signal therefore first
+  participates in the NEXT bar — the classic backtest look-ahead bug is
+  structurally impossible.
+* **Limits need trade-THROUGH:** by default a resting limit does not fill on
+  an exact touch of its level — the bar must trade at least one tick past it
+  (an exact-touch extreme is exactly where real queues don't get filled).
+  This applies at the OPEN too: a bar opening exactly at the level is a touch,
+  not price improvement, so it does not fill at the open under the default;
+  the order can still fill at its level if the bar later trades through.
+  ``fill_limit_on_touch=True`` relaxes both for sensitivity analysis.
+* **Stops always pay slippage:** a triggered stop fills ``stop_slippage_ticks``
+  ADVERSE of its trigger, and a gap through the stop fills at the (worse) open
+  plus slippage — never at the stop price itself. The slipped price MAY exceed
+  the bar's high/low: real stop slippage escapes the bar's printed range, and
+  clamping it back inside would be optimistic. That is intentional.
+* **Marketable-at-open limits DO take the improvement:** an open STRICTLY
+  better than the level is genuine price improvement, not optimism — a resting
+  buy limit above the open would fill at the open in reality too.
+* **Honest timestamps:** open-instant fills are stamped with the bar's OPEN
+  time (``bar.ts_event``); every intrabar fill is stamped with the bar's CLOSE
+  time (``bar.ts_init``) — the honest upper bound for an unknown intrabar time.
+* **Trigger levels:** every fill carries ``trigger_price`` — the LEVEL that
+  triggered it (stop level, limit level, or the open), never the
+  slippage-adjusted price. The broker orders intrabar events by trigger.
+
+All prices are produced by integer-tick arithmetic on the instrument grid;
+a fill price can never land off-grid. Fills are for the FULL remaining
+quantity (Tier-0 models no partials).
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import msgspec
+from topstep_sdk import OrderSide, OrderStatus, OrderType
+
+from ..core.money import from_ticks, to_ticks
+from ..protocols import Bar, Fill, Liquidity, MarketContext, PricePath, WorkingOrder
+
+__all__ = ["BarFillConfig", "BarFillModel"]
+
+
+class BarFillConfig(msgspec.Struct, frozen=True):
+    """Knobs of the Tier-0 pessimism model (all default to the conservative side)."""
+
+    stop_slippage_ticks: int = 1
+    """Adverse ticks added to EVERY triggered stop fill (gap or intrabar)."""
+
+    market_slippage_ticks: int = 0
+    """Adverse ticks on market fills (0: the modeled micros are liquid enough)."""
+
+    fill_limit_on_touch: bool = False
+    """False (default) = a limit fills only if the bar trades >= 1 tick THROUGH
+    its level; True = an exact touch of the level suffices."""
+
+
+class _Execution(msgspec.Struct, frozen=True):
+    """Internal: where/when along the path an order executed."""
+
+    price: Decimal
+    trigger: Decimal  # the LEVEL that triggered the fill (see Fill.trigger_price)
+    seq: int
+    at_open: bool  # True -> executed at the bar's open instant
+
+
+class BarFillModel:
+    """Tier-0 ``FillModel``: decides fills from OHLC bars + the shared path.
+
+    Conforms structurally to ``protocols.FillModel``. Deterministic — no
+    randomness at all at this tier.
+    """
+
+    def __init__(self, config: BarFillConfig | None = None) -> None:
+        self._config = config if config is not None else BarFillConfig()
+
+    @property
+    def config(self) -> BarFillConfig:
+        return self._config
+
+    def try_fill(
+        self,
+        order: WorkingOrder,
+        ctx: MarketContext,
+        path: PricePath,
+    ) -> list[Fill]:
+        bar = ctx.bar
+        if bar is None:  # Tier-0 always sets it; refuse to guess otherwise
+            return []
+        if order.status != OrderStatus.OPEN or order.remaining <= 0:
+            return []
+        # Participation firewall: the order must have existed at/before this
+        # bar's OPEN. An order accepted at a bar's close (ts_init) first
+        # participates in the NEXT bar.
+        if order.accepted_ts > bar.ts_event:
+            return []
+
+        tick = ctx.instrument.tick_size
+        otype = OrderType(order.type)
+        if otype == OrderType.MARKET:
+            execution = self._market(order, bar, tick)
+        elif otype == OrderType.LIMIT:
+            execution = self._limit(order, bar, path, tick)
+        elif otype == OrderType.STOP:
+            if order.stop_price is None:
+                return []
+            execution = self._stop(order, bar, path, tick, order.stop_price)
+        elif otype == OrderType.TRAILING_STOP:
+            # The broker maintains trail_stop_price; without it there is no
+            # trigger to evaluate.
+            if order.trail_stop_price is None:
+                return []
+            execution = self._stop(order, bar, path, tick, order.trail_stop_price)
+        else:
+            # STOP_LIMIT (and any other type) is unsupported at Tier-0; the
+            # broker rejects placement, and we never fill it here.
+            return []
+
+        if execution is None:
+            return []
+
+        liquidity = Liquidity.MAKER if otype == OrderType.LIMIT else Liquidity.TAKER
+        # Open-instant fills happen at the bar's OPEN time; an intrabar fill's
+        # true time is unknown, so it is stamped at the bar's CLOSE (ts_init) —
+        # the honest upper bound. Never ctx.ts_event: the broker sets that to
+        # the bar OPEN, which would make every fill look like an open fill.
+        return [
+            Fill(
+                order_id=order.order_id,
+                price=execution.price,
+                qty=order.remaining,  # Tier-0: always the full remaining qty
+                ts_event=bar.ts_event if execution.at_open else bar.ts_init,
+                seq=execution.seq,
+                liquidity=liquidity,
+                trigger_price=execution.trigger,
+            )
+        ]
+
+    # -- per-type semantics -------------------------------------------------
+
+    def _market(self, order: WorkingOrder, bar: Bar, tick: Decimal) -> _Execution:
+        """MARKET: fill at the open, slipped ADVERSE (buy up / sell down)."""
+        slip = self._config.market_slippage_ticks
+        open_ticks = to_ticks(bar.open, tick)
+        if _is_buy(order.side):
+            price = from_ticks(open_ticks + slip, tick)
+        else:
+            price = from_ticks(open_ticks - slip, tick)
+        # Trigger is the OPEN (the touch point), not the slipped price.
+        return _Execution(price=price, trigger=from_ticks(open_ticks, tick), seq=0, at_open=True)
+
+    def _limit(
+        self,
+        order: WorkingOrder,
+        bar: Bar,
+        path: PricePath,
+        tick: Decimal,
+    ) -> _Execution | None:
+        """LIMIT: an open STRICTLY through the level takes the improvement; an
+        open exactly AT the level is a touch (fills at the open only in touch
+        mode); else require the bar to reach (touch mode) or trade one tick
+        THROUGH (default) the level."""
+        level = order.limit_price
+        if level is None:
+            return None
+        level = from_ticks(to_ticks(level, tick), tick)  # enforce on-grid
+        open_price = from_ticks(to_ticks(bar.open, tick), tick)  # enforce on-grid
+        touch = self._config.fill_limit_on_touch
+
+        if _is_buy(order.side):
+            if bar.open < level or (touch and bar.open == level):
+                # Marketable at the open: genuine price improvement (or an
+                # exact open-touch in touch mode) — fill at the open.
+                return _Execution(price=open_price, trigger=open_price, seq=0, at_open=True)
+            # An open exactly at the level under the default is only a touch:
+            # fall through to the resting logic, which still fills at the
+            # level if the bar trades a tick THROUGH it.
+            required = level if touch else level - tick
+            if bar.low > required:
+                return None
+            seq = _first_seq_reaching_down(path, level)
+        else:
+            if bar.open > level or (touch and bar.open == level):
+                return _Execution(price=open_price, trigger=open_price, seq=0, at_open=True)
+            required = level if touch else level + tick
+            if bar.high < required:
+                return None
+            seq = _first_seq_reaching_up(path, level)
+
+        if seq is None:  # bar range says reachable but path disagrees: no fill
+            return None
+        return _Execution(price=level, trigger=level, seq=seq, at_open=False)
+
+    def _stop(
+        self,
+        order: WorkingOrder,
+        bar: Bar,
+        path: PricePath,
+        tick: Decimal,
+        trigger: Decimal,
+    ) -> _Execution | None:
+        """STOP / TRAILING_STOP: gap-through fills at the open + slippage
+        (never at the trigger); an intrabar trigger fills at trigger +
+        slippage. The slipped price MAY escape the bar's high/low — real
+        slippage does, and clamping would be optimistic."""
+        slip = self._config.stop_slippage_ticks
+        trigger_ticks = to_ticks(trigger, tick)  # also enforces on-grid
+        level = from_ticks(trigger_ticks, tick)  # the on-grid stop level S
+        open_price = from_ticks(to_ticks(bar.open, tick), tick)  # enforce on-grid
+
+        if _is_buy(order.side):
+            if bar.open >= trigger:
+                # Gapped through the stop: pay the (worse) open, plus slippage.
+                # The trigger (touch point) is the OPEN, not the stop level.
+                price = from_ticks(to_ticks(bar.open, tick) + slip, tick)
+                return _Execution(price=price, trigger=open_price, seq=0, at_open=True)
+            seq = _first_seq_reaching_up(path, trigger)
+            if seq is None:
+                return None
+            # Trigger is the stop level S; the PRICE is S slipped adverse.
+            return _Execution(
+                price=from_ticks(trigger_ticks + slip, tick),
+                trigger=level,
+                seq=seq,
+                at_open=False,
+            )
+
+        if bar.open <= trigger:
+            price = from_ticks(to_ticks(bar.open, tick) - slip, tick)
+            return _Execution(price=price, trigger=open_price, seq=0, at_open=True)
+        seq = _first_seq_reaching_down(path, trigger)
+        if seq is None:
+            return None
+        return _Execution(
+            price=from_ticks(trigger_ticks - slip, tick),
+            trigger=level,
+            seq=seq,
+            at_open=False,
+        )
+
+
+def _is_buy(side: OrderSide | int) -> bool:
+    return int(side) == int(OrderSide.BUY)
+
+
+def _first_seq_reaching_down(path: PricePath, level: Decimal) -> int | None:
+    """Index of the first path segment on which price reaches ``level`` from
+    above (the segment's lower end is at/below the level)."""
+    for i in range(len(path) - 1):
+        if min(path[i].price, path[i + 1].price) <= level:
+            return i
+    return None
+
+
+def _first_seq_reaching_up(path: PricePath, level: Decimal) -> int | None:
+    """Index of the first path segment on which price reaches ``level`` from
+    below (the segment's upper end is at/above the level)."""
+    for i in range(len(path) - 1):
+        if max(path[i].price, path[i + 1].price) >= level:
+            return i
+    return None

topstep_backtest/fills/fees.py

@@ -0,0 +1,120 @@
+"""Topstep fee model: per-side commission + exchange + NFA costs.
+
+Conforms to ``protocols.FeeModel``. Costs are charged PER SIDE (entry AND
+exit), split per the SDK ``HalfTradeModel`` convention::
+
+    fees        = (exchange + nfa) * qty     (venue + regulatory)
+    commissions = commission * qty           (broker)
+
+Rates follow docs/topstep-rules.md §7 (researched July 2026, medium
+confidence — reconcile against a real account blotter before trusting
+micro-scalp verdicts; for micros the round-turn cost can rival the edge).
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import msgspec
+from topstep_sdk import OrderSide
+
+from ..core.instruments import SPECS, InstrumentSpec
+from ..protocols import Liquidity
+
+__all__ = ["FeeSchedule", "TopstepFees"]
+
+
+class FeeSchedule(msgspec.Struct, frozen=True):
+    """Per-side cost components for one product (all USD Decimals)."""
+
+    commission_per_side: Decimal
+    exchange_per_side: Decimal
+    nfa_per_side: Decimal
+
+
+_MINI_COMMISSION = Decimal("0.50")
+_MICRO_COMMISSION = Decimal("0.25")
+
+# NFA regulatory fee per side. Topstep publishes ~$0.01-0.02; we take the
+# conservative (higher) end so fee drag is never understated.
+_NFA_PER_SIDE = Decimal("0.02")
+
+# CME Group exchange + clearing, non-member, per side (docs §7).
+# NG, SI and SIL are ESTIMATES inferred from their asset-class siblings
+# (CL-class energy mini; GC/MGC-class metals) — not from a published rate
+# card. Verify against the CME Fee Finder before trusting their verdicts.
+_EXCHANGE_PER_SIDE: dict[str, Decimal] = {
+    "ES": Decimal("1.38"),
+    "NQ": Decimal("1.38"),
+    "YM": Decimal("1.38"),
+    "RTY": Decimal("1.38"),
+    "MES": Decimal("0.35"),
+    "MNQ": Decimal("0.35"),
+    "MYM": Decimal("0.35"),
+    "M2K": Decimal("0.35"),
+    "CL": Decimal("1.50"),
+    "MCL": Decimal("0.50"),
+    "NG": Decimal("1.50"),  # estimate (CL-class energy mini)
+    "GC": Decimal("1.65"),
+    "MGC": Decimal("1.10"),
+    "SI": Decimal("1.65"),  # estimate (GC-class metals mini)
+    "SIL": Decimal("1.10"),  # estimate (MGC-class metals micro)
+}
+
+_DEFAULT_SCHEDULES: dict[str, FeeSchedule] = {
+    symbol: FeeSchedule(
+        commission_per_side=_MICRO_COMMISSION if spec.is_micro else _MINI_COMMISSION,
+        exchange_per_side=_EXCHANGE_PER_SIDE[symbol],
+        nfa_per_side=_NFA_PER_SIDE,
+    )
+    for symbol, spec in SPECS.items()
+}
+
+# Unknown symbol -> conservative MINI-level default: assume the expensive
+# (mini commission, CL-class exchange rate) case so an unrecognized product
+# never gets its costs accidentally understated.
+_UNKNOWN_SCHEDULE = FeeSchedule(
+    commission_per_side=Decimal("0.50"),
+    exchange_per_side=Decimal("1.50"),
+    nfa_per_side=Decimal("0.02"),
+)
+
+
+class TopstepFees:
+    """Per-side Topstep fee model (``protocols.FeeModel``).
+
+    ``overrides`` (keyed by product symbol) replace the built-in schedule for
+    those symbols — the calibration hook for reconciling against a real
+    account blotter.
+    """
+
+    def __init__(self, overrides: dict[str, FeeSchedule] | None = None) -> None:
+        self._overrides: dict[str, FeeSchedule] = dict(overrides) if overrides else {}
+
+    def schedule_for(self, symbol: str) -> FeeSchedule:
+        """The effective schedule for ``symbol``: override > built-in > conservative default."""
+        override = self._overrides.get(symbol)
+        if override is not None:
+            return override
+        return _DEFAULT_SCHEDULES.get(symbol, _UNKNOWN_SCHEDULE)
+
+    def fee(
+        self,
+        instrument: InstrumentSpec,
+        side: OrderSide,
+        qty: int,
+        liquidity: Liquidity,
+    ) -> tuple[Decimal, Decimal]:
+        """Cost of one side of ``qty`` contracts: ``(fees, commissions)``.
+
+        ``fees = (exchange + nfa) * qty``; ``commissions = commission * qty``
+        (the SDK ``HalfTradeModel`` split). Topstep's schedule does not vary
+        by side or maker/taker at this tier, so ``side``/``liquidity`` are
+        accepted for protocol conformance but do not change the amounts.
+        """
+        if qty <= 0:
+            raise ValueError(f"qty must be positive, got {qty}")
+        schedule = self.schedule_for(instrument.symbol)
+        fees = (schedule.exchange_per_side + schedule.nfa_per_side) * qty
+        commissions = schedule.commission_per_side * qty
+        return fees, commissions

topstep_backtest/fills/path.py

@@ -0,0 +1,59 @@
+"""Deterministic intrabar price path construction (Tier-0).
+
+One path is built per bar and shared by the fill model AND the rule engine's
+breach check, so the relative ordering of fills vs. rule breaches inside a bar
+is decided by ONE walk of the bar — never two competing opinions.
+
+The path is always four points, ``seq`` 0..3::
+
+    OPEN -> EXTREME_FIRST -> EXTREME_SECOND -> CLOSE
+
+The only degree of freedom is which extreme comes first, and it is resolved
+PESSIMISTICALLY against the trader's open position:
+
+* net long  -> the LOW comes first (adverse move hits stops/breaches earliest)
+* net short -> the HIGH comes first
+* flat      -> the extreme NEARER the open comes first (the statistically more
+  likely first touch); an exact tie breaks to the LOW, deterministically.
+
+Degenerate bars (``high == low``, doji, single-print) still yield a valid
+4-point path — points may repeat a price, and zero-length segments are fine.
+"""
+
+from __future__ import annotations
+
+from ..protocols import Bar, PathPoint, PointKind, PricePath
+
+__all__ = ["build_path"]
+
+
+def build_path(bar: Bar, position_dir: int) -> PricePath:
+    """Build the pessimistic 4-point intrabar path for ``bar``.
+
+    Args:
+        bar: The completed OHLCV bar to walk.
+        position_dir: The trader's net position direction while this bar
+            prints: ``+1`` net long, ``-1`` net short, ``0`` flat.
+
+    Returns:
+        The 4-point ``PricePath`` (seq 0..3): OPEN, the adverse-first ordering
+        of the two extremes, then CLOSE.
+    """
+    if position_dir > 0:
+        # Long: the low is the adverse extreme — visit it first.
+        first, second = bar.low, bar.high
+    elif position_dir < 0:
+        # Short: the high is the adverse extreme — visit it first.
+        first, second = bar.high, bar.low
+    elif bar.open - bar.low <= bar.high - bar.open:
+        # Flat: extreme nearer the open first; exact tie -> low first.
+        first, second = bar.low, bar.high
+    else:
+        first, second = bar.high, bar.low
+
+    return (
+        PathPoint(seq=0, kind=PointKind.OPEN, price=bar.open),
+        PathPoint(seq=1, kind=PointKind.EXTREME_FIRST, price=first),
+        PathPoint(seq=2, kind=PointKind.EXTREME_SECOND, price=second),
+        PathPoint(seq=3, kind=PointKind.CLOSE, price=bar.close),
+    )