From 02fac78c592971d55fbe997c9d1da3811c88d096 Mon Sep 17 00:00:00 2001 From: jackyu66git Date: Sun, 3 May 2026 19:56:35 +0800 Subject: [PATCH] Update README to reflect current architecture and features - Fix architecture diagram (ScanBGHL, correct data flow) - Add configuration table with all env vars - Document exit logic (convergence, reversal, timeout) - Add Web Dashboard, Notifications, DB, Signals sections - Add project file tree --- README.md | 194 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 132 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 0731b27..77712c9 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,172 @@ # 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. +Cross-exchange perpetual futures arbitrage scanner and automated trading system. Monitors real-time prices from 4 exchanges via **WebSocket**, identifies **Bitget ↔ HyperLiquid** arbitrage opportunities, executes maker-fee trades, and provides a real-time Web dashboard. ## 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 │ - └───────────────────┘ + ┌──────────────┐ + ┌──────────────┤ Binance │◄──── bookTicker WS (price reference) + │ └──────────────┘ + │ ┌──────────────┐ + │──────────────┤ Bitget │◄──── ticker WS (trading exchange) + │ └──────────────┘ +PriceStore ─────────┼──────────────┤ + │ │ HyperLiquid │◄──── webData2 WS (trading exchange) + │ └──────────────┘ + │ ┌──────────────┐ + └──────────────┤ dYdX │◄──── v4_markets WS (price reference) + └──────────────┘ + │ + ┌─────────▼─────────┐ + │ ScanBGHL (500ms) │ + │ BG ↔ HL only │ + └─────────┬─────────┘ + │ + ┌───────────────▼────────────────┐ + │ Trader: TryEntry / Tick / Exit │ + │ Maker fees, scale-in, stop │ + └───────────────┬────────────────┘ + │ + ┌─────────▼─────────┐ + │ Notifier: TG │ + │ Dashboard: :8888 │ + └───────────────────┘ ``` ## 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 | +| Coin | Binance | Bitget | HyperLiquid | dYdX | +|:----:|:--------:|:---------:|:-----------:|:--------:| +| DOGE | DOGEUSDT | DOGEUSDT | DOGE | DOGE | +| LINK | LINKUSDT | LINKUSDT | LINK | LINK | +| ONDO | ONDOUSDT | ONDOUSDT | ONDO | ONDO | +| OP | OPUSDT | OPUSDT | OP | OP | +| WIF | WIFUSDT | WIFUSDT | WIF | WIF | +| ARB | ARBUSDT | ARBUSDT | ARB | ARB | + +- **Bitget / HyperLiquid** — trading exchanges (limit orders with maker fees) +- **Binance / dYdX** — price reference only ## Requirements -- Go 1.21+ +- Go 1.25+ - 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) +cp .env.example .env # edit to configure ./exchange-monitor - -# Run with Telegram notifications -TELEGRAM_BOT_TOKEN=xxx TELEGRAM_CHAT_ID=xxx ./exchange-monitor ``` +Then open [http://localhost:8888](http://localhost:8888) for the Web dashboard. + ## 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 (%) | +| Variable | Code Default | Description | +|:---------|:------------:|:------------| +| `TELEGRAM_BOT_TOKEN` | — | Telegram bot token for notifications | +| `TELEGRAM_CHAT_ID` | — | Target chat ID for notifications | +| `TRADE_ENABLED` | `false` | Enable real trading (`1` to enable) | +| `TRADE_THRESHOLD` | `0.15` | Min net profit % to enter (after fees) | +| `TRADE_AMOUNT_USD` | `10` | USD per leg | +| `TRADE_COOLDOWN_MS` | `30000` | Cooldown between same-coin trades (ms) | +| `TEST_MODE` | `false` | Simulate orders (no real API calls) | +| `MOCK_SLIPPAGE_PCT` | `0.005` | Simulated slippage per leg (%) | +| `BITGET_API_KEY` / `BITGET_API_SECRET` / `BITGET_PASSPHRASE` | — | Bitget API credentials (test mode skips) | +| `HL_PRIVATE_KEY` / `HL_ADDRESS` | — | HyperLiquid wallet credentials (test mode skips) | ## Fee Model -Maker fees (limit orders), no rebate: +All trades use **maker** (limit orders), no rebate. Only Bitget and HyperLiquid are used for trading: | 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%** +Round trip (2 legs entry + 2 legs exit): **0.07%** total fees. ## 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 +1. **Scanner** runs every 500ms, checks all 6 coins for BG ↔ HL spread +2. **Entry** when net profit ≥ `TRADE_THRESHOLD` (after full round-trip fees) +3. **Scale-in** adds another leg-worth when spread widens another 0.10% +4. **Exit** conditions (whichever hits first): + - Spread converges to ≤ 0.02% → **价差收敛，止盈平仓** + - Spread reverses below -0.02% → **价差反转，止盈平仓** + - Position held over 30 minutes → **超时平仓** +5. **Direction**: BG → HL (buy BG, sell HL) or HL → BG (buy HL, sell BG) + +## Notifications + +All notifications sent to Telegram (via `TELEGRAM_BOT_TOKEN`): + +- **开仓** — entry notification with prices, direction, spread, amount +- **平仓** — exit notification with PnL breakdown, fees, convergence analysis +- **每小时** — summary of open positions (duration, amount) +- Uses HTML parse mode for bold formatting + +## Web Dashboard + +Built-in HTTP server at `:8888` with real-time SSE push (1-second refresh): + +- **Price table** — live prices from all exchanges with bid-ask spread +- **BG↔HL spread** — per-coin arbitrage spread with chart +- **Open positions** — live PnL estimate, scaling level, duration +- **Arb scan results** — current arbitrage opportunities +- **Trade history** — past trades with detail view +- **Connection status** — exchange health (online / stale / offline) +- Charts rendered via Chart.js (loaded from CDN) + +## DB & Persistence + +- SQLite at `data/trades.db` +- Tracks open positions across restarts +- Stores all closed trades with full PnL details +- Historical stats merged with in-memory session stats on startup + +## Signals + +| Signal | Action | +|:-------|:-------| +| `Ctrl+C` / `SIGINT` | Graceful shutdown (closes all WS connections) | +| `SIGUSR1` | Dump convergence statistics to `trade_stats.txt` | + +## Project Structure + +``` +exchange-monitor-go/ +├── main.go # Entry point, WS startup, main loop +├── config.go # .env configuration loader +├── types.go # PriceStore, TrackedCoin, ArbOpportunity +├── scanner.go # ScanBGHL — arbitrage scanner +├── trader.go # Position management, entry/exit/scale-in +├── dashboard.go # Web server + SSE + history buffers +├── toaster.go # Telegram notifications +├── static.go # Embedded web static files +├── .env # Local configuration +├── exchange/ +│ ├── connector.go # Generic WS connector with reconnect +│ ├── binance.go # Binance bookTicker WS +│ ├── hyperliquid.go # HyperLiquid webData2 WS +│ ├── hyperliquid_trade.go # HL REST trade API +│ ├── bitget.go # Bitget ticker WS +│ ├── bitget_trade.go # Bitget REST trade API +│ ├── dydx.go # dYdX v4_markets WS +│ ├── helpers.go # Package helpers +│ └── ping.go # Accessibility check tools +├── db/ +│ ├── db.go # SQLite open/migrate +│ └── trade_repo.go # Trade record queries +└── web/static/ + ├── index.html # Dashboard HTML + ├── app.js # SSE client + UI logic + └── style.css # Dashboard CSS +``` ## Disclaimer