Skip to main content

EduMatcher

Learn how market microstructure end exchanges works through simulation.

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

Introduction

EduMatcher is an educational trading simulation system that teaches financial market microstructure, principles, matching logic, and exchange architecture through runnable code paired with extensive documentation and references.

It is based on public- and academic-research literature, including the following primary references:

  • Harris, Larry. Trading and Exchanges: Market Microstructure for Practitioners. Oxford University Press, 2003. ISBN 978-0-19-514470-3.
  • Natenberg, S. Option Volatility and Pricing. McGraw-Hill, 2nd edition, 1994. ISBN 978-1-55738-486-7
  • Hasbrouck, Joel. Empirical Market Microstructure: The Institutions, Economics, and Econometrics of Securities Trading. Oxford University Press, 2007. ISBN 978-0-19-530164-3
  • CME Group, Matching Algorithms Explained. Link
  • CME Group, Matching Algorithm Reference. Link
  • NYSE Pillar, Pillar Functional Differences Guide, Link
  • NYSE, Order Type Matrix, Link
  • Eurex, Matching Principles. Link
  • Eurex, How the market works (price collars, etc). Link

It is a simulation of an exchange, not a simulation of one component: 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.

Quick start

A buzzling and hustling live simulated exchange with 100 of other traders

With Podman or Docker installed, one command gets you a running simulation with 300 made up symbols for fictious companies in different sectors and 100 automated traders that you can watch live and connect to and trade to/with. This is a sophisticated simulation with an advanced market model including news and roumours that affects price discovery. Its the best way to get a feeling of trading in a market. The simulation itself produces around 3 million orders per day.

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

A clean quet simulated exchange with only you as a trader

With Podman or Docker installed, one command gets you a running simulation and five web applications with only two default traders. This will be a silent market as only your actions will move it.

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

The simulation exchange is now running on a bundled configuration.
The pm-* commands, the control plane of the exchange, lives inside the container.

Commands to try

Regardless if you started an empty or populated simulation you run it and trade within it in the exact same way:

The install script will print out more information at startup. To get started open a shell within the container:

cd ~/.edumatcher-sim     # Everything lives in this directory
./edumatcher.sh shell    # Open a shell within the container
pm-help                  # Print help of all available commands
pm-alf-console           # Open the ALF console to interact with the market (send orders)

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
Clearing read-only  :  http://localhost:8096

# 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. The web applications are not in the package, but they are published as ready-built containers and can be run next to your pipx exchange (plain or simulation) with curl -fsSL https://raw.githubusercontent.com/johan162/EduMatcher/main/deployment/curl/install.sh | bash -s -- --guis. 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.

Documentation

Main documentation site EduMatcher Documentation that among other things includes:

*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!

Key Features

  • Complete lifecycle: order entry, matching, clearing, and audit trail
  • End-of-day settlement (pm-eod): daily mark-to-market settlement in a fictional currency, a statement for every trader, and automatic housekeeping (audit archive, log compression, verified database backups)
  • 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.

Limitations

  • Limited authentication & no authorization
  • Only rudimentary settling and clearing mechanisms (no margining or collateral management)
  • Basic set of order types
  • No combo-order books (combo orders are supported with coupled order books)
  • No implied (synthetic) orders
  • No primary-secondary site failover
  • 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. For business-focused assertions and test-design expectations, see the testing guidelines and the test methodology and efficiency workplan. 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.82.0}
}

License

MIT License - see LICENSE.

Metadata

Release files for edumatcher 0.82.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for edumatcher 0.82.0
File Size Uploaded Provenance Actions
edumatcher-0.82.0.tar.gz 2.7 MB Without provenance Details for edumatcher-0.82.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for edumatcher 0.82.0
File Interpreter ABI Platform Actions
edumatcher-0.82.0-py3-none-any.whl Python 3 none any Details for edumatcher-0.82.0-py3-none-any.whl

Total release size: 5.8 MB

Release files / edumatcher-0.82.0.tar.gz

Download URL edumatcher-0.82.0.tar.gz
Size 2.7 MB
Tags Source
SHA-256 checksum
How to use checksums
bf52030ea484f2ab594fcda1887230e4ee651da8251667d0466918db9c318ff7
BLAKE2b-256 checksum
How to use checksums
59eb729b48d37744c82ec164aa321306f814a654615179bb85d95ad3d8dbc268
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.14.4 Linux/7.0.0-1019-azure

Release files / edumatcher-0.82.0-py3-none-any.whl

Download URL edumatcher-0.82.0-py3-none-any.whl
Size 3.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
d29b7e037e23d47fcd485e766085c66ae6e8f1473465e6abb254f7302e002094
BLAKE2b-256 checksum
How to use checksums
8b97a8d4486fef04424d1555e4c75623df7ceb2f20e8eabef7319c1c8abfebfd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.14.4 Linux/7.0.0-1019-azure

Security for edumatcher 0.82.0

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.

Release history Release notifications | RSS feed

This release

0.82.0 This release

2 release files No provenance

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