jackyu66gitandClaude Opus 4.6
d38782490c
删除 HyperLiquid + 全部交易功能，构建自适应 surge 检测器。 - 新增 surge_detector.go: 每币独立滚动窗口基线，检测三所价差异常飙升 - 新增 SpreadCard/SurgeCard 前端组件 - 保留 momentum/trend/cumulative/trend_filter 扫描功能 - 更新文档和配置以反映新系统 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
122 lines
5.7 KiB
Markdown
122 lines
5.7 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
3-exchange spread surge detection system using Binance, OKX, and Bitget. Scans ~150 coins for inter-exchange price spread anomalies, detects surge events with per-coin adaptive baselines, and displays real-time data on a React dashboard.
|
||
|
||
## Build & Run Commands
|
||
|
||
```bash
|
||
# Build Go binary
|
||
go build -o exchange-monitor .
|
||
|
||
# Start (kills old process + builds if needed + runs)
|
||
bash start.sh
|
||
|
||
# Options: --clean (delete DB), --rebuild (force recompile)
|
||
bash start.sh --clean --rebuild
|
||
|
||
# Frontend dev (hot reload on :5173, proxies /api to :8888)
|
||
cd frontend && npm run dev
|
||
|
||
# Frontend production build
|
||
cd frontend && npm run build
|
||
```
|
||
|
||
## Architecture
|
||
|
||
### Data Flow
|
||
```
|
||
Exchange WS (Bitget + Binance + OKX) → PriceStore (in-memory)
|
||
↓
|
||
scanner (Scan3Ex)
|
||
↓
|
||
┌───────────────┼───────────────┐
|
||
↓ ↓ ↓
|
||
surge_detector momentum.go trend.go
|
||
cumulative.go trend_filter.go
|
||
↓ ↓ ↓
|
||
dashboard (SSE hub, :8888)
|
||
↓
|
||
React frontend (SSE events)
|
||
```
|
||
|
||
### Main Loop (main.go)
|
||
Fixed 50ms tick: reads snap from PriceStore → Scan3Ex() → surgeDetector.Tick() → momentum.Tick() etc. Every 30s: status log. Hourly: Telegram summary.
|
||
|
||
### Package Layout
|
||
|
||
| Package | Files | Responsibility |
|
||
|---------|-------|---------------|
|
||
| `main` (root) | `main.go`, `scanner.go`, `dashboard.go`, `config.go`, `types.go`, `surge_detector.go`, `momentum.go`, `trend.go`, `cumulative.go`, `trend_filter.go` | All core logic in a single flat package |
|
||
| `exchange/` | `connector.go`, `bitget.go`, `binance.go`, `okx.go`, `helpers.go` | WS reconnector + exchange-specific REST/WS APIs |
|
||
| `db/` | `db.go`, `surge_event_repo.go` | SQLite persistence (surge_events, cm_events, trend_events, trend_signals) |
|
||
| `frontend/` | Vite + React | Real-time dashboard consuming SSE from backend |
|
||
|
||
### Key Types
|
||
|
||
- **PriceStore** — Thread-safe in-memory map of coin→exchange→price, with bid/ask spread tracking
|
||
- **ThreeExSpread** — 3-exchange scan result: coin, prices, spread %, max/min exchange
|
||
- **SurgeDetector** — Per-coin adaptive baseline surge detection with rolling window median
|
||
- **SurgeEvent** — Detected surge: coin, prices, spread, baseline, direction, leading exchange
|
||
- **MomentumTracker** — Multi-window (1s/5s/15s/60s) price change tracking per exchange
|
||
- **TrendDetector** — Cross-exchange trend state machine (idle→alert→confirmed→exhausting)
|
||
- **CumulativeTracker** — 1m/5m/1h consensus change tracking across exchanges
|
||
- **TrendFilter** — K-line based quiet detection + EMA52 trend filtering
|
||
|
||
### Exchange Connector
|
||
|
||
`PriceConnector` (exchange/connector.go) is a reusable WebSocket reconnector with exponential backoff (1s-30s), configurable ping interval, and read deadline. Bitget uses text ping frames; Binance and OKX use standard ping/pong.
|
||
|
||
### Surge Detection Logic
|
||
|
||
- **Adaptive baseline**: Per-coin rolling window (600 samples, ~30s at 50ms tick) of 3-exchange max spreads
|
||
- **Threshold**: median(spreads) × multiplier (default 3.0), with min floor (0.05%)
|
||
- **Trigger**: currentSpread > threshold AND cooldown (60s) passed
|
||
- **Direction**: Compare highest exchange deviation from median vs lowest exchange deviation
|
||
- **Leading exchange**: The exchange furthest from median price (first to reflect price move)
|
||
|
||
### Configuration Priority
|
||
`.env` vars > `config.json` > code defaults. Config struct in `config.go`.
|
||
|
||
Key env vars: `BITGET_API_KEY`, `BITGET_API_SECRET`, `BITGET_PASSPHRASE`, `BINANCE_API_KEY`, `BINANCE_API_SECRET`, `HTTPS_PROXY`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`.
|
||
|
||
### Dashboard API
|
||
|
||
| Endpoint | Description |
|
||
|----------|-------------|
|
||
| `GET /` | Serves index.html (disk first, fallback embed) |
|
||
| `GET /api/status` | Current prices snapshot |
|
||
| `GET /events` | SSE stream (prices, spread_3ex, momentum, trend, cumulative, trend_filter, surge, status) |
|
||
| `GET /api/history?coin=&exchange=` | Price history ring buffer (500 pts) |
|
||
| `GET /api/spread-history?coin=` | 3-exchange spread history |
|
||
| `GET /api/surge-events?limit=` | Surge event history from DB or memory |
|
||
| `GET /api/cm-history` | Cumulative change event history |
|
||
| `GET /api/trend-signals` | Trend filter signal history |
|
||
| `GET /api/connections` | Exchange WS health (online/stale/offline) |
|
||
|
||
### SSE Events
|
||
|
||
| Event | Data | Frequency |
|
||
|-------|------|-----------|
|
||
| `prices` | All coin prices + 3-ex spread | Every tick |
|
||
| `spread_3ex` | Top 3-ex spreads scan results | Every tick |
|
||
| `momentum` | Multi-window price change % | Every tick |
|
||
| `trend` | Trend state machine snapshots | Every tick |
|
||
| `cumulative` | Cumulative consensus changes | Every tick |
|
||
| `trend_filter` | K-line filter states | Every tick |
|
||
| `trend_signal` | Individual trend signal (enter/exit) | On event |
|
||
| `surge` | Current spread/baseline snapshots | Every tick |
|
||
| `surge_event` | New surge detection event | On detection |
|
||
| `status` | Connection health + coin count | Every tick |
|
||
|
||
### Database
|
||
|
||
SQLite at `~/Project/exchange-monitor-go/data/trades.db` (single-writer mode). Tables: `surge_events`, `cm_events`, `trend_events`, `trend_signals`.
|
||
|
||
### Coin Tracking
|
||
|
||
~150 coins in `TrackedCoins` slice (scanner.go). Each entry has Name, BN (Binance symbol), BG (Bitget symbol), OKX (OKX symbol). Active WebSocket connections: Bitget + Binance + OKX.
|