btc-trading/AGENTS.md

AGENTS.md - AI Coding Assistant Guidelines

Project Overview

BTC Accumulation Bot - Data Collection & Backtesting Phase. High-performance system for cbBTC on Hyperliquid with TimescaleDB. Core components: Data Collector (WS), Indicator Engine (SMA, etc.), Brain (Decision Logic), and Backtester.

Build/Run Commands

Docker (Primary deployment - Synology DS218+)

cd docker && docker-compose up -d --build   # Build and start all services
docker-compose logs -f data_collector       # View logs
bash scripts/deploy.sh                      # Full deploy

Development

cd src/api && uvicorn server:app --reload --host 0.0.0.0 --port 8000
# Docs: http://localhost:8000/docs | Dashboard: http://localhost:8000/dashboard
cd src/data_collector && python -m data_collector.main

Testing

pytest                                                                       # All tests
pytest tests/data_collector/test_websocket_client.py                         # Single file
pytest --cov=src --cov-report=html                                           # With coverage

Project Structure

src/
├── data_collector/              # WebSocket client, buffer, database
│   ├── __init__.py              # Package exports (all public classes)
│   ├── main.py                  # Entry point, orchestration
│   ├── websocket_client.py      # Hyperliquid WS client
│   ├── candle_buffer.py         # Circular buffer with async flush
│   ├── database.py              # asyncpg/TimescaleDB interface
│   ├── backfill.py              # Historical data backfill
│   ├── custom_timeframe_generator.py  # 37m, 148m, 1d aggregation
│   ├── indicator_engine.py      # SMA/EMA computation & storage
│   ├── brain.py                 # Strategy evaluation & decision logging
│   └── backtester.py            # Historical replay driver (server-side)
├── api/
│   ├── server.py                # FastAPI app, endpoints for data/backtests
│   └── dashboard/static/index.html  # Real-time web dashboard with client-side simulation
└── strategies/
    ├── base.py                  # Base strategy interface
    └── ma_strategy.py           # Configurable MA strategy (period: 5-500)
config/data_config.yaml          # Operational config & indicator settings
docker/                          # Docker orchestration & init-scripts
scripts/                         # Deploy, backup, & utility scripts

Architecture & Data Flow

Live Trading (Server-Side)

Live: WS -> Buffer -> DB -> CustomTF -> IndicatorEngine -> Brain -> Decisions
                                              │             │
Backtest: DB (History) -> Backtester ─────────┴─────────────┘

Client-Side Simulation (Dashboard)

User Input -> API /candles/bulk -> Browser (ClientStrategyEngine) -> Chart Visualization
                    ↓                                              ↓
            Historical Data                                Buy/Sell Markers

• Stateless Logic: IndicatorEngine and Brain are driver-agnostic. They read from DB and write to DB, unaware if the trigger is live WS or backtest replay.
• Consistency: Indicators are computed exactly the same way for live and backtest.
• Visualization: Dashboard queries indicators and decisions tables directly. Decisions contain a JSON snapshot of indicators at the moment of decision.
• Client-Side Simulation: All strategy simulations run in the browser using ClientStrategyEngine. The server only provides historical candle data via API. This minimizes server load and allows interactive backtesting with configurable parameters (MA period 5-500).
• Full Historical Display: After simulation, the chart displays the complete date range used, not just the default 1000 recent candles.

Key Dataclasses

@dataclass
class Candle:                    # Standard OHLCV
    time: datetime; symbol: str; interval: str; ...

@dataclass
class Decision:                  # Brain output
    time: datetime; symbol: str; decision_type: str; confidence: float
    indicator_snapshot: Dict;    # Values seen by Brain at decision time
    backtest_id: Optional[str]   # UUID if backtest, None if live

Database Schema (TimescaleDB)

Table	Purpose	Key Columns
candles	OHLCV data	(time, symbol, interval) UNIQUE
indicators	Computed values	(time, symbol, interval, indicator_name) UNIQUE
decisions	Buy/sell signals	(time, symbol, interval, backtest_id)
backtest_runs	Run metadata	(id, strategy, config, results)

• decisions table stores indicator_snapshot JSONB for exact replay/audit.
• Compression enabled on all hypertables (7-day policy).

API Endpoints (src/api/server.py)

Method	Path	Description
GET	/api/v1/candles	Query raw candles
GET	/api/v1/indicators	Query computed indicators (MA, RSI, etc.)
GET	/api/v1/decisions	Query signals (live or backtest)
GET	/api/v1/backtests	List historical backtest runs
POST	/api/v1/backtests	Trigger a new backtest (async background task)
GET	/api/v1/stats	24h trading stats

Code Style Guidelines

• Imports: Stdlib, then Third-party, then Local (relative within package).
• Async: Use async/await for all I/O. Use asyncpg pool.
• Typing: strict type hints required. Optional[T], List[T].
• Logging: Use logger = logging.getLogger(__name__).
• Config: Load from config/data_config.yaml or env vars.

Strategy Configuration

The system uses a single configurable Moving Average strategy (ma_strategy) with a dynamic period (5-500).

Strategy Files

• src/strategies/base.py - Base strategy interface with SignalType enum
• src/strategies/ma_strategy.py - Configurable MA strategy implementation

Client-Side vs Server-Side

Feature	Client-Side (Dashboard)	Server-Side (CLI/API)
Purpose	Interactive simulation	Production backtesting
Strategy	Single configurable MA (period 5-500)	Configurable via strategy registry
Indicators	Calculated in browser (SMA, RSI, etc.)	Pre-computed in database
Data Flow	API → Browser → Chart	DB → Backtester → DB
Performance	Fast, interactive	Thorough, historical

Simulation Workflow

1. User selects date range and MA period (5-500) in dashboard sidebar
2. Browser fetches full historical data from /api/v1/candles/bulk
3. ClientStrategyEngine calculates indicators client-side using JavaScript
4. Simulation runs on complete dataset, generating buy/sell signals
5. Chart updates to show full historical range with trade markers
6. Results displayed in sidebar (win rate, P&L, profit factor)

Common Tasks

Add New Indicator

1. Add to config/data_config.yaml under indicators.
2. Update IndicatorEngine._compute_indicator in src/data_collector/indicator_engine.py if new type (non-SMA).
3. No DB schema change needed (rows are generic).

Run Backtest

# CLI
python -m data_collector.backtester --symbol BTC --intervals 37m --start 2025-01-01

# API
curl -X POST http://localhost:8000/api/v1/backtests \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC", "intervals": ["37m"], "start_date": "2025-01-01"}'