kfox/crypto_trader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
crypto_trader/README.md

345 lines
12 KiB
Markdown
Raw Permalink Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink