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

12 KiB
Raw Blame History

Cryptocurrency Trading Platform

Python 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)

# 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:

# 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:

# 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:

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 for details.

Environment Variables

Create .env file (optional):

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 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

Quick Links

Testing

Run the test suite:

# 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

# 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 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 for:

  • Development environment setup
  • Coding standards
  • Testing guidelines
  • Architecture overview
  • Adding new features

License

MIT License

Support

  • Documentation: See docs/ directory
  • API Docs: http://localhost:8000/docs (when running)
  • Issues: Report bugs and request features via GitHub Issues
  • FAQ: Check FAQ 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 for details.

Reference in New Issue View Git Blame Copy Permalink