Add README with architecture, config, and trading logic documentation

2026-05-03 16:56:44 +08:00
parent 719f0a061d
commit 128ed07aee
1 changed files with 103 additions and 0 deletions
@@ -0,0 +1,103 @@
+# Exchange Monitor Go
+
+Cross-exchange perpetual futures arbitrage scanner and automated trading system. Monitors real-time prices from 4 exchanges via WebSocket, identifies arbitrage opportunities, and executes maker-fee trades between Bitget and HyperLiquid.
+
+## Architecture
+
+```
+                       ┌──────────────┐
+        ┌──────────────┤   Binance    │◄──── bookTicker WS
+        │              └──────────────┘
+        │              ┌──────────────┐
+        │──────────────┤   Bitget     │◄──── ticker WS (trading exchange)
+        │              └──────────────┘
+PriceStore (sync.Map) ─┼──────────────┤
+        │              │ HyperLiquid  │◄──── webData2 WS (trading exchange)
+        │              └──────────────┘
+        │              ┌──────────────┐
+        └──────────────┤    dYdX      │◄──── v4_markets WS
+                       └──────────────┘
+                              │
+                    ┌─────────▼─────────┐
+                    │   Scanner (500ms)  │
+                    │  ScanArbWithFees() │
+                    └─────────┬─────────┘
+                              │
+              ┌───────────────▼────────────────┐
+              │  Trader: TryEntry / Tick / Exit │
+              │  Maker fees, scale-in, stop     │
+              └───────────────┬────────────────┘
+                              │
+                    ┌─────────▼─────────┐
+                    │   Notifier: TG     │
+                    └───────────────────┘
+```
+
+## Tracked Coins
+
+| Coin | Binance | Bitget | HyperLiquid | dYdX |
+|:----:|:-------:|:------:|:-----------:|:----:|
+| DOGE | DOGEUSDT | DOGEUSDT | DOGE | DOGE-USD |
+| LINK | LINKUSDT | LINKUSDT | LINK | LINK-USD |
+| ONDO | ONDOUSDT | ONDOUSDT | ONDO | ONDO-USD |
+| OP | OPUSDT | OPUSDT | OP | OP-USD |
+| WIF | WIFUSDT | WIFUSDT | WIF | WIF-USD |
+| ARB | ARBUSDT | ARBUSDT | ARB | ARB-USD |
+
+## Requirements
+
+- Go 1.21+
+- WebSocket connectivity to all 4 exchanges
+
+## Quick Start
+
+```bash
+# Build
+cd exchange-monitor-go
+go build -o exchange-monitor .
+
+# Configure (copy and edit)
+cp .env.example .env
+# Set TRADE_THRESHOLD, TRADE_AMOUNT_USD, API keys, etc.
+
+# Run (test mode, no real trades)
+./exchange-monitor
+
+# Run with Telegram notifications
+TELEGRAM_BOT_TOKEN=xxx TELEGRAM_CHAT_ID=xxx ./exchange-monitor
+```
+
+## Configuration (.env)
+
+| Variable | Default | Description |
+|:---------|:-------:|:------------|
+| TRADE_ENABLED | false | Enable real trading (1 to enable) |
+| TRADE_THRESHOLD | 0.1 | Min net profit % to enter (round trip after fees) |
+| TRADE_AMOUNT_USD | 5 | USD per leg |
+| TRADE_COOLDOWN_MS | 30000 | Cooldown between same-coin trades |
+| TEST_MODE | true | Simulate orders (no real API calls) |
+| MOCK_SLIPPAGE_PCT | 0.005 | Simulated slippage per leg (%) |
+
+## Fee Model
+
+Maker fees (limit orders), no rebate:
+
+| Exchange | Maker | Taker |
+|:---------|:-----:|:-----:|
+| Bitget | 0.020% | 0.040% |
+| HyperLiquid | 0.015% | 0.035% |
+| Binance | 0.020% | 0.040% |
+
+Round trip (2 legs entry + 2 legs exit): **0.07%**
+
+## Trading Logic
+
+1. **Scanner** runs every 500ms, checks all 10 exchange pairs
+2. **Entry** when net profit ≥ TRADE_THRESHOLD (after full round-trip fees)
+3. **Scale-in** adds $5 per leg when spread widens another 0.10%
+4. **Exit** when spread converges to ≤0.02%, or 30 min timeout
+5. **Only BG ↔ HL** — other exchanges are price references only
+
+## Disclaimer
+
+This software is for educational/research purposes. Use at your own risk. Cryptocurrency trading involves substantial risk of loss.