⚡ Crypto Matching Engine

A high-performance cryptocurrency matching engine implementing REG NMS-inspired principles of price-time priority and internal order protection, with real-time market data streaming and trade execution reporting.

---

🚀 Features

✅ Matching Engine Core (REG NMS Principles)

• Best Bid & Offer (BBO) Maintenance
  Maintains an accurate, real-time view of the best bid and offer for each trading pair.

• Price-Time Priority
  Orders at the same price level are matched on a strict FIFO basis.

• Internal Order Protection
  Ensures no incoming order trades through better resting prices.

• Supported Order Types:

  • Market: Fills immediately at best available prices.
  • Limit: Fills at limit price or better; rests if not marketable.
  • IOC: Executes immediately; cancels unfilled portion.
  • FOK: Executes fully at best prices or cancels entirely.

---

🌐 API Overview

📥 Order Submission API (HTTP REST)

• Endpoint: POST /submit_order
• Payload Example:

   {
   "symbol": "BTC-USDT",
   "order_type": "limit",
   "side": "buy",
   "quantity": 1.5,
   "price": 29500.0
   }

• Order Types:
  • market
  • limit
  • ioc
  • fok

📈 Market Data API (WebSocket)

• Endpoint: ws://<host>:<port>/ws/market_data
• Message Sent (on new BBO or book update):

   {
   "timestamp": "2025-06-19T12:30:45.123456Z",
   "symbol": "BTC-USDT",
   "asks": [["29510.00", "1.2"], ["29515.00", "0.5"]],
   "bids": [["29500.00", "2.0"], ["29495.00", "3.1"]]
   }

• Streams:
  • BBO updates
  • Order book depth (top N levels)

💥 Trade Execution Feed (WebSocket)

• Endpoint: ws://<host>:<port>/ws/trades
• Message Sent (on every execution):

   {
   "timestamp": "2025-06-19T12:30:46.654321Z",
   "symbol": "BTC-USDT",
   "trade_id": "TRADE-872312",
   "price": "29500.00",
   "quantity": "0.8",
   "aggressor_side": "buy",
   "maker_order_id": "ORDER-6523",
   "taker_order_id": "ORDER-7890"
   }

• Real-time notifications for:
  • Price
  • Quantity
  • Maker/Taker ids
  • Aggressor side

---

🏗 Architecture Overview

+-------------------+       +-------------------+
|  REST API Server  | <---> |   Matching Engine |
+-------------------+       +-------------------+
       |                             |
       |                             |
       V                             V
+------------------+       +---------------------+
| WebSocket Server |<----->| Trade & Market Feed |
+------------------+       +---------------------+

• Thread-safe design
• Per-symbol order books
• Asynchronous dissemination of market and trade data

---

🧪 Running the Project

📦 Dependencies

• C++20 or later
• Crow Web Framework
• Cmake

🛠 Build Instructions

mkdir build && cd build
cmake ..
make

🧬 Run the Server

./matching_engine

Server starts at http://localhost:8080

---

📝 TODO

• Add robust error handling for invalid inputs and edge cases.
• Integrate logging for diagnostics, events, and debugging.
• Write unit tests for matching logic and order operations.

📚 Future Enhancements

• Add advanced order types: Stop-Loss, Stop-Limit, Take-Profit.
• Implement persistence for order book recovery after restarts.
• Benchmark and optimize latency, concurrency, and data structures.
• Add a simple maker-taker fee model with execution fee reporting.