# 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: Advanced order types (trailing stop, bracket, OCO, iceberg, TWAP/VWAP), order placement, management, and position closing
  - Dashboard: AutoPilot controls, system health monitoring, real-time updates, live P&L widgets, ML confidence gauge, market regime indicators
  - Portfolio: Allocation charts, position management, performance analytics, VaR analysis, correlation analysis, automated rebalancing
  - Backtesting: Historical strategy testing with walk-forward analysis, Monte Carlo simulation, parameter optimization, and progress tracking
  - Trade Journal: Comprehensive trade history with filtering, statistics, analysis, and CSV export
  - Settings: Exchange management, alerts, alert history, risk configuration
  - Mobile Responsive: Touch-optimized navigation and controls for mobile devices
- **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
  - **Online Learning**: Incremental model updates with concept drift detection
  - **Confidence Calibration**: Platt scaling and isotonic regression for accurate confidence scores
  - **Model Explainability**: SHAP values for feature importance and prediction explanations
  - **Advanced Regime Detection**: HMM and GMM-based market regime classification
- **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)
- **Advanced Order Types**: Trailing stop-loss, bracket orders (entry + TP + SL), TWAP, VWAP
- **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
  - **Walk-Forward Analysis**: Rolling window optimization for robust parameter selection
  - **Monte Carlo Simulation**: Statistical analysis with confidence intervals and distribution metrics
  - **Parameter Optimization**: Grid search, Bayesian optimization, and genetic algorithms
- **Strategy Framework**: Multi-timeframe strategies with scheduling and optimization
- **Advanced Order Execution**: TWAP/VWAP execution algorithms with order book impact modeling
- **Portfolio Rebalancing**: Automated rebalancing with threshold and time-based triggers
- **Advanced Risk Management**: 
  - Stop-loss, position sizing (Kelly Criterion, volatility-adjusted, regime-aware), drawdown limits, daily loss limits
  - **Value at Risk (VaR)**: Historical, Parametric, and Monte Carlo VaR calculation methods
  - **Portfolio Correlation Analysis**: Diversification scoring, concentration risk analysis
  - **Correlation-based Position Limits**: Prevent over-concentration in correlated assets
- **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, bracket orders, OCO, iceberg
- Execution algorithms: TWAP (Time-Weighted Average Price), VWAP (Volume-Weighted Average Price)
- Order book impact modeling for realistic execution simulation
- Real-time position tracking
- Paper trading simulator with realistic fee simulation
- Futures and leverage trading
- Trade journal with comprehensive filtering and analysis

### 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, order book impact)
- Performance metrics (Sharpe, Sortino, drawdown, VaR)
- **Walk-Forward Analysis**: Rolling window optimization for robust parameter selection
- **Monte Carlo Simulation**: Statistical analysis with confidence intervals and distribution metrics
- Parameter optimization (grid search, Bayesian optimization, genetic algorithms)
- Export results

### Risk Management

- **Position Sizing**: Fixed, Kelly Criterion (fractional), volatility-adjusted, regime-aware, confidence-based
- **Stop-Loss Orders**: Standard, trailing stop, bracket orders
- **Maximum Drawdown Limits**: Portfolio-level drawdown protection
- **Daily Loss Limits**: Per-day loss restrictions
- **Portfolio Allocation Limits**: Correlation-based position limits
- **Value at Risk (VaR)**: Historical, Parametric, and Monte Carlo VaR calculation methods
- **Portfolio Correlation Analysis**: Diversification scoring, concentration risk analysis
- **Automated Rebalancing**: Threshold and time-based portfolio rebalancing

### Portfolio Management

- Real-time P&L tracking with live widgets
- Advanced analytics (Sharpe ratio, Sortino ratio, drawdown analysis)
- **Automated Portfolio Rebalancing**: Threshold and time-based triggers with fee-aware logic
- **Risk Analysis**: VaR calculation, correlation analysis, diversification scoring
- Performance charts and allocation visualization
- Export and reporting (CSV, PDF, tax 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.