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
└── api/
    ├── server.py                # FastAPI app, endpoints for data/backtests
    └── dashboard/static/index.html  # Real-time web dashboard
config/data_config.yaml          # Operational config & indicator settings
docker/                          # Docker orchestration & init-scripts
scripts/                         # Deploy, backup, & utility scripts

Architecture & Data Flow

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

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

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.

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"}'