EduMatcher
Learn how real trading systems work. Build it from first principles.
| Category | Link |
|---|---|
| Repo URL |  |
| Package |    |
| Documentation |  |
| CI/CD |  |
| Code Quality |     |
| License |  |
EduMatcher is an educational trading system that teaches market microstructure, matching logic, and exchange architecture through runnable code.
It is a real exchange, not a simulation of one: a matching engine, a session scheduler, order-entry and market-data gateways, clearing, audit and statistics services, browser front-ends, and its own wire protocols — all running as separate processes that talk to each other the way a real venue's do.
Quick start
With Podman or Docker installed, one command gets you a running exchange and five web applications:
curl -fsSL https://raw.githubusercontent.com/johan162/EduMatcher/main/deployment/curl/install.sh | bash
cd ~/.edumatcher
The exchange is now running on a bundled configuration.
The pm-* commands, the control plane of the exchange, lives inside the container.
Use regular Docker/Podman command to open a shell in the conainer or use the shortcut:
./edumatcher.sh shell # then pm-help, pm-admin, pm-alf-console, pm-stats-cli, ...
Once inside the container, start with reviewing available commands
pm-help
Then, on your host, open a browser and go to the following URLs for the more user-friendly ways to trade and watch the market:
# The trading platform to buy/sell equities. Requires log-in using
# one of the API keys defined in the `engine_config.yaml`
Trader GUI : http://localhost:8093.
# The terminal to watch the movements of the market
Trading terminal : http://localhost:8090
# One symbol's full order book, session statistics and trade tape
# (the browser companion to the pm-viewer command)
Order book : http://localhost:8094
# The central log server to observe what is happening internally
# in the exchange platform
Log viewer : http://localhost:8091
# The Swagger REST-API documentation. The exchange can be
# completely run using REST commands
REST API docs : http://localhost:8080/docs
Configuring the exchange can be done by either 1) Manually edit the config YAML file (and then verify/lint it with pm-cverifier) or, 2) generate it in scripts using the pm-config-gen tool or, 3) using the Web application reachable at :
Config builder : http://localhost:8092
Prefer a Python package? pipx install edumatcher, then pm-setup. Both
routes, and three more, are covered in
Installation.
New here? A Path Through the Guide is a staged route from the command above to running a venue of your own, with a checkpoint at every step.
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
- Real risk controls: price collars, kill switch, circuit breakers, and mass cancel
- Easy to understand configuration through single source
engine_config.yamlwhich acts as the system reference data. To simplify its creation either Web-based tool (http://localhost:8092/) or a CLI toolpm-config-gencan be used. In addition it is of course possible to manually create a handwritten config file that can be verified withpm-cverifier. To guarantee correctness and that it is a single-source of truth the YAML file is then compiled and checked bypm-deploy-configto be automatically stored in the canonical location used by the system.
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
Note: Running an exchange is an inherently complex task and there is only so much that can be simplified. The user guide and training material are built to get you through it.
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 | 47.785 | 49.702 | 50.748 | 53.206 | 84.664 |
| Market | 47.209 | 49.428 | 50.571 | 54.191 | 89.989 |
Throughput
| Metric | Value |
|---|---|
| Max TPS | ~29,122 orders/second |
| µs / order (mean) | 34.3 µ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
- Limited authentication & no authorization implemented
- No combo-order books (combo orders are supported with coupled order books)
- No implied (synthetic) orders
- No primary-secondary automatic site failover
- 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 (Automated Collar Expansion) ladder is exchange-wide only, not per symbol
- No replay functionality on the bus for clients connecting after the opening
Contributing
Contributions are welcome. Start with the Developer Guide, which covers the development environment, testing and the conventions this project follows, then open an issue or pull request on GitHub.
Release notes for every version are in CHANGELOG.md.
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.43.1}
}
License
MIT License - see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for edumatcher 0.43.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| edumatcher-0.43.1.tar.gz | 1.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| edumatcher-0.43.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.3 MB
Release files / edumatcher-0.43.1.tar.gz
| Download URL | edumatcher-0.43.1.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
24e0851600efd13ab5df0f89d1e128ed5fae4657c88e840b606110b25ab716d2
|
|
BLAKE2b-256 checksum How to use checksums |
c384041fbf2906ac713d095d421a3b53382bf84e96ca03173b907d63e9f6a889
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.12.3 Linux/6.17.0-1022-azure
|
Release files / edumatcher-0.43.1-py3-none-any.whl
| Download URL | edumatcher-0.43.1-py3-none-any.whl |
|---|---|
| Size | 1.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
684682f2f26915b3f033ac83d0a01a93b30a01c5e2bdeb7ef3a31b6d4a8e2017
|
|
BLAKE2b-256 checksum How to use checksums |
69713b0c1c459d574e4bd85dff1047686123d02ca7e75ef4ec63b466fa00167b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.12.3 Linux/6.17.0-1022-azure
|
