# Triangular Arbitrage Bot

Real-time triangular arbitrage detection and execution for KuCoin Spot.
Single C binary. WebSocket book feeds, triangle evaluation, and order placement in one process.

## Architecture

Monolithic single-process design using N+1 pthreads:

| Thread | Role |
|---|---|
| **Hot thread** | WebSocket I/O via epoll, order book maintenance, book update dispatch to evaluator |
| **Evaluator** (embedded in hot thread) | Triangle profitability evaluation on every book update, delivers to first free executor slot |
| **Executor thread(s)** | Spin on per-thread slot via atomic state machine; pick up signal, place 3-leg HF market orders via KuCoin REST API, wait for fills via WebSocket, optional balance-wait between legs |

```
[KuCoin WS] ──▶ Hot Thread ──▶ Evaluator ──▶ Slot[0..N] ──▶ Executor Thread(s)
                     │                       (CAS state machine)   │
               Order Book                                        KuCoin REST
```

Each executor thread owns one slot. The evaluator writes the signal directly into the slot via a CAS state machine (FREE → CLAIMED → READY). The executor picks it up on the next spin iteration (nanoseconds). If all slots are busy or no free slot available, the signal is dropped.

The evaluator runs **in-process** on every book update (no cooldown).
The executor does **not** re-evaluate, it trusts the signal as valid at emission time.

## Prerequisites

- C compiler (gcc/clang), CMake 3.22+, OpenSSL, libyaml, pthreads

## Building

```bash
mkdir -p build && cd build
cmake ../src -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
```

Binary at `build/fused_engine`.

## Configuration

Edit `config.yaml` (see `config.yaml.example`):

| Key | Description |
|---|---|
| `live_mode` | `false` = paper trades (test endpoint), `true` = real orders |
| `signal_threshold_bps` | Minimum predicted bps to fire a signal (default: 2) |
| `hold_currencies` | Currencies held as capital; triangles must start/end in one of these |
| `excluded_currencies` | Currencies to exclude from triangle enumeration |
| `kcs_discount_active` | Whether KCS fee discount applies |
| `balance_wait_enabled` | Wait for WS balance settlement between live legs (default: false) |
| `concurrent_slots` | Number of executor threads (default: 1, max 16) |
| `initial_capital` | Map of currency to max quote per signal |
| `kucoin_api_key/secret/passphrase` | KuCoin API credentials |

## Running

```bash
./build/fused_engine
```

Fetches fee table and symbol list, connects to KuCoin WebSocket, subscribes to order books, enumerates triangles, evaluates on every book update, and executes signals via REST.

## Project Structure

```
tri_arb/
├── src/                     # C source
│   ├── main.c              # Entry point, thread spawn
│   ├── ws_client.c/h       # KuCoin WebSocket client (TLS, epoll, book/balance/order frames)
│   ├── book.c/h            # Order book store (top-5 bid/ask)
│   ├── symbols_api.c/h     # Symbol discovery, triangle enumeration
│   ├── triangle.c/h        # Triangle set, leg, signal types
│   ├── evaluate.c/h        # Triangle evaluation and signal dispatch
│   ├── executor.c/h        # Signal execution, REST order placement, fill+balance wait
│   ├── events.c/h          # Event loops (hot thread + executor thread(s))
│   ├── fill_handler.c/h    # Cross-thread fill event channel (SPSC ring + eventfd)
│   ├── rest_client.c/h     # KuCoin REST API client (signed requests, keepalive)
│   ├── http_client.c/h     # One-shot HTTPS requests (token fetch, fee table)
│   ├── slot.c/h            # Per-executor signal slot with atomic CAS delivery
│   ├── config.c/h          # YAML config parser
│   ├── hash.c/h            # Hash table
│   ├── cJSON.c/h           # JSON parser
│   ├── log.c/h             # Logging
│   └── CMakeLists.txt
├── build/                   # Build output
├── config.yaml              # Runtime config (gitignored)
├── config.yaml.example      # Config template
└── scripts/                 # Deployment scripts
```


## Disclaimer

This software is designed for low-latency environments. It is only useful when
colocated with the exchange's servers.

## Contact

Nicolás Sánchez — nicolassanchez@tutanota.com