jack/exchange-monitor-go
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README to reflect current architecture and features

Browse Source 
- 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
This commit is contained in:
jackyu66git
2026-05-03 19:56:35 +08:00
parent c89a3b7333
commit 02fac78c59
1 changed files with 132 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+132 -62
View File
@@ -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