# β‘ GoQuant Arbitrage Engine
> Real-time cross-exchange arbitrage engine for spot & derivatives trading
## π Table of Contents
- [βοΈ Features & Status](#οΈ-features--status)
- [𧱠Project Structure](#-project-structure)
- [π§ͺ Module-by-Module Overview](#-module-by-module-status-overview)
- [π Recent Achievements & Changes](#-recent-achievements--changes)
- [π Build & Run](#-build--run)
- [π§Ύ Expected Output](#-expected-output)
- [π§ Architecture Overview](#-architecture-overview)
- [π₯ Demo](#-demo)
- [π€ Contributing](#-contributing)
- [π£ Roadmap](#-roadmap)
- [π License](#-license)
---
## βοΈ Features & Status
| Feature | Status | Description |
| ----------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| β
**BinanceConnector** | Complete | - Fully integrated with Binance WebSocket:
- Spot L2
- Perp L2
- Mark Price
- Funding Rate
- Robust, multi-threaded, handles all JSON edge cases
- Logs and updates best bid/ask, mark price, and funding rate in real time |
| β
**OKXConnector** | Complete | - Fully integrated with OKX WebSocket:
- Books
- Mark Price
- Funding Rate
- Robust symbol normalization and API compliance
- Real-time orderbook, mark price, and funding rate updates |
| π§ **BybitConnector** | Incomplete | - Scaffold present
- Live integration not yet implemented |
| β
**MarketDataManager** | Complete | - Thread-safe storage and retrieval of best bid/ask, mark price, and funding rate
- Consistent symbol normalization across all exchanges
- Shared data manager used by all connectors |
| β
**SyntheticCalculator** | Working | - Synthetic spot calculation from OKX perpetual mark price and funding rate
- Real-time computation using funding rate and next funding time
- Compares Binance spot mid-price vs. OKX synthetic spot |
| β
**MispricingDetector** | Working | - Cross-exchange arbitrage detection between Binance and OKX
- Real-time detection of price differences exceeding threshold (configurable)
- Logs arbitrage opportunities with source/destination and amounts |
| β
**ArbitrageEngine** | Working | - Detects and logs real arbitrage opportunities
- Integrated with TradeExecutor for simulated (dry-run) and live trading |
| β οΈ **RiskManager** | Dummy | - Dummy logic for position sizing, funding cost, exposure
- Needs advanced models |
| β
**PerformanceMonitor** | Complete | - Logs latency, throughput, memory, and CPU usage |
| β
**Unit Testing** | Complete | - Google Test suite covers all major modules
- All tests passing (including thread safety) |
| β
**Shutdown Handling** | Complete | - Signal handling and clean exit supported |
| β
**Config Handling** | Complete | - JSON config file and CLI argument parsing
- Thread-safe, globally accessible ConfigManager
- All modules use config values (no hardcoded parameters) |
| β
**Multi-Symbol Support** | Complete | - Cross-exchange arbitrage between multiple symbols
- Real-time data feeds from both exchanges
- Easy extension to additional symbols and exchanges |
| β
**Multi-Exchange Support** | Working | - Binance + OKX fully integrated and working |
| π‘ **Documentation** | Partial | - Needs more detail, diagrams, architecture docs |
---
## 𧱠Project Structure
| Folder / File | Description |
| ------------------ | --------------------------------------------------------- |
| `src/`, `include/` | All core engine, exchange, and utility code |
| `third_party/` | External dependencies (Asio, nlohmann/json, spdlog, etc.) |
| `tests/` | Google Test suite for core modules |
| `CMakeLists.txt` | Modern CMake setup (Boost, OpenSSL, spdlog integration) |
| `README.md` | Project overview, setup instructions, and roadmap |
---
## π§ͺ Module-by-Module Status Overview
| Module | Status | Notes |
| -------------------------- | ------------- | ------------------------------------------------------------ |
| **BinanceConnector** | β
Complete | Live L2, mark price, funding feeds; production-grade |
| **OKXConnector** | β
Complete | Live books, mark-price, funding-rate feeds; production-grade |
| **BybitConnector** | π§ Incomplete | Only scaffold; no live integration yet |
| **MarketDataManager** | β
Complete | Thread-safe, shared data manager with symbol normalization |
| **SyntheticCalculator** | β
Working | Real synthetic spot calculation from OKX perp data |
| **MispricingDetector** | β
Working | Real cross-exchange arbitrage detection (Binance vs OKX) |
| **ArbitrageEngine** | β
Working | Detects and logs real arbitrage opportunities |
| **TradeExecutor** | β
Working | Simulated (dry-run) and live trade execution, REST API, risk |
| **RiskManager** | β οΈ Dummy | Requires real models (exposure, funding cost, VaR) |
| **PerformanceMonitor** | β
Complete | Logs latency, memory, CPU, throughput |
| **Config Handling** | β
Complete | JSON config file and CLI parsing, thread-safe, global access |
| **Unit Testing** | β
Complete | Covers all major modules, including config/thread safety |
| **Shutdown Handling** | β
Complete | Signal-safe shutdown |
| **Multi-Symbol Support** | β
Complete | BTCUSDT/ETHUSDT/SOLUSDT working; easy extension |
| **Multi-Exchange Support** | β
Working | Binance + OKX fully integrated and working |
| **Documentation** | π‘ Partial | Needs more detail, diagrams, architecture docs |
---
## π Recent Achievements & Changes
### β
Config Refactor & Thread Safety
- Replaced hardcoded config with a robust, thread-safe, globally accessible `ConfigManager`.
- Added support for loading config from `config.json` and overriding via CLI arguments.
- All modules now use config values (API keys, symbols, thresholds, etc.) from the config manager.
- Fixed a critical deadlock bug in config access by switching to `std::recursive_mutex`.
- Unit tests for config and thread safety now pass.
### β
Trade Execution Pipeline
- Integrated `TradeExecutor` with REST API connectors for Binance and OKX.
- Supports both dry-run (simulated) and live trading modes.
- Risk checks and logging for all trade attempts.
### β
Production-Grade Reliability
- No more infinite loops or deadlocks at startup or in tests.
- Robust error handling, reconnection, and data validation.
- Clean shutdown on interrupt.
---
## π Build & Run
**Requirements:**
- CMake 3.20+
- C++20-compatible compiler
- Dependencies: Boost, OpenSSL, nlohmann/json, spdlog
(Install via Homebrew or vcpkg)
- Standalone Asio (vendored in `third_party/asio`)
**Build Steps:**
```sh
mkdir -p build
cd build
cmake ..
make -j
```
**Run:**
```sh
./goquant [--config config.json] [--dry-run] [other CLI options]
```
- Loads configuration from `config.json` (or file specified via `--config`).
- All engine parameters (API keys, symbols, thresholds, etc.) are now configurable.
- Connects to Binance and OKX, logs best bid/ask and mark price for all enabled symbols in real time.
- Detects and logs arbitrage opportunities between Binance spot and OKX synthetic spot.
- Press CTRL+C to exit cleanly.
---
## π§Ύ Expected Output
```
[info] [main] GoQuant process started
[info] [ConfigManager] Current configuration:
{ ... full config ... }
[info] Connected to OKX SWAP mark-price for BTC-USDT-SWAP
[info] Connected to OKX SWAP funding-rate for BTC-USDT-SWAP
[info] OKX mark price update [btcusdtswap]: 108085.2
[info] OKX funding rate update [btcusdtswap]: 7.273546296e-06
[info] [DEBUG] markPrice: 108087.7, fundingRate: 7.273546296e-06
[info] [DEBUG] Computed Synthetic Spot: 108087.3216504467
[info] [Arb] Binance spot mid: 108101.535 vs. Synthetic spot: 108087.3216504467 | delta: 0.0131%
```
---
## π§ Architecture Overview
```mermaid
graph TD
A["Binance WS"] -->|"bid/ask"| B("MarketDataManager")
C["OKX WS"] -->|"funding/mark"| B
B --> D["SyntheticCalculator"]
D --> E["MispricingDetector"]
E --> F["ArbitrageEngine"]
```
---
## π€ Contributing
We welcome contributions! Hereβs how you can help:
- Fork the repo
- Create a feature branch
- Submit a pull request
See `CONTRIBUTING.md` for more details.
---
## π£ Roadmap
- [x] Binance spot integration
- [x] OKX synthetic spot pricing
- [ ] Bybit integration
- [ ] Telegram/Slack notification on arbitrage
- [ ] Advanced risk management
---
## π License
MIT