EduMatcher

Learn how real trading systems work. Build it from first principles.

Category Link
Repo URL GitHub
Package GitHub release PyPI version Python 3.13+
Documentation Documentation
CI/CD CI
Code Quality Coverage Code style: black Checked with mypy Linting: flake8
License License: MIT

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 four web applications:

curl -fsSL https://raw.githubusercontent.com/johan162/EduMatcher/main/deployment/curl/install.sh | bash
cd ~/.edumatcher && ./edumatcher.sh start

Then open http://localhost:8090 for the market display, http://localhost:8091 for the log console, and http://localhost:8093 for the trading terminal.

Prefer the 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.yaml which acts as the system reference data. To simplify its creation either Web-based tool (http://localhost:8092/) or a CLI tool pm-config-gen can be used. In addition it is of course possible to manually create a handwritten config file that can be verified with pm-cverifier. To guarantee correctness and that it is a single-source of truth the YAML file is then compiled and checked by pm-deploy-config to 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 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

  • Very limited authentication & authorization
  • 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

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.29.1}
}

License

MIT License - see LICENSE.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.34.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for johan162 from gravatar.com johan162

Credits

Author: Johan Persson

License

MIT License (MIT)

Requires

Python <4.0, >=3.13

Tags

finance exchange matching-engine trading education learning order-matching market-microstructure

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

edumatcher-0.29.1.tar.gz (1.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

edumatcher-0.29.1-py3-none-any.whl (1.4 MB view details)

Uploaded Python 3

File details

Details for the file edumatcher-0.29.1.tar.gz.

File metadata

  • Download URL: edumatcher-0.29.1.tar.gz
  • Upload date:
  • Size: 1.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.2 CPython/3.12.3 Linux/6.17.0-1022-azure

File hashes

Hashes for edumatcher-0.29.1.tar.gz
Algorithm Hash digest
SHA256 4c8501ea7cb3d9020b0971542cd1a0e57e8150fd4c3f606d89ecd57af9b4b675
MD5 5b2c0fd8914b732711e354119f84e79c
BLAKE2b-256 606ccba136541b81f867b73da05bf69fd1a3361a515c8d4fc7a6a41a82277864

See more details on using hashes here.

File details

Details for the file edumatcher-0.29.1-py3-none-any.whl.

File metadata

  • Download URL: edumatcher-0.29.1-py3-none-any.whl
  • Upload date:
  • Size: 1.4 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.4.2 CPython/3.12.3 Linux/6.17.0-1022-azure

File hashes

Hashes for edumatcher-0.29.1-py3-none-any.whl
Algorithm Hash digest
SHA256 fe37d684ec0870fd71d45c4ced04043ebf8fff8d574e53c8ac49a5a789973f84
MD5 91a5681e0183e8ea69e7ca41e17d89fa
BLAKE2b-256 3b41e556db9225985f48846914f9acb07efdf172d3f36d8ff2a3291b7bfcba37

See more details on using hashes here.

Release history Release notifications | RSS feed

0.34.0

2 files

0.33.1

2 files

0.33.0

2 files

0.32.0

2 files

0.31.0

2 files

0.29.2

2 files

This release

0.29.1 This release

2 files

0.29.0

2 files

0.28.1

2 files

0.28.0

2 files

0.27.3

2 files

0.27.2

2 files

0.27.1

2 files

0.27.0

2 files

0.26.3

2 files

0.26.2

2 files

0.26.1

2 files

0.26.0

2 files

0.20.4

2 files

0.20.3

2 files

0.20.2

2 files

0.20.1

2 files

0.20.0

2 files

0.19.1

2 files

0.18.0

2 files

0.17.0

2 files

0.16.2

2 files

0.16.1

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

0.13.5

2 files

0.13.4

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.5

2 files

0.12.4

2 files

0.12.3

2 files

0.12.2

2 files

0.12.1

2 files

0.12.0

2 files

0.11.0

2 files

0.10.1

2 files

0.10.0

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.0

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.9

2 files

0.1.8

2 files

0.1.6

2 files

0.1.5

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page