🤖 Advanced Crypto Trading Bot

Professional-grade automated trading system for cryptocurrencies with advanced features, real-time monitoring, and production-ready deployment options.

English | Español

---

⚠️ DISCLAIMER

This software is for educational and research purposes only. Cryptocurrency trading carries significant risks and may result in total capital loss. Use this bot at your own risk.

• ❌ NO profitability guarantees
• ❌ NO liability for losses
• ✅ Always start with testnet
• ✅ Fully understand before using real money

---

📋 Table of Contents

• Features
• Quick Start
• Installation
• Configuration
• Usage
• Deployment
• Architecture
• Strategies
• Security
• Contributing
• License

---

✨ Features

🤖 Automated Trading

• ✅ 24/7 market monitoring and analysis
• ✅ Automatic signal execution
• ✅ Real-time position management
• ✅ Auto-restart on failure
• ✅ Multi-symbol support (BTC, ETH, SOL, etc.)

📊 Advanced Backtesting

• ✅ Historical simulation with real market data
• ✅ Configurable commissions and slippage
• ✅ Complete metrics: Sharpe, Sortino, Calmar ratios
• ✅ Drawdown analysis and win rate tracking
• ✅ Equity curve visualization
• ✅ CSV export for further analysis

📈 Trading Strategies

• ✅ SMA Crossover - Golden/Death Cross signals
• ✅ RSI + Bollinger Bands - Oversold/overbought detection
• ✅ EMA Scalping - Fast/Slow EMA with volume confirmation
• ✅ Multi-Timeframe Analysis - Trend confirmation (4h → 1h)
• ✅ Easily extensible for custom strategies

🛡️ Risk Management

• ✅ Position Sizing - Percentage-based capital allocation
• ✅ Stop Loss & Take Profit - Automatic exit points
• ✅ Trailing Stop - Lock in profits dynamically
• ✅ Kill Switch - Auto-halt on max drawdown
• ✅ Circuit Breaker - Halt on extreme volatility/volume
• ✅ Max Positions Limit - Control portfolio exposure
• ✅ Consecutive Loss Protection - Stop after X losses

🖥️ Real-Time Dashboard

• ✅ Live trading statistics
• ✅ Equity curve visualization
• ✅ Open positions tracking
• ✅ Trade history
• ✅ Real-time market data
• ✅ Performance metrics

🗄️ Database Integration

• ✅ SQLite persistence
• ✅ Automatic trade logging
• ✅ Position snapshots
• ✅ Historical data storage
• ✅ Performance analytics
• ✅ Query capabilities for analysis

📱 Telegram Notifications

• ✅ Real-time trade alerts
• ✅ Position updates
• ✅ Error notifications
• ✅ Daily performance summaries
• ✅ Bot status updates

🚀 Deployment Ready

• ✅ Railway (PaaS) - Quick deploy
• ✅ Oracle Cloud - Free forever option
• ✅ Docker support
• ✅ Systemd service configuration
• ✅ Auto-restart policies
• ✅ Environment-based configuration

🔒 Security

• ✅ API keys in environment variables
• ✅ Testnet/Production separation
• ✅ Order validation before execution
• ✅ Auto-recovery from connection errors
• ✅ Comprehensive logging
• ✅ No hardcoded credentials

---

🚀 Quick Start

# 1. Clone repository
git clone https://github.com/Astolfu/trading-bot.git
cd trading-bot

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
# Edit .env with your settings

# 5. Run backtest
python scripts/run_backtest.py --symbols BTCUSDT --days 90

# 6. Run bot (testnet)
python scripts/run_bot.py

Access dashboard at: http://localhost:5000

---

📦 Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)
• Git
• Binance account (for API keys)

Step-by-Step Installation

1. Clone the repository

   git clone https://github.com/Astolfu/trading-bot.git
   cd trading-bot
   

2. Create virtual environment

   python -m venv venv
   
   # Activate on Windows
   venv\Scripts\activate
   
   # Activate on Linux/Mac
   source venv/bin/activate
   

3. Install dependencies

   pip install --upgrade pip
   pip install -r requirements.txt
   

4. Get Binance API Keys

   • Testnet: testnet.binance.vision
   • Production: binance.com → Account → API Management

5. Configure environment

   cp .env.example .env
   

   Edit .env and add your API keys and preferences.

6. Setup Telegram (Optional)

   • Create bot with @BotFather
   • Get your Chat ID
   • Add to .env

   See TELEGRAM_SETUP.md for detailed guide.

---

⚙️ Configuration

Essential Settings

# Exchange API
BINANCE_TESTNET_API_KEY=your_testnet_key
BINANCE_TESTNET_API_SECRET=your_testnet_secret
USE_TESTNET=true

# Trading
EXECUTE_REAL=true  # true = execute orders, false = simulation only
SYMBOLS=BTCUSDT,ETHUSDT,SOLUSDT
TIMEFRAME=1h
INITIAL_CAPITAL=10000

# Risk Management
RISK_PER_TRADE=2  # 2% of capital per trade
MAX_POSITIONS=5
STOP_LOSS_PERCENT=2
TAKE_PROFIT_PERCENT=4
MAX_DRAWDOWN_PERCENT=10

# Strategies
DEFAULT_STRATEGY=EMA_SCALP  # SMA_CROSS, RSI_BB, EMA_SCALP

See CONFIGURATION.md for all options.

---

📖 Usage

Backtesting

# Basic backtest
python scripts/run_backtest.py --symbols BTCUSDT --days 90

# Multi-symbol backtest
python scripts/run_backtest.py --symbols BTCUSDT,ETHUSDT,SOLUSDT --days 180

# Custom date range
python scripts/run_backtest.py \
    --symbols BTCUSDT \
    --start 2024-01-01 \
    --end 2024-12-31 \
    --timeframe 1h

Running the Bot

# Start bot (testnet recommended)
python scripts/run_bot.py

# Bot will:
# - Connect to Binance
# - Initialize database
# - Start dashboard on port 5000
# - Begin monitoring markets
# - Execute trades based on signals

Dashboard Access

Open browser: http://localhost:5000

Features:

• Real-time equity curve
• Active positions
• Trade history
• Performance metrics

Database Queries

# Check database contents
python scripts/check_database.py

# Simulate a test trade
python scripts/simulate_trade.py

---

🌐 Deployment

Option 1: Oracle Cloud (Free Forever - Recommended)

1. Create Oracle Cloud account
2. Launch VM instance (ARM recommended - up to 24GB RAM free)
3. Setup bot with systemd
4. Configure firewall

Cost: $0/month (Always Free tier)
Setup: 45-60 minutes

See oracle_cloud_deployment_guide.md

Option 2: DigitalOcean ($4/month)

1. Create Droplet (512MB RAM)
2. Clone repository
3. Install dependencies
4. Setup systemd service

Cost: $4/month ($200 credit for new users)
Setup: 30 minutes

Option 3: Docker (Any Platform)

# Build image
docker build -t trading-bot .

# Run container
docker run -d --env-file .env -p 5000:5000 trading-bot

Note: For production trading, Oracle Cloud is recommended as it's free forever and Binance doesn't block its IPs.

---

🏗️ Architecture

trading-bot/
├── bot/                    # Main trading bot
│   ├── trading_bot.py      # Core bot logic
│   └── order_manager.py    # Order execution
├── strategies/             # Trading strategies
│   ├── sma_cross.py        # SMA Crossover
│   ├── rsi_bb.py           # RSI + Bollinger Bands
│   └── ema_scalping.py     # EMA Scalping
├── risk/                   # Risk management
│   ├── risk_manager.py     # Position sizing
│   └── position_manager.py # Position tracking
├── database/               # Data persistence
│   ├── db_manager.py       # SQLite manager
│   └── schema.sql          # Database schema
├── dashboard/              # Web dashboard
│   ├── server.py           # Flask server
│   └── templates/          # HTML templates
├── core/                   # Core utilities
│   ├── exchange_connector.py
│   ├── market_data.py
│   └── logger.py
├── notifications/          # Alerts
│   └── telegram_notifier.py
├── backtesting/            # Backtest engine
│   ├── backtester.py
│   └── metrics.py
└── scripts/                # Executable scripts
    ├── run_bot.py
    └── run_backtest.py

---

📊 Strategies

1. SMA Crossover

Signals:

• Buy: SMA20 crosses above SMA50 (Golden Cross)
• Sell: SMA20 crosses below SMA50 (Death Cross)

Best for: Medium to long-term trends

2. RSI + Bollinger Bands

Signals:

• Buy: RSI < 30 AND price touches lower BB
• Sell: RSI > 70 AND price touches upper BB

Best for: Range-bound markets

3. EMA Scalping

Signals:

• Buy: EMA8 crosses above EMA21 + volume spike
• Sell: EMA8 crosses below EMA21

Best for: Active markets with good volume

Multi-Timeframe Filter

Confirms trend on higher timeframe (4h) before executing 1h signals.

Configurable per symbol.

---

🔐 Security

API Key Protection

✅ Never hardcode keys - Use environment variables
✅ Testnet first - Validate before production
✅ Read-only keys - Disable withdrawals
✅ IP Whitelist - Restrict API access
✅ Git ignored - .env never committed

Trading Safety

✅ Kill Switch - Auto-stop on max drawdown
✅ Circuit Breaker - Halt on extreme volatility
✅ Position Limits - Max concurrent positions
✅ Order Validation - Verify before executio