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
A clean exchange with only you as a trader
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. The exchage now
waits for you to make a move! If you feel it is lonely inthe exchange being the only trader, read the next
section!
A buzzling and hustling live simulated exchange with 100 of other traders
With Podman or Docker installed, one command gets you a running exchange with 300 symbols and 100 of automated traders that you can watch live and connect to. This is a sophisticated simulation with an advanced market model including news and roumours that affects price discovery.
curl -fsSL https://raw.githubusercontent.com/johan162/EduMatcher/main/deployment/curl/install.sh \
| bash -s -- --sim
cd ~/.edumatcher-sim
Commands to try
Regardless if you started an empty exchange or the simulated exchange you run it and trade within it in the exact same way:
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 exchange operator dashboard
Operator dashboard: http://localhost:8095
# 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 :
# Configuring the exchange reference data
Config builder : http://localhost:8092
Run from a plain Python pip/x
Prefer a Python package? pipx install edumatcher, then pm-setup. Both
routes, and three more, are covered in
Installation.
New here? The Quick Start Guide takes you from the command above to a first trade, a full trading day and 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: ~25,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
- Quick Start Guide: install, first trade, a full trading day and your own configuration, step by step
- Participant Guide, Operator's Guide, Protocols and Clients and Reference Manual: trading, running an exchange, connecting clients, and looking things up
- Training Material: self-paced exercises to learn how to setup and manage the Exchange
- AI Traders and Market Simulation: an exchange that trades itself — AI traders, hidden true values, news and rumours — in one container that runs for weeks
- 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 and still keep it realistic. 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 with a thorethical throughput of somewhere between 25,000 - 30,000 TPS 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.51.5}
}
License
MIT License - see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for edumatcher 0.51.5
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 | |
|---|---|---|---|---|
| edumatcher-0.51.5.tar.gz | 2.0 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| edumatcher-0.51.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.2 MB
Release files / edumatcher-0.51.5.tar.gz
| Download URL | edumatcher-0.51.5.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7317a1d9ff3a60d24c029c0ff238aba707c7dd9289b5b4f299353d299c44810e
|
|
BLAKE2b-256 checksum How to use checksums |
46201b9202062b18bd3b84898f5dbd8cb2f7bf15628538a1a1ced111d80a7c7b
|
| 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.51.5-py3-none-any.whl
| Download URL | edumatcher-0.51.5-py3-none-any.whl |
|---|---|
| Size | 2.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5c4d119c07b2327f42cd46531673df163c3d22680ec1843a1756e2d0e08cd7d0
|
|
BLAKE2b-256 checksum How to use checksums |
6f24d1838ac1a08f98fbe2c1fe23e45024318ffdaa256ad6331a53c1a964010c
|
| 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
|
Security for edumatcher 0.51.5
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.
