triangular_arbitrage_bot/README.md

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

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

source .venv/bin/activate
python3 -m executor

Creates the Unix socket at /tmp/executor.sock and listens for signals.

2. Start fused_engine

./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