XXSim
Exchange Execution Simulator — simulates order execution against OHLCV candlebar data.
Disclaimer
Own risk warning — Execution prices are best estimations based on worst-case scenarios and statistics. There will be price differences between simulations and real-world execution. By using this package the user acknowledges consent and takes full responsibility for any implications caused by errors or misinterpretation of results.
The challenge
The golden standard of market data comes in OHLCV candlebars (1-min, 5-min, daily, etc.). Within each bar, the intra-bar price path is unknown. Fill prices depend on rules and order formations that are hard to simulate exactly.
The solution
XXSim reconstructs a plausible intra-bar price path from OHLC data and evaluates orders against it, producing realistic fill prices within statistical uncertainty.
Supported order types
MarketOrderLimitOrderStopOrderStopLimitOrderTrailingStopMarketTrailingStopLimitMarketOnCloseOrder(MOC) — fills atbar.closeonly on bars whereBarData.is_close_bar=True
Not supported
- Limit-on-Close (LOC)
- Market-if-Touched (MIT)
Order modifiers
Fields that modify order behavior without changing the order type:
| Field | Description |
|---|---|
tif |
Time-in-force: GTC (default), DAY (expires on date change), GTD (expires after goodTillDate) |
goodTillDate |
Expiry datetime for GTD orders — format '%Y%m%d %H:%M:%S <timezone>' |
goodAfterTime |
Order inactive until this datetime — format '%Y%m%d %H:%M:%S <timezone>', timezone is mandatory |
ocaGroup |
One-Cancels-All group name — when one order in the group fills, the rest are cancelled |
Execution algorithm assumptions
- No partial fills — orders fill entirely or not at all
- Aggressive approach — order fills if there is any plausible price path through the bar that would trigger it
- Intra-bar price path for trailing stops:
- Bullish bar (
close > open):open → low → high → close - Bearish bar (
close ≤ open):open → high → low → close
- Bullish bar (
- Optional fill drift — volatility-based normal distribution drift, configurable via
SimulatorConfig:fill_drift_model="none"(default): deterministic fills at exact pricefill_drift_model="normal": drift drawn fromN(0, bar_range / std_divider)- Result always clamped to
[bar.low, bar.high] - Use
random_seedfor reproducible backtests
Installation
pip install XXSim
Usage
Single-Bar Execution
from XXSim import ExecutionEngine
from xtrading_models import MarketOrder, BarData
from datetime import datetime
engine = ExecutionEngine()
bar = BarData(
date=datetime(2025, 1, 1, 9, 30),
open=100.00, high=105.00, low=95.00, close=102.00, volume=1000000,
)
order = MarketOrder(action='BUY', totalQuantity=100)
fills = engine.execute(order, bar)
print(fills)
Multi-Bar Simulation
from XXSim import Simulator, SimulatorConfig
from xtrading_models import MarketOrder, LimitOrder
sim = Simulator()
# Register callbacks
sim.on_fill(lambda trade, fill: print(f"Filled: {fill.execution.price}"))
sim.on_cancel(lambda trade: print(f"Cancelled: {trade.log[-1].message}"))
# Submit orders
sim.submit_order(MarketOrder(action='BUY', totalQuantity=100))
sim.submit_order(LimitOrder(action='SELL', totalQuantity=100, price=110.0))
# Process bars
for bar in historical_bars:
fills = sim.process_bar(bar)
Bracket Orders
from xtrading_models import MarketOrder, StopOrder, LimitOrder
entry = MarketOrder(action='BUY', totalQuantity=100)
stop_loss = StopOrder(action='SELL', totalQuantity=100, price=95.0)
take_profit = LimitOrder(action='SELL', totalQuantity=100, price=110.0)
entry.add_child(stop_loss)
entry.add_child(take_profit)
trade = sim.submit_order(entry)
The Simulator supports:
- Bracket orders: child orders activate when parent fills
- Callbacks:
on_fill,on_cancel,on_status,on_bar SimulatorEvent: enum of all event names (fill,cancel,status,bar) — use instead of raw strings when subscribing viaEventEmitterdirectly
Development
Running Tests
pytest tests/ -v
Visualizations
Stop-limit and trailing test cases can be visualized:
python docs/stop-limit-chart-generator.py test-data/stop-limit/<filename.csv>
python docs/trailing-stop-chart-generator.py test-data/trailing-stop/<filename.csv>
Contributing
Contributions are welcome! Please see the documentation in the docs folder for algorithm details and test specifications.
Metadata
Release files for XXSim 0.24.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xxsim-0.24.0.tar.gz | 48.5 kB | Without provenance | Details for xxsim-0.24.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xxsim-0.24.0-py3-none-any.whl | Python 3 | none | any | Details for xxsim-0.24.0-py3-none-any.whl |
Total release size: 69.5 kB
Release files / xxsim-0.24.0.tar.gz
| Download URL | xxsim-0.24.0.tar.gz |
|---|---|
| Size | 48.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ed04def683b5320b69988722fa00c21d369164359db888d708fb0b1e9f42e3c
|
|
BLAKE2b-256 checksum How to use checksums |
d1841576dfa498919da78cfc62a1d82a9f2142b0154c535727c44d408afaaeb2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / xxsim-0.24.0-py3-none-any.whl
| Download URL | xxsim-0.24.0-py3-none-any.whl |
|---|---|
| Size | 21.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b5b765cd87c41577ccd55b16aa3729187323492f6f5d311fe86d50e1c74dff64
|
|
BLAKE2b-256 checksum How to use checksums |
507b373c7b4dfffda8c817fc5640c30949ff5ab26bc0ef68b1c10f342cca3d72
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for XXSim 0.24.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.