Executable artifact
ordersim
An inspectable, deterministic execution simulator for replaying real order-book data, with a Python-facing API and equivalent Python/C++ execution engines.
Why it exists
Backtests hide the path. ordersim records it.
Aggregate PnL is not enough when the strategy depends on queue position, cancel timing, partial fills, passive resting orders, and entry latency. ordersim treats the order-intent log as a first-class research artifact.
Install
Small API, explicit behavior.
pip install ordersimIn depth
The gap a backtest cannot show you.
There is a particular failure mode that backtests are bad at exposing. The strategy looks profitable in aggregate — Sharpe is high, drawdown is contained, equity curve the kind that books meetings. Then it goes live, and the realized fills happen at a different price than the backtest assumed. The strategy is still right about direction. It just isn't getting the trades it was promised.
ordersim was built to make that gap inspectable. Every order goes through a small, regular gateway API. Every interaction with the simulated venue — place, modify, cancel, partial fill, passive fill, queue position at the time of trade — is logged as a structured event. After a run, the question is no longer "what was the PnL", but "what exactly happened, in order, for each order".
That changes the unit of research. A backtest claim ("this strategy works") becomes a fill claim ("this strategy fills here, at this queue position, given this much liquidity ahead"). The latter is the one that survives contact with a live venue. For the conceptual frame, see the Trading Reality essay Execution IS the Strategy; for the mechanism in a runnable form, see latency and execution.
ordersim runs in two equivalent engines — a Python reference and a C++ port — that must produce identical event streams against the same replay. Identical, not similar. The equivalence is part of CI. If the C++ path drifts, the build fails. Speed is useful only when it does not change what you observe.
Frequently asked
Questions that come up.
What does ordersim do that a normal backtester does not?
A normal backtester returns aggregate PnL. ordersim returns the full event stream behind each fill — queue position at the time of trade, what was ahead in the book, when the order arrived, why it filled or did not. Aggregate PnL is a summary of that stream. The stream is the actual research object.
Why two engines (Python and C++)?
The Python engine is the reference — simple to read, easy to inspect, owns the definition of correct behavior. The C++ engine is the same model, faster. Both produce identical event logs against the same replay, and the equivalence is enforced in CI. The speed is only useful because the answer is the same.
What kind of order-book data does ordersim need?
Granular order-book data with per-event timestamps — message-level if available, top-of-book or top-N depth otherwise. Tick aggregates are not enough, because queue position is invisible at that resolution.
Is ordersim a live-trading system?
No. ordersim is a simulator, deliberately separated from any live execution gateway. The Python-facing API is shaped to be the same surface a production gateway would expose — so the strategy can target a single interface — but the bridging code is yours to own.
Where do I start?
Install via pip, run the latency demo, then read the simulation-assumptions doc. The demo is short on purpose: one strategy, one replay, two latency settings, and a diverging fill path you can read end to end.