edumatcher 0.12.3

Educational multi-process trading system with order matching

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: ~60,000 orders/second with microsecond latency
• 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
• 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.yaml which acts as the system reference data. To simplify its creation a CLI tool pm-config-gen can be used and a handwritten config file can be verified with pm-cverifier

Key Functional Limitations

• No spread-order books
• No implied (synthetic) orders

Key Infrastructure Limitations

• No primary-secondary automatic site failover
• No load balancing
• Limited replay for participants that lose the connection

Performance

EduMatcher does not aim to match venues like NYSE or LSE, but it is still fairly fast for a pure Python educational project. The figures below reflect the performance on an Intel MacBook Pro. On an ARM M1 MacBook the throughput is roughly 150,000 TPS (an improvement of almost 150%). Latencies are about 25% lower.

It would be an interesting exercise rewriting this project in Rust.

Latency (engine-only, n=1,000 each)

Order type	min (µs)	median (µs)	P80 (µs)	P90 (µs)	max (µs)
Limit	8.1	8.5	9.6	10.0	18
Market	8.1	8.5	8.8	9.3	45

Throughput

Metric	Value
Max TPS	~60,000 orders/second
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.

Documentation

Main documentation site EduMatcher Documentation that among other things includes:

• Installation Guide: how to get up and running with EduMatcher
• User Guide: step-by-step instructions for installation, configuration, and running EduMatcher
• Developer Guide: deep dive into the architecture, design decisions, and code structure-
• Training Materials: self-paced exercises to learn how to setup and manage the Exchange
• How an Exchange Works: a primer on exchange mechanics and market microstructure concepts aimed at software developers with no prior financial experience

Contributing

This is an educational project. If you find bugs, improve the documentation, or make other enhancements PRs are welcome!

Setup a running system

ALTERNATIVE 1: Using a Multipass VM

Pre-Reqs

Requirement	Notes
Multipass	A lightweight VM manager. Install from multipass.run
curl	Used to download the VM bootstrap script
Internet access	Required for downloading scripts and PyPI packages
Host resources	Recommended minimum: 2 vCPU, 3 GB RAM, 8 GB disk

Bootstrap with one command

curl -fsSL https://raw.githubusercontent.com/johan162/EduMatcher/main/vm/curl_setup_vm.sh | bash -s -- --version 0.12.3 --snapshot

This command downloads the VM setup scripts, launches a Multipass VM, installs EduMatcher in the VM, links all process commands in the exchange pm-* commands into /usr/local/bin, prepares /home/ubuntu/session, and takes an initial snapshot to allow you to easily reset the environment.

Start the CME (Central Matching Engine) in the VM

multipass shell edumatcher-vm
cd /home/ubuntu/session
pm-engine --verbose

Open additional host terminals and run multipass shell edumatcher-vm in each terminal to start pm-gateway, pm-viewer, pm-clearing, and pm-audit.

Note: Running the exchange is complex enough that you really need to read the documentation and follow the instructions in the User Guide to get a full exchange up and running. The above commands are just a quick start to get you going. The User Guide will explain how to configure the exchange, start and stop processes, and run the system in a realistic way.

ALTERNATIVE 2: Local Python Installation via pipx

1. Install Python 3.13+ and Poetry (or use the VM setup below)
2. Install pipx (pip install pipx or on MacOS brew install pipx)
3. Bootstrap a new session directory and either generate engine_config.yaml with sane defaults, or start from the sample config copied by pm-setup:

pipx install edumatcher
mkdir session
cd session
pm-setup
pm-config-gen --symbols AAPL MSFT --gateways TRADER01 TRADER02 OPS01:ADMIN --sessions-enabled --output engine_config.yaml
pm-engine --verbose

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

License

MIT License - see LICENSE.