# Cryptocurrency Trading Platform [![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) A comprehensive cryptocurrency trading platform with multi-exchange support, real-time trading, backtesting, advanced risk management, and portfolio analytics. Built with a modern web architecture (React frontend + FastAPI backend) while preserving the core Python trading engine. ## Features - **Modern Web UI**: React + TypeScript + Material-UI with comprehensive feature coverage - Strategy Management: Full CRUD operations with parameter configuration - Manual Trading: Order placement, management, and position closing - Dashboard: AutoPilot controls, system health monitoring, real-time updates - Portfolio: Allocation charts, position management, performance analytics - Backtesting: Historical strategy testing with progress tracking - Settings: Exchange management, alerts, alert history, risk configuration - **RESTful API**: FastAPI with auto-generated documentation - **Real-Time Updates**: WebSocket integration for live order, position, and price updates - **Intelligent Autopilot**: ML-based trading automation - ML strategy selection with LightGBM/XGBoost ensemble models - Configurable training: historical days, timeframe, symbols - Background model training via Celery with real-time progress - Auto-reload of trained models without restart - Pre-flight order validation (prevents failed orders) - Smart order types: LIMIT for better entries, MARKET for urgency - Stop-loss vs take-profit detection for optimal exit strategy - Multi-symbol support with independent autopilot instances - **Multi-Tier Pricing Data**: Robust pricing data system with automatic failover - Primary providers: CCXT-based (Kraken, Coinbase, Binance) with automatic failover - Fallback provider: CoinGecko API (free tier, no API keys required) - Smart caching with configurable TTL - Health monitoring with circuit breaker pattern - Works without exchange integrations for paper trading, ML, and backtesting - **Multi-Exchange Support**: Trade on multiple exchanges (starting with Coinbase) - **Paper Trading**: Test strategies with virtual funds ($100 default, configurable) - Configurable fee exchange model (Coinbase, Kraken, Binance) - Realistic fee simulation with maker/taker rates - Immediate order execution (no pending orders) - **Advanced Backtesting**: Realistic backtesting with slippage, fees, and order book simulation - **Strategy Framework**: Multi-timeframe strategies with scheduling and optimization - **Risk Management**: Stop-loss, position sizing (Kelly Criterion), drawdown limits, daily loss limits - **Portfolio Analytics**: Advanced metrics (Sharpe ratio, Sortino ratio, drawdown analysis) - **Alert System**: Price, indicator, risk, and system alerts with history tracking - **Export & Reporting**: CSV, PDF, and tax reporting (FIFO/LIFO/specific identification) - **Futures & Leverage**: Support for futures trading and leverage - **Fully Local**: No telemetry, all data stored locally with encryption - **Transparent Operations**: System health indicators, data freshness tracking, operation visibility - **Background Task Processing**: Celery-powered ML training and report generation - **Distributed State Management**: Redis-backed autopilot state persistence across restarts ## Quick Start ### Docker (Recommended) ```bash # Build and run docker-compose up --build # Access application open http://localhost:8000 ``` ### Development **Prerequisites**: - Python 3.11+ - Node.js 18+ - PostgreSQL 14+ - Redis 5.0+ **Quick Setup**: ```bash # Create virtual environment python -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt # Install frontend dependencies cd frontend && npm install && cd .. # Start all services (Redis, Celery, Backend, Frontend) ./scripts/start_all.sh ``` **Manual Setup**: ```bash # 1. Start Redis (choose one option) sudo service redis-server start # With sudo # OR: redis-server --daemonize yes # Without sudo (for containers) # 2. Start Celery worker (background tasks) celery -A src.worker.app worker --loglevel=info & # 3. Start backend API uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000 & # 4. Start frontend cd frontend && npm run dev ``` Access frontend at: http://localhost:3000 API docs at: http://localhost:8000/docs **Verify Setup**: ```bash python scripts/verify_redis.py ``` ## Architecture ``` Frontend (React) → FastAPI → Python Services → Database ``` - **Frontend**: React + TypeScript + Material-UI - **Backend**: FastAPI (Python) - **Services**: Existing Python code (trading engine, strategies, etc.) - **Database**: PostgreSQL ## Project Structure ``` crypto_trader/ ├── backend/ # FastAPI application │ ├── api/ # API endpoints │ └── core/ # Dependencies, schemas ├── frontend/ # React application │ └── src/ │ ├── pages/ # Page components (Dashboard, Strategies, Trading, Portfolio, Backtesting, Settings) │ ├── components/ # Reusable components (StatusIndicator, SystemHealth, etc.) │ ├── api/ # API client functions │ ├── hooks/ # Custom React hooks (useWebSocket, useRealtimeData) │ ├── contexts/ # React contexts (SnackbarContext) │ ├── types/ # TypeScript type definitions │ └── utils/ # Utility functions ├── src/ # Core Python code │ ├── trading/ # Trading engine │ ├── strategies/ # Strategy framework │ ├── portfolio/ # Portfolio tracker │ ├── backtesting/ # Backtesting engine │ └── ... ├── tests/ # Test suite │ ├── unit/ # Unit tests │ ├── integration/ # Integration tests (including frontend API workflows) │ └── e2e/ # End-to-end tests ├── docs/ # Documentation │ ├── user_manual/ # User documentation │ ├── developer/ # Developer documentation │ └── architecture/ # Architecture documentation └── config/ # Configuration files ``` ## API Endpoints - **Trading**: `/api/trading/*` - Orders, positions, balance - **Portfolio**: `/api/portfolio/*` - Portfolio data and history - **Strategies**: `/api/strategies/*` - Strategy management - **Backtesting**: `/api/backtesting/*` - Run backtests - **Exchanges**: `/api/exchanges/*` - Exchange management - **Autopilot**: `/api/autopilot/*` - Intelligent autopilot - **Market Data**: `/api/market-data/*` - Market data endpoints - **WebSocket**: `/ws/` - Real-time updates Full API documentation: http://localhost:8000/docs ## Configuration Configuration files are stored in `~/.config/crypto_trader/` following XDG Base Directory Specification. Data is stored in `~/.local/share/crypto_trader/`: - `trading.db` - Legacy SQLite database (removed) - `historical/` - Historical market data - `logs/` - Application logs See [Configuration Guide](docs/user_manual/configuration.md) for details. ## Environment Variables Create `.env` file (optional): ```env VITE_API_URL=http://localhost:8000 VITE_WS_URL=ws://localhost:8000/ws/ DATABASE_URL=postgresql+asyncpg://user:password@localhost/dbname ``` ## Requirements - **Python**: 3.11 or higher - **Node.js**: 18+ (for frontend) - **PostgreSQL**: 14+ (required for database) - **Redis**: 5.0+ (required for state management) - **Celery**: Included in requirements.txt (for background tasks) - **Docker**: Optional, for containerized deployment ## Features in Detail ### Trading - Market and limit orders - Advanced order types (stop-loss, take-profit, trailing stop, OCO, iceberg) - Real-time position tracking - Paper trading simulator - Futures and leverage trading ### Strategies - Pre-built strategies: - **Technical**: RSI, MACD, Moving Average, Bollinger Mean Reversion - **Composite**: Confirmed Strategy, Divergence Strategy - **Accumulation**: DCA (Dollar Cost Averaging), Grid Trading - **Advanced**: Momentum, Consensus (multi-strategy voting) - **Quantitative**: Statistical Arbitrage (Pairs Trading), Volatility Breakout - **Alternative Data**: Sentiment/News Trading (with Fear & Greed Index) - **Market Making**: Bid/Ask spread capture with inventory management - Custom strategy development - Multi-timeframe support - Strategy scheduling with real-time status tracking - Parameter optimization (grid search, genetic, Bayesian) - **See [Pairs Trading Guide](docs/guides/pairs_trading_setup.md)** for advanced strategy configuration ### Backtesting - Historical data replay - Realistic simulation (slippage, fees) - Performance metrics (Sharpe, Sortino, drawdown) - Parameter optimization - Export results ### Risk Management - Position sizing (fixed, Kelly Criterion, volatility-based) - Stop-loss orders - Maximum drawdown limits - Daily loss limits - Portfolio allocation limits ### Portfolio Management - Real-time P&L tracking - Advanced analytics - Portfolio rebalancing - Performance charts - Export and reporting ### Pricing Data Providers - **Multi-Tier Architecture**: Primary CCXT providers with CoinGecko fallback - **Automatic Failover**: Seamless switching between providers on failure - **Health Monitoring**: Real-time provider status with circuit breakers - **Smart Caching**: Configurable TTL-based caching for performance - **No API Keys Required**: Works with public data APIs for paper trading - **WebSocket Support**: Real-time price updates via WebSocket - **Provider Configuration**: Full UI for managing provider priorities and settings ## Documentation - **[User Manual](docs/user_manual/README.md)** - Complete user guide - **[Developer Guide](docs/developer/README.md)** - Development documentation - **[API Documentation](http://localhost:8000/docs)** - Interactive API docs - **[Architecture Docs](docs/architecture/overview.md)** - System architecture - **[Deployment Guide](docs/deployment/README.md)** - Deployment instructions ### Quick Links - [Getting Started](docs/user_manual/getting_started.md) - [Trading Guide](docs/user_manual/trading.md) - [Strategy Development](docs/user_manual/strategies.md) - [Pairs Trading Guide](docs/guides/pairs_trading_setup.md) - [Backtesting Guide](docs/user_manual/backtesting.md) - [Configuration](docs/user_manual/configuration.md) - [Troubleshooting](docs/user_manual/troubleshooting.md) - [FAQ](docs/user_manual/faq.md) ## Testing Run the test suite: ```bash # Install test dependencies pip install -r tests/requirements.txt # Run all tests pytest # Run with coverage pytest --cov=src --cov-report=html # Run specific test category pytest -m unit pytest -m integration pytest -m e2e ``` ## Docker Deployment ```bash # Build docker build -t crypto-trader:latest . # Run docker run -d \ -p 8000:8000 \ -v $(pwd)/data:/app/data \ -v $(pwd)/config:/app/config \ crypto-trader:latest ``` ## Contributing We welcome contributions! See [Contributing Guidelines](docs/developer/contributing.md) for details. 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Write/update tests 5. Submit a pull request ## Development See [Developer Guide](docs/developer/README.md) for: - Development environment setup - Coding standards - Testing guidelines - Architecture overview - Adding new features ## License MIT License ## Support - **Documentation**: See [docs/](docs/) directory - **API Docs**: http://localhost:8000/docs (when running) - **Issues**: Report bugs and request features via GitHub Issues - **FAQ**: Check [FAQ](docs/user_manual/faq.md) for common questions ## Migration from PyQt6 The application has been migrated from PyQt6 desktop app to web architecture while preserving 90% of existing Python code. See [Migration Guide](docs/migration_guide.md) for details.