EduMatcher Documentation¶
EduMatcher is an educational stock exchange you can run on your own computer. It has a real matching engine and order books, a trading day with opening and closing auctions, market makers, risk controls, statistics, profit-and-loss tracking, an audit trail, external protocols and trading bots — close to a real exchange in architecture and behavior, and built for learning how exchanges work in practice.
Figure 1: The exchange, with order books and the central matching engine.
Start here¶
| Step | Time | |
|---|---|---|
| 1 | New to markets? Read How an Exchange Works. It explains order books, bids and asks, auctions and market makers without assuming any finance background. | an evening |
| 2 | Everyone: work through the Quick Start Guide. It installs the exchange, takes you through your first trade and a full trading day, and ends with your own configuration. | 1–3 hours |
| 3 | Then choose your book by what you want to do next — see the map and the table below, or the Quick Start's Choose Your Next Book. | — |
With Podman or Docker installed, this one command gets you a running exchange and its five browser applications; the Quick Start's Install and Start chapter explains what happens next:
curl -fsSL https://raw.githubusercontent.com/johan162/EduMatcher/main/deployment/curl/install.sh | bash
The library¶
The documentation is a library of nine books. Each is written for one kind of reader and one kind of task, so most people need only two or three of them.
flowchart TD
B0["How an Exchange Works\nthe concepts, no software"]
QS["Quick Start Guide\ninstall, first trade, next steps"]
TG["Training Guide\nhands-on exercises"]
PG["Participant Guide\ntrade, make markets, run bots"]
OG["Operator's Guide\ninstall, configure, run, recover"]
PC["Protocols and Clients\nconnect your own program"]
AD["Architecture and Developer Guide\nhow it is built, how to change it"]
RM["Reference Manual\nevery command, field and term"]
AI["AI Traders and Market Simulation\nan exchange that trades itself"]
B0 -.->|"new to markets?"| QS
QS --> AI
QS --> TG
QS --> PG
QS --> OG
QS --> PC
QS --> AD
TG -.->|"background"| PG
TG -.->|"background"| OG
PG -.->|"look up"| RM
OG -.->|"look up"| RM
PC -.->|"look up"| RM
AD -.->|"look up"| RMWhich books are for you¶
● = written for you, ○ = useful later
| Book | Student / trader | Instructor / operator | Client developer | Contributor |
|---|---|---|---|---|
| How an Exchange Works — exchange concepts without software | ● | ● | ● | ○ |
| Quick Start Guide — install, first trade, first session | ● | ● | ● | ● |
| Training Guide — 29 chapters of hands-on exercises | ● | ● | ○ | ○ |
| Participant Guide — orders, auctions, market making, bots, P&L, trading screens | ● | ● | ○ | ○ |
| Operator's Guide — install, configure, run, supervise and recover an exchange | ○ | ● | ○ | ○ |
| Protocols and Clients — the wire protocols, APIs and client examples | ○ | ● | ○ | |
| Architecture and Developer Guide — the design, the code and how to change it | ○ | ● | ||
| Reference Manual — commands, configuration fields, glossary | ○ | ● | ● | ● |
| AI Traders and Market Simulation — a market that trades itself: AI traders, hidden true values, news, the simulation container | ○ | ● | ○ | ○ |
I want to…¶
| I want to… | Start here | Then |
|---|---|---|
| understand what an exchange does | How an Exchange Works | Quick Start: What EduMatcher Is |
| see EduMatcher run | Quick Start: Install and Start | Your First Trade |
| learn by doing, step by step | Training Guide | the chapters in order |
| trade or make markets | Participant Guide: The Order Book | Order Types |
| leave a live, simulated market running for a class | AI Traders: Ten-Minute Start | The True Value |
| run an exchange for a class | Operator's Guide: Installation | Running the Exchange |
| find out why an order was rejected | Participant Guide: The Trader Console | Operator's Guide: Risk Controls |
| fix a configuration or startup problem | Quick Start: When Something Does Not Work | Operator's Guide: Configuration Verifier |
| connect my own program | Protocols and Clients: Protocols Overview | the protocol's specification in Part II |
| understand or change the code | Architecture | Development Practice |
| look up a command, field or term | Reference Manual | Glossary |
Download the books¶
Every book is also available as an EPUB, for e-readers, screen readers and adjustable text size:
| Book | EPUB |
|---|---|
| 📖 Quick Start Guide | ⬇️ Download |
| 📖 Participant Guide | ⬇️ Download |
| 📖 Operator's Guide | ⬇️ Download |
| 📖 Reference Manual | ⬇️ Download |
| 📖 Protocols and Clients | ⬇️ Download |
| 📖 Architecture and Developer Guide | ⬇️ Download |
| 📖 Training Guide | ⬇️ Download |
| 📖 AI Traders and Market Simulation | ⬇️ Download |
Each book is also published as PDF on every GitHub release:
| Format | Best for |
|---|---|
| A4 light | Printed reference copies |
| B5 light | Compact print and tablets |
| A4 or B5 dark | Screen reading in low light |
| Chapter PDF | Sharing one focused chapter |
Contributors can build every format from a checkout with the targets in
docs/Makefile (make help in the docs/ directory).
What EduMatcher deliberately leaves out¶
EduMatcher keeps the parts of a real exchange that matter for learning and simplifies the rest:
- Authentication and authorization are minimal. There is no hierarchy of members, firms and users; participants are identified by a configured ID.
- There is no fault tolerance. No hot-standby system, replication or failover; one machine runs the whole exchange.
- Implied (synthetic) orders are not supported. The Participant Guide explains the concept in Implied Orders.
- Combo orders are not atomic. They are a thin layer over the individual order books, not a book of their own.
The Reference Manual's Known Limitations lists the rest.
Not for real trading
EduMatcher is for teaching and experimenting in a controlled environment. Never use it for real financial transactions.