exchange-monitor-go/CLAUDE.md

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

# 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.