# Crypto Trading Bot Platform

A simplified crypto trading bot platform for strategy testing and development. Test multiple trading strategies in parallel using real OKX market data with virtual trading simulation.

## Overview

This platform enables rapid strategy testing within 1-2 weeks of development. Built with a monolithic architecture for simplicity, it supports 5-10 concurrent trading bots with real-time monitoring and performance tracking.

## Key Features

- **Multi-Bot Management**: Run 5-10 trading bots simultaneously with different strategies
- **Real-time Monitoring**: Live OHLCV charts with bot trading signals overlay
- **📊 Modular Chart Layers**: Advanced technical analysis with 26+ indicators and strategy presets
- **🤖 Bot Signal Integration**: Real-time bot signal visualization with performance analytics
- **Virtual Trading**: Simulation-first approach with realistic fee modeling
- **JSON Configuration**: Easy strategy parameter testing without code changes
- **Backtesting Engine**: Test strategies on historical market data
- **Crash Recovery**: Automatic bot restart and state restoration

## Chart System Features

The platform includes a sophisticated modular chart system with:

- **Technical Indicators**: 26+ professionally configured indicators (SMA, EMA, Bollinger Bands, RSI, MACD)
- **Strategy Presets**: 5 real-world trading strategy templates (EMA crossover, momentum, mean reversion)
- **Bot Integration**: Real-time visualization of bot signals, trades, and performance
- **Custom Indicators**: User-defined indicators with JSON persistence
- **Validation System**: 10+ validation rules with detailed error reporting
- **Modular Architecture**: Independently testable chart layers and components

📊 **[Complete Chart Documentation](docs/components/charts/README.md)**

## Tech Stack

- **Framework**: Python 3.10+ with Dash (unified frontend/backend)
- **Database**: PostgreSQL with optimized OHLCV data storage
- **Real-time**: Redis pub/sub for live updates
- **Package Management**: UV
- **Development**: Docker for consistent environment

## Quick Start

### Prerequisites
- Python 3.10+, Docker, UV package manager

### Setup

**📖 For detailed setup instructions, see [docs/setup.md](docs/setup.md)**

Quick setup:
```bash
python scripts/dev.py setup        # Setup environment
python scripts/dev.py start        # Start services  
python scripts/dev.py dev-server   # Start with hot reload
```

## Project Structure

```
├── app.py                   # Main Dash application
├── bot_manager.py          # Bot lifecycle management
├── database/               # PostgreSQL models and connection
├── data/                   # OKX API integration
├── components/             # Dashboard UI components
├── strategies/             # Trading strategy modules
├── config/bot_configs/     # JSON bot configurations
└── docs/                   # Project documentation
```

## Documentation

- **[Setup Guide](docs/setup.md)** - Complete setup instructions for new machines
- **[Product Requirements](docs/crypto-bot-prd.md)** - Complete system specifications and requirements
- **[Technical Architecture](docs/architecture.md)** - Implementation details and component design
- **[Platform Overview](docs/specification.md)** - Human-readable system overview
- **📊 [Chart Layers System](docs/components/charts/README.md)** - Modular chart system with technical indicators
- **🤖 [Bot Integration Guide](docs/components/charts/bot-integration.md)** - Real-time bot signal visualization

## Configuration Example

Bot configurations use simple JSON files for rapid testing:

```json
{
  "bot_id": "ema_crossover_01",
  "strategy_file": "ema_crossover.json",
  "symbol": "BTC-USDT",
  "virtual_balance": 10000,
  "enabled": true
}
```

## Development Timeline

**Target**: Functional system within 1-2 weeks
- **Phase 1** (Days 1-5): Database, data collection, basic visualization
- **Phase 2** (Days 6-10): Bot management, backtesting, trading logic  
- **Phase 3** (Days 11-14): Testing, optimization, deployment

## Contributing

1. Review [architecture documentation](docs/architecture.md) for technical approach
2. Check [task list](tasks/tasks-prd-crypto-bot-dashboard.md) for available work
3. Follow project coding standards and use UV for dependencies
4. Update documentation when adding features