Broker & replay

Broker support by instrument

All three market classes read local trade and quote databases, even with quotes=False. They require the native extension and configured MASSIVE_SPEEDUP_DB_PATH or an explicit database_path. They do not connect to a live broker or fetch missing data. Brokers are supplied by the iterator; they have no public constructor.

The event loop contract

for instrument, timestamp, trade, quote, trades, quotes, broker in market:
    ...

quotes=False emits trade events while still advancing quote state. quotes=True emits both. For a given instrument and equal timestamp, quotes precede trades. Stock/futures ties between instruments are ordered by the input symbol list, so not every other symbol's equal-time event has necessarily been observed yet.

fast=False creates fresh recent-record dictionaries for each yielded event. fast=True reuses and mutates the same dictionaries; copy them if you retain a snapshot. These dictionaries contain observed market records, independent of the simulator's execution quote lookup.

iter(market) returns the market itself. next(market) advances; StopIteration marks exhaustion. It cannot be rewound; create another market to replay again. market.broker provides the current event's broker and raises IndexError before the first event or after exhaustion. Use the newly yielded broker each iteration; retaining an old broker retains its old timestamp.

Read integer timestamps from records or broker properties when nanosecond precision matters. Do not pass the tuple's floating-point seconds directly to database searches, which expect nanoseconds.

SimpleMarket — stocks

ms.SimpleMarket(date, symbols, trade_latency_ns=150000000, *,
    database_path=None, quotes=False, fast=False, trade_emulator=None,
    execution="market", passivity=0.0, unit_shares=1.0)

Read-only properties: broker, trade_emulator, trade_latency_ns, execution, passivity, unit_shares. market["AAPL"] returns held shares, and market[None] returns cash. A fresh book starts at zero cash and zero positions. market.summary() returns the session's ledger and the current book only after exhaustion.

When supplying trade_emulator, its execution, passivity, and unit size take precedence over the corresponding market arguments. The default latency argument defers to the emulator; an explicitly nondefault, inconsistent latency raises ValueError.

import massive_speedup as ms

market = ms.SimpleMarket(
    "2026-09-11", ["AAPL"],
    trade_latency_ns=150_000_000, quotes=True,
)
for symbol, timestamp, trade, quote, trades, quotes, broker in market:
    if trade is not None:
        broker.set_desired(1)

print(market.summary())

SimpleMarketBroker

broker.set_desired(desired: float, symbol=None) -> None
broker.buy(shares: float, symbol=None) -> None
broker.sell(shares: float, symbol=None) -> None

Read-only symbol identifies the bound stock; sip_timestamp is the decision timestamp in integer nanoseconds. symbol=None targets the current instrument. An explicit symbol must belong to the market; a bar-aggregator broker accepts only its own symbol.

Only −1, 0, and +1 are accepted as desired values. Repeating the same target does not keep buying shares; the emulator trades the difference from its current holding or maintains an existing working order. buy and sell are quantity commands: repeating them submits another quantity.

Quantity must be finite and nonnegative. Stock quantities at or below the emulator's 1e-12 tolerance are no-ops. Invalid values raise ValueError, unknown symbols raise IndexError, and submissions through a market broker after exhaustion raise RuntimeError. All three methods return None; inspect fills and rejections after replay.

How execution is calculated

For a decision at integer time t, the simulator looks up the last quote whose primary timestamp is at or before t + trade_latency_ns. The recorded execution timestamp is t + latency; the recorded quote timestamp is the timestamp of the actual quote used and may be earlier. This lookup is evaluated internally when the order is processed; it does not advance the strategy's event iterator to that later time.

buy_limit  = ask - passivity * (ask - bid)
sell_limit = bid + passivity * (ask - bid)

Passivity 0 places at the touch, 0.5 at the midpoint, 1 at the opposite side (buy bid / sell ask), and values above 1 beyond that side. There is no free midpoint fill: the quote must become marketable relative to the stored limit. Limit placement and polling use the quote lookup at the decision/poll time plus latency, so these are simulator operations, not current-event observations.

A changed desired target cancels a previous working order and creates a new one when required. Unchanged targets retain the working limit. SimpleMarket polls automatically on every trade and quote, including quotes that are not emitted. The remaining working limits are cancelled when the last attached stock session ends; positions and cash remain open.

A missing execution quote records reason="no_quote". A non-finite or nonpositive execution-side price records reason="unusable_price". Middle-mode quote validation additionally requires positive finite bid and ask with ask ≥ bid. Market orders validate the execution side; there is no staleness cutoff or displayed-size capacity check.

This is a quote-based execution model. It does not model queue priority, partial fills, fees, borrow availability, margin, auctions, market impact, or instrument-specific contract multipliers. Cash flow is quantity × reported price. In particular, futures and option ledger notionals do not apply a contract multiplier.

TradeEmulator — stock account and execution policy

ms.TradeEmulator(trade_latency_ns=150000000, execution="market",
    passivity=0.0, unit_shares=1.0)

The stock emulator owns execution policy, the order ledger, desired targets, cash, positions, and resting limits. Reuse one across chronological SimpleMarket sessions or attach it to a stock trade aggregator. It is not accepted by FuturesMarket or OptionMarket.

emulator.set_desired(symbol, desired, sip_timestamp, quotes,
                     quote_index_hint=-1) -> int
emulator.poll_working(symbol, sip_timestamp, quotes,
                      quote_index_hint=-1) -> int
emulator.working_order(symbol) -> dict | None
emulator.force_close_at(symbol, price, timestamp_ns=0,
                        style="moc_approx") -> None

Direct calls are advanced APIs. Drive them in chronological order, pass the matching quote database for each symbol, and serialize mutations of a shared book. There is no public method to reset an emulator or seed a starting balance; construct a fresh emulator to start again.

import massive_speedup as ms

emulator = ms.TradeEmulator(unit_shares=1)
for day in ("2026-09-10", "2026-09-11"):
    market = ms.SimpleMarket(day, ["AAPL"], trade_emulator=emulator)
    for symbol, timestamp, trade, quote, trades, quotes, broker in market:
        broker.set_desired(1)

print(emulator.summary())

Exhaust each session before moving to the next date. Cash, holdings, desired targets, and the ledger carry over; working limits do not carry past the end of the last active session. Session market.summary() reports that session's orders alongside the cumulative stock account, while emulator.summary() includes all orders.

Broker access from stock trade bars

ms.StockTradeAggregator(rows, interval_seconds, *,
    start_timestamp=None, quotes=None, trade_emulator=None)

Provide both a StockQuoteDatabase and a TradeEmulator to attach execution to stock trade aggregation. Both omitted gives ordinary aggregation; only one supplied raises ValueError. A matching stock trade database or typed stock trade iterable supplies the bars.

bars.broker is a SimpleMarketBroker for the current bar's instrument, with decision time bar.window_start + interval_ns. It becomes available after a bar is yielded and is unavailable before iteration, after StopIteration, or without the two execution arguments. bars.trade_emulator exposes the attached emulator or None.

import massive_speedup as ms

trades = ms.StockTradeDatabase("2026-09-11", "AAPL")
quotes = ms.StockQuoteDatabase("2026-09-11", "AAPL")
emulator = ms.TradeEmulator()
bars = ms.StockTradeAggregator(
    trades, 60, start_timestamp=trades.market_open,
    quotes=quotes, trade_emulator=emulator,
)
for bar in bars:
    bars.broker.set_desired(1 if bar.close > bar.open else 0)

del bars  # Release the aggregator's attached session.
print(emulator.summary())

The aggregator keeps its attached session alive until the aggregator is destroyed, even after bar iteration is exhausted. Releasing it lets the emulator end the session and cancel working limits when no other sessions remain. A saved broker must not outlive its aggregator, because it references that aggregator's quote-search state. No other instrument's aggregator exposes a broker.

FuturesMarket and FuturesMarketBroker

ms.FuturesMarket(date, symbols, trade_latency_ns=150000000, *,
    exchange="", database_path=None, quotes=False, fast=False)

date is the session end date (ISO string or datetime.date); symbols contains the exact stored contract tickers. exchange selects "" for generic futures directories or one of "cbot", "cme", "comex", "nymex" for the corresponding exchange directories. The other parameters have the event-loop meanings described above.

Yields FuturesTrade / FuturesQuote records ordered by timestamp. Both record types can carry a session_end_date that includes the prior evening's observations. The first tuple field and recent-record dictionary keys are contract ticker strings. Market members are broker, summary(), __iter__, and __next__.

broker.buy(contracts: float, symbol=None) -> None
broker.sell(contracts: float, symbol=None) -> None

The broker exposes symbol, timestamp, and sip_timestamp read-only; the latter is an alias of the futures timestamp for interface compatibility, not a separate SIP field. The optional symbol must be in the market's symbol list. Quantities must be finite and nonnegative; futures calls record zero-quantity orders rather than applying the stock emulator's near-zero no-op rule.

Futures execution crosses the spread using the last quote at or before event time plus latency. There is no set_desired, limit mode, shared stock emulator, market[symbol], or account book. summary() is gated until exhaustion and reports orders and raw cash flow; it does not return cash or positions.

import massive_speedup as ms

market = ms.FuturesMarket("2026-09-11", ["0BTZ9"], exchange="cme")
sent = False
for symbol, timestamp, trade, quote, trades, quotes, broker in market:
    if not sent:
        broker.buy(1)
        sent = True

print(market.summary())

OptionMarket and OptionMarketBroker

ms.OptionMarket(date, root, expiration, right, strike,
    trade_latency_ns=150000000, *, database_path=None,
    quotes=False, fast=False)

Replays one option contract. date is the observation session, root the underlying, expiration its YYYY-MM-DD expiration string, right is C or P, and strike is rounded to thousandths as in the option database constructors. It reads both contract trade and quote files.

Yields OptionTrade / OptionQuote in SIP order. Instrument and recent-record dictionary keys use ROOT/EXPIRATION/RIGHT/SSSSSSSS, for example AAPL/2026-09-18/C/00150000. Market members are broker, summary(), __iter__, and __next__.

broker.buy(contracts: float) -> None
broker.sell(contracts: float) -> None

Read-only broker.contract is the contract key string and broker.sip_timestamp is integer nanoseconds. There is no symbol override because a market holds one contract. Quantities must be finite and nonnegative; zero-quantity calls still produce an order record. Orders use the same latency-adjusted ask/bid lookup as futures.

Options have no set_desired, resting-limit policy, shared TradeEmulator, or position book. summary() requires exhaustion and provides the ledger and raw quantity × quote-price cash flow; no 100-share multiplier, exercise, assignment, or expiration settlement is applied.

import massive_speedup as ms

market = ms.OptionMarket("2026-09-11", "AAPL", "2026-09-18", "C", 150.0)
sent = False
for contract, timestamp, trade, quote, trades, quotes, broker in market:
    if not sent:
        broker.buy(1)
        sent = True

print(market.summary())

Summary and order record fields

All market summary() methods raise RuntimeError until the iterator is exhausted. Stock TradeEmulator.summary() is the lower-level exception: it can be read at any time. The following fields describe dictionaries, not record classes.

Rejections and cancellations omit price, notional, and quote_timestamp. The presence of a submitted order never guarantees a fill. Stocks retain open holdings at session end unless strategy code flattens them; the market does not automatically liquidate. Raw cash and cash_flow alone are not mark-to-market portfolio profit.

Causal visibility and the low-level boundary

The replay iterator is the intended strategy input: it exposes the current trade/quote and the latest already-observed records. Broker submissions return None instead of an execution price, and market summaries are withheld until replay completes. This makes the usual event loop harder to turn into an accidental crystal ball.

The package does not isolate all future data. The stock emulator updates its internal cash, holdings, and ledger immediately using the quote found at decision time plus latency. market[None], market.trade_emulator, emulator.cash, emulator.summary(), working-order prices, and direct emulator search hints can therefore expose state derived from later quotes while replay is still at the decision event.

Keep decisions based on the observed event stream and incremental state. Treat execution summaries as post-replay analysis. If using the advanced account or database APIs inside a strategy, enforce your own as-of-time visibility. Never use force_close_at with an eventual close price before that close is observable, and never feed a completed future bar into an earlier event.

This event-by-event pattern is intended to work with RTTA: update the indicator or model with one newly observed value, read its current signal, then submit a desired position. The quick-start broker example demonstrates the high-level path; the timestamp-search documentation explains how participant and receipt time can differ.