High-performance C++ matching engine and live market simulation dashboard built around a custom intrusive order-book core, Abseil-backed containers, real-time WebSocket streaming, and bounded agent-based microstructure dynamics.

Mercury is a low-latency trading engine implementing a full limit order book with price-time priority matching. It ships with a localhost HTTP/WebSocket server, a React dashboard for live visualization, and a unified market simulation runtime where manual browser orders, replayed flow, and built-in agents all trade through the same engine thread.

Key Metrics:

• 3.2M+ orders/sec sustained throughput
• ~320 ns average order insertion latency
• O(1) order lookup, insertion, and cancellation
• 248 backend tests, all passing
• Nanosecond gateway-to-engine latency instrumentation

• Order Types: Limit, Market, Cancel, Modify
• Time-in-Force: GTC (Good-til-Canceled), IOC (Immediate-or-Cancel), FOK (Fill-or-Kill)
• Price-Time Priority: FIFO matching at each price level
• Self-Trade Prevention: Client ID based filtering
• Risk Management: Pre-trade risk checks with position/exposure limits
• P&L Tracking: Realized and unrealized P&L with FIFO cost basis
• Unified Market Runtime: One runtime for manual orders, replay, built-in agents, and headless simulation
• Built-In Agents: Passive market maker, aggressive momentum trader, mean-reversion bot, Poisson-flow noise trader
• Advanced Microstructure: Queue-position-aware agents, deeper multi-level market-maker quoting, and toxicity-driven spread widening
• Regime Manager: Auto-detected calm/normal/stressed regimes with explicit Poisson λ controls for limit, cancel, and marketable arrival rates, plus Pareto order-size dispersion for whale-vs-retail flow
• Live Server: HTTP order entry + dual WebSocket market data (JSON and binary)
• React Dashboard: Real-time ladder, trade tape, mid-price chart, order entry, P&L, simulation controls, system health
• Latency Telemetry: Nanosecond-precision tracking from gateway entry through engine to publication
• Throughput Monitoring: Messages-per-second counter broadcast to the dashboard
• Bounded Volatility Presets: low, normal, and high widen spread and increase activity without runaway 100% to 1000% price jumps in seconds
• Binary Protocol: Packed wire-format structs for high-throughput market data consumers

┌─────────────────────────────────────────────────────────────────────────────┐
│                            React Dashboard                                 │
│  Order Entry │ PnL │ Sim Controls │ Ladder │ Tape │ Chart │ System Health │
│                  Zustand Store ← WebSocket ← /ws/market                    │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │ HTTP POST /api/orders
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                           OrderEntryGateway                                │
│            JSON parse → latency stamp → MarketRuntime::submitOrder()       │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                             MarketRuntime                                  │
│  Simulation loop │ Environment │ Agent registry │ Replay │ Runtime fanout  │
│  manual orders + replay + built-in agents → shared submission path         │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                             EngineService                                  │
│   Engine thread (single writer) │ PnL tracker │ stats │ sequencing         │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                            MatchingEngine                                  │
│    Validation → Matching → Book mutations → trade/execution callbacks      │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────────────┐
│                          MarketDataPublisher                               │
│     JSON /ws/market                     Binary /ws/market/bin              │
└─────────────────────────────────────────────────────────────────────────────┘

The core book keeps intrusive FIFO queues inside each price level while using absl::btree_map for sorted bid/ask ladders and an Abseil-backed HashMap wrapper for O(1) average order lookup.

The React frontend (/frontend) provides a real-time market-operations interface:

mercury/
├── include/                    # Headers
│   ├── Order.h                 # Order, Trade, ExecutionResult types
│   ├── OrderBook.h             # Order book with Abseil ladders + intrusive FIFO levels
│   ├── MatchingEngine.h        # Price-time priority matching
│   ├── EngineService.h         # Live engine thread + telemetry
│   ├── MarketRuntime.h         # Unified simulation/runtime layer
│   ├── MarketData.h            # Market-data DTOs and sink interfaces
│   ├── MarketDataPublisher.h   # JSON + binary WebSocket publisher
│   ├── OrderEntryGateway.h     # HTTP order entry handler
│   ├── BinaryProtocol.h        # Packed binary wire-format structs
│   ├── ServerApp.h             # Server entrypoint
│   └── ...
├── src/                        # Implementations
│   ├── MatchingEngine.cpp
│   ├── EngineService.cpp
│   ├── MarketRuntime.cpp
│   ├── OrderEntryGateway.cpp
│   ├── MarketDataPublisher.cpp
│   ├── ServerApp.cpp
│   └── main.cpp
├── tests/                      # Google Test suites (248 tests)
├── benchmarks/                 # Optional benchmark target
├── frontend/                   # React/Vite/TypeScript dashboard
├── data/                       # Sample CSV inputs
├── docs/                       # ARCHITECTURE.md, WORKFLOWS.md
└── AGENTS.md                   # Agent guidance

cmake -B build -G Ninja
cmake --build build

The backend pulls third-party dependencies with CMake FetchContent, including Abseil for the ladder and lookup containers.

Terminal 1 — backend:

.\build\mercury.exe --server --sim --host 127.0.0.1 --port 9001 --symbol SIM,AAPL,GOOG

Terminal 2 — frontend:

Set-Location frontend
npm install
npm run dev

Open http://127.0.0.1:5173. Vite proxies /api and /ws to the backend.

.\build\mercury.exe --server --sim --host 127.0.0.1 --port 9001 --symbol SIM --replay data\sample_orders_with_clients.csv --replay-speed 10

.\build\mercury.exe --sim --headless --sim-speed 25 --sim-seed 42 --sim-duration-ms 30000 --sim-volatility normal

Example order submission:

{
  "type": "limit",
  "side": "buy",
  "price": 101,
  "quantity": 10,
  "clientId": 1,
  "tif": "GTC"
}

Simulation control example:

{
  "action": "set_volatility",
  "volatility": "high"
}

Force a specific market regime (calm, normal, or stressed):

{
  "action": "set_regime",
  "volatility": "stressed"
}

{
  "type": "book_delta",
  "sequence": 42,
  "symbol": "SIM",
  "payload": {
    "side": "buy",
    "price": 100,
    "quantity": 5,
    "orderCount": 1
  }
}

sim_state frames expose:

• running and paused state
• clock mode and speed multiplier
• current volatility preset
• simulation timestamp
• market-maker, momentum, mean-reversion, and noise-trader agent counts
• realized volatility and average spread summaries
• toxicity score, measuring recent sweep-like flow versus displayed top-book liquidity
• current market regime (calm, normal, stressed) and the active Poisson arrival intensities (limitLambda, cancelLambda, marketableLambda), all expressed as expected events per millisecond

Messages on /ws/market/bin use packed structs from include/BinaryProtocol.h:

All fields are little-endian (x86/x64 host order).

.\build\mercury.exe data\sample_orders.csv trades.csv executions.csv riskevents.csv pnl.csv
.\build\mercury.exe data\sample_orders.csv --concurrent --async-io

Benchmarks run on 12-core CPU @ 3.6GHz (Release build):

cmake -B build -DMERCURY_BUILD_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build build
.\build\mercury_benchmarks.exe

248 unit tests covering:

• Order book operations (insert, remove, update)
• Matching engine (limit, market, IOC, FOK)
• Risk manager (position limits, exposure limits)
• P&L tracker (realized, unrealized, FIFO cost basis)
• Market data (sequencing, snapshots, deltas)
• Unified simulation runtime and agent fanout
• Bounded volatility excursion and long-run two-sided book maintenance
• Trading strategies and legacy migration coverage
• Concurrency (thread pool, async writers)
• Stress tests (100K+ orders, deep books)
• Core data structures and container behavior

# Backend
ctest --test-dir build --output-on-failure

# Frontend
Set-Location frontend
npm run test:run
npm run build

• Localhost only, no auth
• Single book in core engine, but multi-symbol supported via an EngineService registry
• JSON primary transport, binary secondary for throughput-sensitive consumers
• Browser writes over HTTP, market data over WebSocket
• Browser is a thin operator client; the market can stay active without manual orders
• Frontend is a separate Vite dev app, not served by C++
• Python strategy loading is deferred; v1 custom strategies are C++ only

AGPL-3.0