EduMatcher
Learn how real trading systems work. Build it from first principles.
| Category | Link |
|---|---|
| Package |   |
| Documentation |  |
| License |  |
| Release |  |
| CI/CD |  |
| Code Quality |    |
| Repo URL |  |
EduMatcher is an educational trading system that teaches market microstructure, matching logic, and exchange architecture through runnable code.
Why EduMatcher?
- Real exchange mechanics: order books, auctions, clearing, and risk controls
- Multi-process architecture: gateway, engine, audit, clearing, stats, and tooling
- Performance-aware implementation: ~80,000 orders/second with microsecond latency on a Linux server
- Practical protocol design: ALF (ALmost Fix) command language for gateway order entry, RALF (Reconciliation ALF) for post trade consumers and CALF (Channel ALF) to serve market data to subscribers, and finally BALF (Binary ALF) for high performance trade clients
- Strong engineering discipline: type hints, linting, and high test coverage
Key Features
- Complete lifecycle: order entry, matching, clearing, and audit trail
- Rich order support: MARKET, LIMIT, STOP, STOP_LIMIT, IOC/FOK, ICEBERG, combo, OCO
- Market mechanisms: opening/closing auctions
- Risk handling with circuit breakers and price collars
- Message-based process boundaries with strong observability
- Implement real risk controls such as prioce-collar, kill-switch, circuit-breaker, and mass-cancel
- Easy to understand configuration through single source
engine_config.yamlwhich acts as the system reference data. To simplify its creation a CLI toolpm-config-gencan be used and a handwritten config file can be verified withpm-cverifier
Documentation
Main documentation site EduMatcher Documentation that among other things includes:
- How an Exchange Works: a primer on exchange mechanics and market microstructure concepts aimed at software developers with no prior financial experience
- Exchange Concepts: deep dive in core technical concept of an exchange
- User Guide: step-by-step instructions for installation, configuration, and running EduMatcher
- Training Material: self-paced exercises to learn how to setup and manage the Exchange
- Architecture: an overview of the SW architecture
- Developer Guide: deep dive into the architecture, design decisions, and code structure. Necessary reading for anyone wanting to contribute!
- Glossary: the finance world uses lot of specialized terms, this glossary lists the most important with an explanation
Installing
Note: Running an exchange is an inherent complex task and unfortunately it is only so much that can be simplified. However, going throught the user guide and training material should give a great start!
Performance
EduMatcher does not aim to match venues like NYSE or LSE, but it is still fairly fast for a purely Python educational project. The figures below reflect the performance on an high end Linux server with risk checks enabled (price collar and circuit-breaker).
Latency (engine-only, n=1,000 each)
| Order type | min (µs) | median (µs) | P80 (µs) | P90 (µs) | max (µs) |
|---|---|---|---|---|---|
| Limit | 13.1 | 15.0 | 15.4 | 15.7 | 155.7 |
| Market | 12.1 | 13.9 | 15.2 | 15.7 | 73.6 |
Throughput
| Metric | Value |
|---|---|
| Max TPS | ~81,000 orders/second |
| µs / order (mean) | 12.4 µs |
| Order mix | 20% Market, 30% aggressive Limit, 50% passive Limit |
Performance note: price-collar and circuit-breaker checks run in the hot path for every match. They are required for realistic risk control and add measurable cost.
Key Functional and Infrastructure Limitations
- No spread-order books
- No implied (synthetic) orders
- No primary-secondary automatic site failover
- No load balancing
- Limited replay for participants that lose the connection
- MARKET orders are rejected during a circuit-breaker halt rather than joining
the reopening auction. Both Nasdaq and Xetra accept them into the call; here
the uncross prices interest by book level, so unpriced interest has no level
to sit at and would be invisible to
compute_equilibrium() - The ACE expansion ladder is exchange-wide only (see below)
Possible Future Extensions
Per-symbol ACE expansion ladders. A symbol may currently override the
starting corridor (initial_band_pct), whether ACE applies at all, and the
random-end bound — but not the expansion ladder itself, which is rejected on a
symbol (pm-cverifier S112).
The reasoning is that the starting corridor describes the instrument (a thin small-cap needs a wider reopening corridor than a liquid blue chip), while the escalation schedule describes the venue's willingness to keep an instrument suspended, and uniformity there is what makes halt durations comparable across the book.
That line is defensible rather than airtight. min_duration_ns lives in the
ladder and is arguably instrument-shaped: a thin name may need longer call
phases simply for liquidity to arrive. Real venues disagree — Nasdaq varies
nothing per security, while Deutsche Börse's ACE publishes corridor widths
and durations per instrument in reference data.
Lifting the restriction would mean: dropping the loader guard and S112;
teaching the Config GUI a per-symbol ladder editor (a list of rungs does not
fit a table cell, so it needs a dialog); and giving pm-config-gen a way to
express a ladder that is not a comma-separated --symbol-opts value. The
engine's merge already treats a symbol ladder as all-or-nothing, so the
runtime side is close to free — the cost is almost entirely in the tooling.
Citation
If you use this tool in teaching or courses, please cite:
@software{edumatcher,
title = {EduMatcher},
author = {Johan Persson},
year = {2026},
url = {https://github.com/johan162/EduMatcher},
version = {0.18.0}
}
License
MIT License - see LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file edumatcher-0.18.0.tar.gz.
File metadata
- Download URL: edumatcher-0.18.0.tar.gz
- Upload date:
- Size: 562.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.12.3 Linux/6.17.0-1020-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d85853865e82ff3d3048bd0a3733ddc20f64925c8375ed52c97a098530e6a994
|
|
| MD5 |
588973fa0df731e6eb89d418e1ee68f2
|
|
| BLAKE2b-256 |
142b40352f5381cb23294ae4cc624d7dbd84d5a21c5f337e6dd4e742437afa46
|
File details
Details for the file edumatcher-0.18.0-py3-none-any.whl.
File metadata
- Download URL: edumatcher-0.18.0-py3-none-any.whl
- Upload date:
- Size: 659.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.12.3 Linux/6.17.0-1020-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1d869c0fadb765306fa986af141f8abc9c286997132cb09611377401d8829e13
|
|
| MD5 |
3232d0c8522a1290337e6a81ab027067
|
|
| BLAKE2b-256 |
87acdf0d860084915234ba53c9dd7676b7551afeedcfbdfa099accc37994b898
|
