btc-trading/GEMINI.md

BTC Accumulation Bot - Context & Guidelines

High-performance crypto data collection and trading system for cbBTC on Hyperliquid, optimized for Synology NAS deployment.

Project Overview

• Purpose: Collect 1-minute candle data for cbBTC-PERP from Hyperliquid, compute technical indicators on custom timeframes (e.g., 37m, 148m), and execute accumulation strategies.
• Tech Stack:
  • Backend: Python 3.11+ (FastAPI, asyncio, websockets, asyncpg, pandas, numpy).
  • Database: TimescaleDB (PostgreSQL 15 extension) on Synology DS218+.
  • Infrastructure: Docker Compose (Network Mode: host for performance).
  • Frontend: Vanilla JS dashboard for real-time monitoring and charts.
• Architecture:
  • DataCollector: Main orchestrator managing WebSocket ingestion, buffering, and database writes.
  • IndicatorEngine: Computes technical indicators (MA44, MA125) on multiple timeframes.
  • Brain: Decision engine that evaluates signals based on indicator state.
  • CustomTimeframeGenerator: Dynamically generates non-standard intervals from 1m base candles.

Building and Running

Development & Deployment

• Deployment: Run chmod +x scripts/deploy.sh && ./scripts/deploy.sh to scaffold directories and start Docker services.
• Service Control:
  • Start: cd docker && docker-compose up -d
  • Stop: cd docker && docker-compose down
  • Logs: docker-compose logs -f [service_name] (e.g., data_collector, api_server, timescaledb)
• Backups: scripts/backup.sh (manages PostgreSQL dumps with 7-day retention).

Local API Server (Hybrid Setup)

To run the dashboard/API locally while the database remains on the NAS:

1. NAS Config: Ensure 5433:5432 mapping is active in docker-compose.yml.
2. Local Environment: Create a .env file locally:

   DB_HOST=NAS_IP_ADDRESS
   DB_PORT=5433
   DB_NAME=btc_data
   DB_USER=btc_bot
   DB_PASSWORD=YOUR_PASSWORD
   

3. Run Locally:

   pip install -r requirements.txt
   python -m uvicorn src.api.server:app --host 0.0.0.0 --port 8000 --reload
   

Testing

• Manual Verification:
  • API Health: curl http://localhost:8000/api/v1/health
  • DB Status: docker exec btc_timescale pg_isready -U btc_bot
• Indicator Testing: scripts/test_ma44_performance.py

Development Conventions

Coding Standards

• Modularity: Keep files small (< 500 lines) and focused on a single responsibility.
• Async First: Use asyncio for all I/O bound operations (WebSockets, Database, API).
• Type Safety: Use Pydantic models for configuration and API responses.
• Logging: Use structured logging with console prefixes: [SYSTEM], [CLP], [HEDGE], [MONITOR].
• Golden Rule (Data): Always read the source of truth from the blockchain or primary API (Hyperliquid) rather than relying on local calculations if possible.
• Golden Rule (Positioning): CLP positions must use symmetric grid snapping.

Database Design

• Hypertables: Use TimescaleDB hypertables for candles and indicators with weekly partitioning.
• Compression: Automatic compression is enabled for data older than 7 days to save space on NAS.
• Gaps: Continuous gap detection and automatic backfill from Hyperliquid REST API.

Dashboard & API

• FastAPI: Main entry point in src/api/server.py.
• Static Assets: Dashboard located in src/api/dashboard/static/.
• Indicator Engine: JS-side mirror of indicators for the UI chart located in src/api/dashboard/static/js/indicators/.

Project Roadmap

• Phase 1 (Complete): Data collection, TimescaleDB integration, Basic API.
• Phase 2 (In-Progress): Indicator Engine (SMA, EMA, RSI, MACD), Brain decision logic.
• Phase 3 (TODO): Web3 execution layer (Uniswap V3 swaps on Base).
• Phase 4 (TODO): Aave V3 integration for yield on collected cbBTC.