# Task: CoinEx Trader Bot — Full Dashboard Control Suite

**Priority:** HIGH  
**Assigned:** Glitch  
**Status:** Spec  
**Date:** 2026-03-01  

## Context

The live trader bot (`coinex_live_trader.py`) currently runs as a headless systemd timer with no UI control. D J wants ALL configuration and control moved into the CoinEx Dashboard (port 8891) before any more live trading happens.

## Requirements

### 1. Master Controls (Top Priority)
- **Global ON/OFF toggle** — starts/stops the trading bot entirely
- **Mode selector** — LIVE / DRY-RUN / PAUSED
- **Emergency Stop button** — immediately halts bot + attempts to close all positions
- **Lockfile status** — show if circuit breaker is tripped, with a "Clear Lockfile" button

### 2. Position Management
- **View all open positions** — symbol, side, entry price, current price, P&L, P&L%, margin, leverage
- **Close individual position** button
- **Close ALL positions** button
- **Position history** — recent closed trades with P&L

### 3. Runtime Configuration (all hot-reloadable, no restart needed)
- **Position size %** (currently 5%)
- **Max concurrent positions** (currently 3)
- **Max leverage** (currently 10x)
- **Kill switch drawdown %** (currently 50%)
- **TP threshold %** (take profit)
- **SL threshold %** (stop loss)
- **Circuit breaker failure count** (currently 3)
- **Scan interval** (currently 5 min)
- **Long signal threshold** (currently 45 pts)
- **Short signal threshold** (currently 50 pts)
- **Coin whitelist/blacklist** — toggle which coins can be traded

### 4. Account Overview
- **Total equity** (available + margin)
- **Available balance**
- **Margin in use**
- **Unrealized P&L total**
- **Starting balance** and **drawdown %**
- **Kill switch distance** (how far from trigger)

### 5. Activity Log
- **Trade log** — every open/close with timestamps, prices, P&L
- **Error log** — API failures, circuit breaker events
- **Signal log** — what signals were generated and whether acted on
- **Bot cycle log** — last N cycle summaries (scanned, signals found, actions taken)

### 6. Configuration Persistence
- All settings saved to `trader_config.json` 
- Bot reads config at start of each cycle (hot reload)
- Dashboard reads/writes same config file
- Default values match current hardcoded settings

## Architecture

### Backend
- New API routes in the dashboard:
  - `GET /api/trader/status` — bot state, positions, balance, config
  - `POST /api/trader/config` — update runtime config
  - `POST /api/trader/control` — start/stop/pause/emergency-stop/clear-lockfile
  - `POST /api/trader/close-position` — close specific position
  - `POST /api/trader/close-all` — close all positions
  - `GET /api/trader/logs` — recent trade/error/signal logs

### Config File: `trader_config.json`
```json
{
  "mode": "paused",
  "position_size_pct": 5.0,
  "max_positions": 3,
  "max_leverage": 10,
  "kill_switch_drawdown_pct": 50,
  "tp_pct": null,
  "sl_pct": null,
  "circuit_breaker_threshold": 3,
  "scan_interval_minutes": 5,
  "long_threshold": 45,
  "short_threshold": 50,
  "coin_blacklist": [],
  "coin_whitelist": []
}
```

### Frontend
- New `/trader` page in the dashboard (linked from main nav)
- Dark theme matching existing dashboard aesthetic
- Real-time updates via the existing WebSocket

### Trader Bot Changes
- Read `trader_config.json` at start of each cycle
- Respect `mode` field: "live" | "dry-run" | "paused"
- If "paused", exit immediately (no API calls)
- All hardcoded values replaced with config reads
- Bot NO LONGER managed by systemd timer — dashboard API controls start/stop

## Files
- Dashboard project: `~/.openclaw/workspace/projects/coinex-dashboard/`
- Trader script: `~/.openclaw/workspace/projects/crypto-signals/scripts/coinex_live_trader.py`
- Trader state: `~/.openclaw/workspace/projects/crypto-signals/data/coinex-live/trader_state.json`
- Lockfile: `~/.openclaw/workspace/projects/crypto-signals/data/coinex-live/live-trader-lock.json`
- New config: `~/.openclaw/workspace/projects/crypto-signals/data/coinex-live/trader_config.json`
- CoinEx creds: `~/.openclaw/workspace/.credentials/coinex.env`

## Constraints
- **Zero client-side CoinEx API calls** — all CoinEx calls go through server-side API routes
- **All existing scoring logic in `lib/indicators.ts` preserved exactly**
- **Use api.binance.us NOT api.binance.com** (451 geo-blocking)
- **Must include unit tests**
- **Context7 mandatory** for any library usage
- **Dark theme, monospace font aesthetic**
- Standard stack: Next.js 16 + Tailwind v4 + Framer Motion + ShadCN + Lucide + TypeScript

## Definition of Done
- [ ] All controls functional from dashboard UI
- [ ] Bot reads config from file each cycle (hot reload)
- [ ] Emergency stop works
- [ ] Position management works (view, close individual, close all)
- [ ] All settings persisted and reloadable
- [ ] Activity logs visible in UI
- [ ] Unit tests for API routes
- [ ] No live trading until D J explicitly flips the switch in the UI