metadata
title: EuNEx
emoji: 📈
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
EuNEx — Euronext Optiq Architecture Learning Project
C++ actor-based matching engine that mirrors the Euronext Optiq architecture, ported from the StockEx Python prototype.
Architecture Mapping
StockEx (Python/Kafka) EuNEx (C++/Simplx) Optiq (Production)
───────────────────── ────────────────── ──────────────────
fix_oeg_server.py → OEGActor → OEActor
Kafka 'orders' topic → Event::Pipe → Simplx Event::Pipe
matcher.py → MECoreActor → LogicalCoreActor + Book
match_order() → Book::newOrder() → RecoveryCause → IACA Cause → forwardToBook
handle_cancel() → Book::cancelOrder() → CancelOrderData
handle_amend() → Book::modifyOrder() → ModifyOrderData
Kafka 'trades' topic → TradeEvent via Pipe → IACA fragment chain
dashboard.py (SSE) → MDGActor → MDLimitLogicalCoreHandler
/orderbook/<sym> → BookUpdateEvent → PublishLimitUpdateRequest
/trades → TradeEvent → IACA → IA SBE message
database.py (SQLite) → RecoveryProxy (memory) → RecoveryProxy → Kafka
save_trade() → FragmentStore::append() → PersistenceAgent → Kafka produce
fix_oeg_server.py → FIXAcceptorActor → FIX 4.4 OEG Acceptor
NewOrderSingle → 35=D handling → Optiq FIX gateway
ExecutionReport → 35=8 response → Execution reports
ch_ai_trader.py → ClearingHouseActor → Clearing House (PTB path)
AI strategies → AITraderActor → Trading obligations
Actor Topology (v0.9)
Core 0: OEGActor + FIXAcceptorActor ← Order entry & FIX protocol
Core 1: MECoreActor (per symbol) ← Matching engine (Book)
Core 2: MDGActor ← Market data snapshots
Core 3: ClearingHouseActor + AITrader ← Post-trade & AI members
Dual Engine Architecture
The dashboard can run in two modes, switchable at runtime via a toggle in the UI:
┌───────────────────────────────────┐
│ Browser (:8090) │
│ [Python ○────● C++] toggle │
└──────────────┬────────────────────┘
│
┌──────────────▼────────────────────┐
│ Dashboard (Flask :8090) │
│ │
│ ┌────────────┐ ┌─────────────┐ │
│ │ Python ME │ │ C++ Bridge │ │
│ │MatchingEng │ │ FIX 4.4 TCP │ │
│ │(built-in) │ │ client │ │
│ └──────┬─────┘ └──────┬──────┘ │
│ mode=python mode=cpp │
└──────────────────────────┼────────┘
│ FIX 4.4 TCP
▼
┌──────────────────────────────────────┐
│ C++ Matching Engine │
│ eunex_me (:9001) │
│ │
│ OEG → MECore → MDG → ClearingHouse │
│ FIXAcceptorActor (TCP :9001) │
│ Multi-threaded actors │
└──────────────────────────────────────┘
| Mode | Engine | How orders are matched | Use case |
|---|---|---|---|
| Python | Built-in MatchingEngine |
In-process, same Flask app | Demo, learning, no compilation needed |
| C++ | eunex_me via FIX 4.4 |
TCP to C++ actors on port 9001 | Production-like, microsecond latency |
Service Architecture
┌─────────────────────────────────────────────────────────┐
│ nginx (:7860) │
│ Reverse proxy (Docker) │
└────────┬───────────────────┬───────────────────┬────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Dashboard │ │ Clearing House │ │ FIX Gateway │
│ (:8090) │ │ (:8091) │ │ (:9001 TCP) │
│ │ │ │ │ │
│ Order Book │ │ 10 AI Members │ │ FIX 4.4 Acceptor│
│ Trade Charts │ │ Leaderboard │ │ NewOrder/Cancel │
│ OHLCV History │ │ Portfolios │ │ Amend/ExecRpt │
│ SQLite DB │ │ Settlements │ │ │
│ SSE Streaming │ │ │ │ │
│ Engine Switch │ │ LLM Trading │ │ │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
└───────────────────┴────────────────────┘
│
▼
┌─────────────────────────────┐
│ C++ Matching Engine │
│ (eunex_me) │
│ Multi-threaded actors │
│ Price-time priority │
└─────────────────────────────┘
Quick Start (Linux)
# Install dependency
pip install flask
# Start all services (dashboard + FIX gateway + clearing house)
./run.sh
# Services:
# Dashboard: http://localhost:8090
# Clearing House: http://localhost:8091
# FIX Gateway: localhost:9001 (TCP)
# Stop all
./run.sh stop
# Check status
./run.sh status
Quick Start (Docker — Windows/Linux)
cd docker
docker compose up --build
# All services via nginx:
# Dashboard: http://localhost:7860
# Clearing House: http://localhost:7860/ch/
# Kafka: localhost:9092
Build C++ Engine
cmake -B build -DEUNEX_BUILD_TESTS=ON
cmake --build build --config Release
# Run matching engine (FIX server on port 9001)
./build/Release/eunex_me
# Run all tests (7 suites)
cd build && ctest -C Release
# Use with dashboard: start eunex_me, then toggle "C++" in the dashboard header
With Kafka Persistence
# Compile with Kafka support (requires librdkafka-dev)
cmake -B build -DEUNEX_USE_KAFKA=ON
cmake --build build --config Release
# Run with Kafka (set broker address)
EUNEX_KAFKA_BROKERS=localhost:9092 ./build/Release/eunex_me
# Topics: eunex.orders, eunex.trades, eunex.market-data, eunex.recovery.fragments
Without EUNEX_USE_KAFKA, the engine compiles with a no-op stub and runs standalone.
FIX Gateway
The C++ engine includes a built-in FIX 4.4 acceptor on TCP port 9001. A Python FIX gateway is also available:
python fix_gateway/fix_server.py
python fix_gateway/fix_server.py test
Supports: NewOrderSingle (35=D), OrderCancelRequest (35=F), OrderCancelReplaceRequest (35=G), ExecutionReport (35=8).
Configuration (.env)
All Python services auto-load settings from .env in the project root.
No extra packages needed — shared/config.py parses it at startup.
# .env — LLM and service configuration
LLM_PROVIDER=auto # ollama | groq | hf | auto (try all)
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.1
HF_MODEL=Qwen/Qwen2.5-7B-Instruct
# HF_TOKEN=hf_... # or auto-discovered from ~/.cache/huggingface/token
# GROQ_API_KEY=gsk_...
| Variable | Default | Description |
|---|---|---|
LLM_PROVIDER |
auto |
LLM backend: ollama, groq, hf, or auto (tries all in order) |
OLLAMA_HOST |
http://localhost:11434 |
Ollama server URL |
OLLAMA_MODEL |
llama3.1 |
Ollama model name |
HF_TOKEN |
(auto-discovered) | HuggingFace API token; reads ~/.cache/huggingface/token if not set |
HF_MODEL |
Qwen/Qwen2.5-7B-Instruct |
HuggingFace model (free tier) |
GROQ_API_KEY |
(empty) | Groq Cloud API key |
GROQ_MODEL |
llama-3.1-8b-instant |
Groq model name |
EUNEX_DASHBOARD_PORT |
8090 |
Dashboard HTTP port |
EUNEX_CH_PORT |
8091 |
Clearing House HTTP port |
EUNEX_FIX_PORT |
9001 |
FIX Gateway TCP port |
EUNEX_KAFKA_BROKERS |
localhost:9092 |
Kafka broker address |
AI Market Analyst
The Dashboard includes an AI-powered market analyst that generates real-time commentary on trading activity. It uses a fallback chain of LLM providers:
- Ollama (local) — best for development, requires Ollama installed
- Groq (cloud) — fast inference, requires
GROQ_API_KEY - HuggingFace (cloud) — free tier with
HF_TOKEN, uses Qwen 2.5 7B
The dashboard shows a green/red status dot and lets you select the active
Ollama model from a dropdown. Set LLM_PROVIDER=auto to try all providers
in order until one succeeds.
Clearing House
10 AI trading members (MBR01-MBR10) with 4 strategies:
- Momentum: follow price trends
- Mean Reversion: fade price moves
- Random: noise trading
- LLM: AI-driven decisions with natural language explanations (uses same provider chain)
Features: capital tracking, holdings per symbol, P&L, leaderboard, strategy selection per member, LLM trading explanations panel.
Project Structure
EuNEx/
├── src/ # C++ matching engine
│ ├── main.cpp # Entry point, actor wiring
│ ├── engine/SimplxShim.hpp # Multi-threaded actor engine
│ ├── common/
│ │ ├── Types.hpp # Price, Order, Trade, enums
│ │ └── Book.hpp/cpp # Price-time priority matching
│ ├── actors/
│ │ ├── Events.hpp # Inter-actor event types
│ │ ├── OEGActor.hpp/cpp # Order Entry Gateway
│ │ ├── MECoreActor.hpp/cpp # Matching Engine core (per symbol)
│ │ ├── MDGActor.hpp/cpp # Market Data Gateway
│ │ ├── FIXAcceptorActor.hpp/cpp # FIX 4.4 TCP acceptor
│ │ ├── ClearingHouseActor.hpp/cpp # Trade clearing & member positions
│ │ └── AITraderActor.hpp/cpp # Automated trading members
│ ├── net/SocketCompat.hpp # Cross-platform socket abstraction
│ ├── persistence/
│ │ ├── PersistenceStore.hpp # Abstract store + InMemoryStore
│ │ ├── KafkaBus.hpp # Multi-topic Kafka publisher (Optiq KFK)
│ │ └── KafkaStore.hpp # Kafka persistence (optional)
│ ├── recovery/RecoveryProxy.hpp/cpp # Recovery Cause/Effect
│ └── iaca/
│ ├── Fragment.hpp # IACA fragment definitions
│ └── IacaAggregator.hpp/cpp # Fragment chain aggregation
├── dashboard/
│ ├── app.py # Flask dashboard + matching engine
│ ├── database.py # SQLite (orders, trades, OHLCV)
│ └── templates/index.html # Trading UI with Chart.js
├── fix_gateway/
│ └── fix_server.py # Python FIX 4.4 TCP acceptor
├── clearing_house/
│ ├── app.py # Flask CH portal + API
│ ├── ch_database.py # SQLite (members, holdings)
│ ├── ch_ai_trader.py # AI trading strategies
│ └── templates/ # CH web UI
├── .env # LLM and service configuration
├── shared/config.py # Centralized configuration (auto-loads .env)
├── docker/
│ ├── docker-compose.yml # Kafka + EuNEx (all services)
│ ├── Dockerfile # Multi-stage Linux build
│ └── nginx.conf # Reverse proxy configuration
├── tests/
│ ├── test_orderbook.cpp # Book unit tests (26 cases)
│ ├── test_matching_engine.cpp # ME integration tests
│ ├── test_threaded_engine.cpp # Multi-threaded engine tests
│ ├── test_clearing_house.cpp # Clearing house tests (7 cases)
│ ├── test_fix_gateway.cpp # FIX gateway tests (5 cases)
│ └── test_ai_trader.cpp # AI trader tests (6 cases)
├── examples/
│ ├── ping_pong.cpp # Actor basics tutorial
│ └── simple_match.cpp # Matching with Recovery + IACA
└── docs/
├── developers-guide.md # Detailed developers guide
└── process-diagram.md # Architecture diagrams
Documentation
- Developers Guide — Detailed architecture, data flow, component reference
- Process Diagram — Optiq architecture diagrams and roadmap
Next Steps
Multi-threaded actor engine✓ SimplxShim with mailbox queuesKafka persistence✓ KafkaStore + Docker Compose (KRaft mode)FIX gateway✓ C++ FIXAcceptorActor + Python fallbackClearing House✓ ClearingHouseActor + AITraderActorMarket simulation✓ Realistic AI trading + Dashboard auto-simulationAI Analyst✓ Ollama/Groq/HuggingFace market commentaryMessage Flow Visualizer✓ Developer pipeline tracing toolEngine Mode Switch✓ Python ↔ C++ toggle with FIX 4.4 bridge- SBE encoding — replace event structs with SBE-encoded messages
- Master/Mirror failover — implement full Recovery replay on Mirror node
- Trading phases — pre-open, uncrossing, continuous, close, TAL
- Additional order types — Stop, Pegged, Mid-Point, Iceberg