Crypto market microstructure research on a practical question: does a short-horizon signal survive the cost of executing it?
The Python toolkit connects causal quote and trade features to chronological model selection, a stateful execution simulator and provenance checks. A small C++ component cross-checks order-book replay. Spread, fees, latency, available liquidity, inventory and adverse selection are part of the research question.
Research status: the resumed 48-fit experiment is complete. Its best new candidate reached 57.313% balanced accuracy versus 57.341% for the retained complete control; none passed the expansion gate. Research continues toward predictive accuracy. A substantial independent improvement and executable alpha have not been established. The research summary distinguishes completed findings from pending validation.
Python 3.9 or newer is required; Python 3.11 or 3.12 is recommended. The core package has no third-party runtime dependencies.
git clone https://github.com/hlemonnier/microstructure-alpha-lab.git
cd microstructure-alpha-lab
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/microstructure-alpha-lab --help
make e2e PYTHON=.venv/bin/pythonThe E2E command builds source and wheel distributions, installs the wheel in a fresh environment, runs the synthetic research pipeline, verifies its artifacts and compares Python with C++ replay. It installs pinned build tools from PyPI. It uses committed fixtures, with no market-data downloads, credentials or cloud jobs. A C++17 compiler, make, bash, rsync and zip are needed for the complete check.
Each run writes a separate directory under artifacts/public_e2e/, containing evidence.json, checksums, logs, source packages and synthetic result ledgers. Run it from a clean, committed checkout so the evidence identifies the exact source revision. See reproducibility for optional model dependencies and advanced workflows.
- Check what the source actually records and when each observation becomes available.
- Build causal features and declare an untouched holdout before model selection.
- Compare complete procedures on chronological development splits, with purging and validation-only selection.
- Simulate orders, fills, cash and inventory under explicit execution assumptions.
- Bind inputs, configuration, checkpoints and outputs to hashes before interpreting results.
| Component | Purpose | Entry point |
|---|---|---|
| Features and timing | Completed buckets, raw flow and explicit decision/entry/exit clocks | Pipeline |
| Selection and holdouts | Chronological splits, frozen candidates and one-way final evaluation | Methodology |
| Execution | Maker/taker orders, partial fills, fees, latency and risk limits | Expected edge |
| Inference | Dependence-aware intervals and procedure-level multiple-testing records | Statistical and model contracts |
| L2 replay | Snapshot/delta validation, gap detection and Python/C++ parity | Replay contract |
Optional research dependencies support ridge, tree and sequence-model experiments. Neural fixture runs demonstrate pipeline wiring; empirical claims require sufficient replay-grade data and separate validation.
Market data, trained checkpoints and generated results are kept outside Git. A fresh clone includes only synthetic CSV fixtures and the data acquisition guide.
Binance Vision bookTicker and trade archives support quote/trade research. Its bookDepth files contain percentage-band aggregate depth; genuine L2 replay requires snapshot/delta data from an appropriate source. Read data source reality before selecting a dataset or interpreting a model.
Software verification and empirical validation have separate requirements:
| Evidence | Current scope |
|---|---|
| Synthetic E2E | Reproducible checks of holdout filtering, selection, simulation, packaging and replay |
| Historical studies | Exploratory comparisons; cohorts, controls and limitations are stated in each report |
| Independent confirmation | The substantial-gain requirement has not been met |
| Executable alpha | Unestablished; full confirmatory economics and observed-fill validation remain pending |
| Midpoint conversion study | All 48 fits completed; no candidate passed the predictive expansion gate |
Historical protocols and evidence inventories remain at their original paths to preserve their hashes. Older implementation counts and artifacts are dated records, not the current verification result. make verify-evidence-gates is an empirical audit and may fail when required studies are missing; a green CI run does not close those gates.
src/lob_forge/ Research toolkit and command-line interface
cpp/ C++17 L2 replay reference
examples/fixtures/ Small synthetic inputs
scripts/ Verification, data acquisition and study runners
tests/ Existing implementation regression suite
docs/ Methodology and runbooks
docs/research/ Dated protocols, findings and evidence inventories
Start with the documentation index, research summary or contribution guide. The implementation traceability records the historical remediation work.
The code and repository documentation are available under the MIT License. External datasets and third-party dependencies retain their own terms. Citation metadata is provided in CITATION.cff.