110 lines
4.1 KiB
Markdown
110 lines
4.1 KiB
Markdown
# Triangular Arbitrage Bot
|
|
|
|
Real-time triangular arbitrage detection and execution for centralized crypto exchanges. Currently supports **KuCoin**.
|
|
|
|
## Architecture
|
|
|
|
Two-process design communicating via Unix domain sockets:
|
|
|
|
| Process | Role |
|
|
|---|---|
|
|
| `fused_engine` | C binary combining Feed Handler, Order Book, and Opportunity Engine. KuCoin WebSocket subscriber, order book mirror, triangle enumeration, live opportunity evaluation. Emits signals to executor. |
|
|
| `executor` | Consumes signals from `fused_engine`, places 3-leg KuCoin REST orders. Fire-and-forget: no re-evaluation, no queue, drop if busy. |
|
|
|
|
```
|
|
[KuCoin WS] ──▶ [fused_engine] ──────────────────── Unix socket ──▶ [executor]
|
|
│
|
|
Triangle Evaluator
|
|
```
|
|
|
|
`fused_engine` evaluates triangles on live book updates and emits signals to the executor. The executor does **not** re-evaluate books — it trusts the signal as valid at emission time and places orders directly via KuCoin REST API.
|
|
|
|
## Status
|
|
|
|
| Component | Status |
|
|
|---|---|
|
|
| `fused_engine` | Complete — WebSocket subscription, order book mirror, triangle enumeration, top-level profitability evaluation with chained `max_volume`, signal dispatch via Unix socket |
|
|
| `executor` | Complete — Signal consumption via Unix socket, paper-mode order validation via `/api/v1/hf/orders/test`, deterministic fill simulation, REST control API |
|
|
|
|
## Prerequisites
|
|
|
|
- C compiler (gcc/clang), CMake 3.22+, OpenSSL, libyaml, pthread
|
|
- Python 3.11+ (for executor only)
|
|
|
|
## Building fused_engine
|
|
|
|
```bash
|
|
mkdir -p build && cd build
|
|
cmake ../src -DCMAKE_BUILD_TYPE=Release
|
|
make -j$(nproc)
|
|
```
|
|
|
|
Binary at `build/fused_engine`.
|
|
|
|
## Configuration
|
|
|
|
Edit `config.yaml`:
|
|
|
|
- `hold_currencies` — currencies held as capital. Only triangles starting and ending in one of these are evaluated (default: `["USDT", "USDC", "USD1"]`)
|
|
- `excluded_currencies` — currencies to exclude from triangle enumeration
|
|
- `signal_threshold_bps` — minimum net profit in basis points to fire a signal (default: `0.2`)
|
|
- `cooldown_ms` — minimum milliseconds between opportunity notifications for the same triangle (default: `1000`)
|
|
- `api.key` / `api.secret` / `api.passphrase` — KuCoin API credentials
|
|
|
|
## Running
|
|
|
|
**Startup order:** `executor` → `fused_engine`
|
|
|
|
### 1. Start the executor
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
python3 -m executor
|
|
```
|
|
|
|
Creates the Unix socket at `/tmp/executor.sock` and listens for signals.
|
|
|
|
### 2. Start fused_engine
|
|
|
|
```bash
|
|
./build/fused_engine
|
|
```
|
|
|
|
Fetches all KuCoin pairs, enumerates triangles, subscribes to WebSocket order books, evaluates triangles on every book update, and dispatches signals to the executor via Unix socket.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
tri_arb/
|
|
├── src/ # C source for fused_engine
|
|
│ ├── main.c # Entry point
|
|
│ ├── ws_client.c/h # KuCoin WebSocket client (TLS, masked frames)
|
|
│ ├── book.c/h # Order book store
|
|
│ ├── symbols_api.c/h # Symbol discovery, triangle enumeration
|
|
│ ├── triangle.c/h # Triangle set management
|
|
│ ├── evaluate.c/h # Triangle evaluation & signal construction
|
|
│ ├── events.c/h # Event loop, Unix socket client to executor
|
|
│ ├── queue.c/h # SPSC lock-free queue (hot → cold thread)
|
|
│ ├── config.c/h # YAML config parser
|
|
│ ├── http_client.c/h # KuCoin REST API client (HMAC signing)
|
|
│ ├── hash.c/h # Hash table
|
|
│ ├── cJSON.c/h # JSON parser
|
|
│ ├── jsmn.h # Minimal JSON tokenizer (header-only, unused)
|
|
│ └── CMakeLists.txt
|
|
├── executor/ # Triangular Arbitrage Executor (Python)
|
|
│ ├── __main__.py
|
|
│ ├── executor.py
|
|
│ ├── kucoin_api.py
|
|
│ ├── rest_api.py
|
|
│ ├── socket_server.py
|
|
│ └── config.py
|
|
├── common/ # Shared Python utilities
|
|
│ ├── config.py
|
|
│ └── log.py
|
|
├── build/ # Build output (not committed)
|
|
├── scripts/
|
|
│ └── install.sh
|
|
├── config.yaml
|
|
└── config.yaml.example
|
|
```
|