380 lines
12 KiB
Markdown
380 lines
12 KiB
Markdown
# GENESIS — Autonomous MT5 Trading System
|
||
|
||
> **Powered by [API2TRADE](https://app.api2trade.com)** — the REST API for MetaTrader 5
|
||
|
||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||
[](https://python.org)
|
||
[](https://app.api2trade.com)
|
||
|
||
GENESIS is a fully autonomous, multi-strategy Forex trading system that connects to any **MetaTrader 5** account via the [API2TRADE](https://app.api2trade.com) REST API. It runs six independent strategy bots in parallel, managed by **Hermes** — an LLM-powered orchestration brain.
|
||
|
||
---
|
||
|
||
## 🏗 Architecture
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ HERMES (Brain) │
|
||
│ GPT-4o-mini · Hourly LLM │
|
||
│ Macro analysis + routing │
|
||
└──────────────┬──────────────┘
|
||
│
|
||
┌────────────────────────┼────────────────────────┐
|
||
│ GENESIS Autonomous Engine │
|
||
│ (genesis_autonomous.py · every 5min) │
|
||
└──┬──────┬──────┬──────┬──────┬──────────────────┘
|
||
│ │ │ │ │
|
||
ARES APOLLO ATHENA ARTEMIS ZEUS HEPHAESTUS
|
||
M1 M5 M5 H1 M5 Grid
|
||
BB+RSI EMA BB+RSI Ichimoku ICT Martingale
|
||
│ │ │ │ │ │
|
||
└──────┴──────┴──────┴──────┴────────┘
|
||
│
|
||
┌─────────▼─────────┐
|
||
│ API2TRADE REST │
|
||
│ app.api2trade.com│
|
||
└─────────┬─────────┘
|
||
│
|
||
┌─────────▼─────────┐
|
||
│ MetaTrader 5 │
|
||
│ (any broker) │
|
||
└───────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🤖 Strategy Bots
|
||
|
||
| Bot | Timeframe | Strategy | Symbols | Expected Signals |
|
||
|-----|-----------|----------|---------|-----------------|
|
||
| **ARES** | M1 | Bollinger Bands + RSI mean reversion | EURUSD, GBPUSD | 10–30/day |
|
||
| **APOLLO** | M5 | EMA 9/21 crossover trend following | EURUSD, GBPUSD | 5–15/day |
|
||
| **ATHENA** | M5 | Multi-TF BB + RSI ranging | EURUSD | 5–15/day |
|
||
| **ARTEMIS** | H1 | Ichimoku Kumo breakout | EURUSD, GBPUSD, GBPJPY | 2–8/day |
|
||
| **ZEUS** | M5 | ICT Smart Money — Liquidity + FVG + OB | EURUSD, GBPUSD, XAUUSD | 3–10/day |
|
||
| **HEPHAESTUS** | — | Grid / Martingale cycling | Any | Continuous |
|
||
|
||
---
|
||
|
||
## 📋 Prerequisites
|
||
|
||
### 1. API2TRADE Account (Required)
|
||
|
||
GENESIS communicates with MT5 exclusively through the [API2TRADE](https://app.api2trade.com) REST API — no local MT5 installation, no Windows VPS required.
|
||
|
||
1. Sign up at **[app.api2trade.com](https://app.api2trade.com)**
|
||
2. Connect your MetaTrader 5 account
|
||
3. Copy your **Account UUID** and **API Key** from the dashboard
|
||
|
||
> **Cost:** €12/month per connected MT5 account · No per-call fees · Unlimited requests
|
||
|
||
### 2. Telegram Bot (Required for alerts)
|
||
|
||
1. Message [@BotFather](https://t.me/BotFather) → `/newbot`
|
||
2. Copy the bot token
|
||
3. Get your Chat ID from [@userinfobot](https://t.me/userinfobot)
|
||
|
||
### 3. OpenAI API Key (Optional — for Hermes brain)
|
||
|
||
1. Get a key at [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
|
||
2. Cost: ~$0.10–0.50/day using `gpt-4o-mini`
|
||
3. Without it: GENESIS runs strategies autonomously without LLM macro analysis
|
||
|
||
---
|
||
|
||
## 🚀 Quick Start
|
||
|
||
### Option A — Docker (Recommended for local testing)
|
||
|
||
```bash
|
||
# 1. Clone the repo
|
||
git clone https://github.com/api2trade/Genesis-Metatrader-Automatic-AI-Trading-System.git
|
||
cd Genesis-Metatrader-Automatic-AI-Trading-System
|
||
|
||
# 2. Run the setup wizard (generates your .env)
|
||
bash setup.sh
|
||
|
||
# 3. Start the container
|
||
docker compose up -d
|
||
|
||
# 4. Watch it run
|
||
docker logs -f genesis
|
||
```
|
||
|
||
### Option B — VPS Production (Ubuntu 22.04)
|
||
|
||
```bash
|
||
# 1. Clone the repo on your VPS
|
||
git clone https://github.com/api2trade/Genesis-Metatrader-Automatic-AI-Trading-System.git
|
||
cd Genesis-Metatrader-Automatic-AI-Trading-System
|
||
|
||
# 2. Run setup wizard
|
||
bash setup.sh
|
||
|
||
# 3. Install cron jobs, CLI shortcuts and log folders
|
||
bash install.sh
|
||
|
||
# 4. Verify cron schedule is active
|
||
crontab -l
|
||
|
||
# 5. Watch live logs
|
||
tail -f /var/log/hermes/autonomous.log
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Manual Setup
|
||
|
||
If you prefer to configure manually instead of using `setup.sh`:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env # Fill in your credentials
|
||
```
|
||
|
||
Required fields:
|
||
|
||
| Variable | Where to get it |
|
||
|----------|----------------|
|
||
| `MT5_ACCOUNT_UUID` | [app.api2trade.com](https://app.api2trade.com) → Dashboard |
|
||
| `MT5_API_KEY` | [app.api2trade.com](https://app.api2trade.com) → API Keys |
|
||
| `MT5_API_USER` | Your API2TRADE username |
|
||
| `MT5_API_PASS` | Your API2TRADE password |
|
||
| `TELEGRAM_BOT_TOKEN` | [@BotFather](https://t.me/BotFather) |
|
||
| `TELEGRAM_CHAT_ID` | [@userinfobot](https://t.me/userinfobot) |
|
||
|
||
---
|
||
|
||
## 💻 Usage
|
||
|
||
### Strategy Analysis
|
||
|
||
```bash
|
||
# Single strategy analysis (no trade placed)
|
||
docker exec -it genesis ares analyze EURUSDxx
|
||
docker exec -it genesis apollo analyze GBPUSDxx
|
||
docker exec -it genesis athena analyze EURUSDxx
|
||
docker exec -it genesis artemis analyze GBPUSDxx
|
||
docker exec -it genesis zeus analyze XAUUSDxx
|
||
|
||
# Scan ALL strategies on one symbol at once
|
||
docker exec -it genesis genesis-scan EURUSDxx
|
||
docker exec -it genesis genesis-scan GBPUSDxx
|
||
```
|
||
|
||
### Live Logs
|
||
|
||
```bash
|
||
# All decisions
|
||
docker exec -it genesis tail -f /var/log/hermes/autonomous.log
|
||
|
||
# Trade journal (JSONL)
|
||
docker exec -it genesis tail -f /var/log/hermes/trade_journal.jsonl
|
||
|
||
# LLM macro cycles
|
||
docker exec -it genesis tail -f /var/log/hermes/trading_cycle.log
|
||
```
|
||
|
||
### Strategy Output Format
|
||
|
||
Every strategy returns a JSON object:
|
||
|
||
```json
|
||
{
|
||
"action": "trade",
|
||
"strategy": "ares-bb-rsi-m1",
|
||
"symbol": "EURUSDxx",
|
||
"direction": "Buy",
|
||
"entry": 1.08542,
|
||
"stop_loss": 1.08392,
|
||
"take_profit": 1.08842,
|
||
"volume": 0.1,
|
||
"rr_ratio": 2.0,
|
||
"sl_pips": 15.0,
|
||
"confidence": "high",
|
||
"reason": "RSI oversold + BB lower touch + session active"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
Genesis-Metatrader-Automatic-AI-Trading-System/
|
||
├── setup.sh # ← Interactive setup wizard (start here)
|
||
├── install.sh # ← VPS production installer
|
||
├── docker-compose.yml # ← Docker deployment
|
||
├── Dockerfile
|
||
├── .env.example # ← Credential template
|
||
│
|
||
├── core/
|
||
│ ├── genesis_autonomous.py # Main engine — runs every 5min via cron
|
||
│ ├── trading_cycle.py # Hermes LLM macro cycle — hourly
|
||
│ ├── genesis_daily_report.py # Daily P&L Telegram report
|
||
│ ├── genesis_brain_feed.py # Hourly Telegram market summary
|
||
│ ├── heartbeat.py # System health check
|
||
│ └── tg_notify.py # Telegram helper
|
||
│
|
||
├── strategies/
|
||
│ ├── ares/ # BB+RSI M1 mean reversion
|
||
│ │ ├── ares_cycle.py # Strategy logic + API2TRADE bridge
|
||
│ │ └── ares_tool.py # CLI: ares analyze/execute EURUSDxx
|
||
│ ├── apollo/ # EMA trend following
|
||
│ ├── athena/ # BB+RSI multi-TF ranging
|
||
│ ├── artemis/ # Ichimoku H1 breakout
|
||
│ ├── zeus/ # ICT Smart Money M5
|
||
│ └── hephaestus/ # Grid/Martingale
|
||
│
|
||
├── configs/
|
||
│ ├── ares_config.yaml # ARES parameters (BB period, RSI thresholds, etc.)
|
||
│ ├── apollo_config.yaml
|
||
│ ├── athena_config.yaml
|
||
│ ├── artemis_config.yaml
|
||
│ ├── zeus_config.yaml
|
||
│ └── hephaestus_config.yaml
|
||
│
|
||
└── backtest/
|
||
├── backtest.py # Python backtester using yfinance
|
||
└── BB_RSI_MeanReversion.mq5 # MT5 Expert Advisor (manual backtest)
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ API2TRADE — How It Works
|
||
|
||
GENESIS uses API2TRADE as the bridge between Python and MetaTrader 5. Every strategy calls these endpoints directly:
|
||
|
||
```python
|
||
# Get account balance
|
||
GET /AccountSummary?id={session_uuid}
|
||
→ {"balance": 10000.0, "equity": 10000.0, "currency": "USD"}
|
||
|
||
# Get live quote
|
||
GET /Quote?id={session_uuid}&symbol=EURUSDxx
|
||
→ {"Bid": 1.08540, "Ask": 1.08542}
|
||
|
||
# Place a trade
|
||
GET /OrderSendSafe?id={session_uuid}&symbol=EURUSDxx&operation=Buy&volume=0.1&stoploss=1.083&takeprofit=1.090&comment=GENESIS-ARES
|
||
→ {"ticket": 12345678}
|
||
|
||
# Close a position
|
||
GET /OrderCloseSafe?id={session_uuid}&ticket=12345678&lots=0.1
|
||
```
|
||
|
||
No WebSocket setup, no local MT5 terminal, no Windows server. Just REST calls from any Python environment.
|
||
|
||
> 💡 **Sign up at [app.api2trade.com](https://app.api2trade.com) to get your session UUID and API key.**
|
||
|
||
---
|
||
|
||
## 🛡 Risk Management
|
||
|
||
Hard limits enforced before **every** trade — cannot be bypassed:
|
||
|
||
| Limit | Default | Config |
|
||
|-------|---------|--------|
|
||
| Max risk per trade | **2% of balance** | `MAX_RISK_PCT` in `.env` |
|
||
| Max lot size | **3.0 lots** | `MAX_LOTS` in `.env` |
|
||
| Max open positions | **4** | `MAX_POSITIONS` in `.env` |
|
||
| Stop loss | **Required** (5–150 pips) | Per strategy config |
|
||
| Spread filter | **1.0–3.0 pips** | Per strategy YAML |
|
||
| News filter | **±15 min** around high-impact | Per strategy YAML |
|
||
|
||
---
|
||
|
||
## ⚙️ Configuration
|
||
|
||
Each strategy has a dedicated YAML config in `configs/`. Example for ARES:
|
||
|
||
```yaml
|
||
# configs/ares_config.yaml
|
||
strategy:
|
||
name: ARES
|
||
magic_number: 1001
|
||
|
||
bollinger:
|
||
period: 20
|
||
std_dev: 2.0
|
||
|
||
rsi:
|
||
period: 14
|
||
oversold: 30
|
||
overbought: 70
|
||
|
||
risk:
|
||
risk_pct: 0.01 # 1% per trade
|
||
max_spread_pips: 1.0
|
||
min_rr_ratio: 1.5
|
||
|
||
sessions:
|
||
allowed:
|
||
- {start: 7, end: 20} # GMT hours
|
||
```
|
||
|
||
---
|
||
|
||
## 🖥 VPS Deployment (Recommended)
|
||
|
||
For 24/7 autonomous trading, deploy on a Ubuntu 22.04 VPS:
|
||
|
||
```bash
|
||
# Minimum spec: 2 vCPU, 2GB RAM, 20GB SSD
|
||
# Cost: ~€4–8/month (Hetzner, Contabo, DigitalOcean)
|
||
|
||
bash setup.sh # Configure credentials
|
||
bash install.sh # Install Python, venv, cron jobs, CLI shortcuts
|
||
```
|
||
|
||
The installer sets up:
|
||
- Python 3.11 virtual environment at `/opt/hermes-agent/.venv-hermes`
|
||
- Cron job: `genesis_autonomous.py` every 5 minutes
|
||
- Cron job: `trading_cycle.py` (Hermes LLM) every hour
|
||
- Log rotation at `/var/log/hermes/`
|
||
- CLI shortcuts: `ares`, `apollo`, `athena`, `artemis`, `zeus`, `hephaestus`, `genesis-scan`
|
||
|
||
---
|
||
|
||
## 📊 Backtesting
|
||
|
||
```bash
|
||
# Backtest ARES on EURUSD (last 12 months)
|
||
python3 backtest/backtest.py --strategy ares --symbol EURUSD --days 365
|
||
|
||
# Or open the MT5 EA in MetaEditor for native backtesting
|
||
# backtest/BB_RSI_MeanReversion.mq5
|
||
```
|
||
|
||
---
|
||
|
||
## 🤝 Contributing
|
||
|
||
GENESIS is open source under **GPL v3** — forks must also be open source.
|
||
|
||
1. Fork the repo
|
||
2. Create your feature branch (`git checkout -b feature/my-strategy`)
|
||
3. Commit your changes
|
||
4. Open a Pull Request
|
||
|
||
---
|
||
|
||
## ⚠️ Disclaimer
|
||
|
||
This software is for **educational and research purposes**. Forex trading involves substantial risk of loss. Past performance does not guarantee future results. Always test on a **demo account** before trading with real money. The authors accept no responsibility for financial losses.
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
GPL-3.0 · See [LICENSE](LICENSE)
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Built with API2TRADE · [app.api2trade.com](https://app.api2trade.com)**
|
||
|
||
*Connect any MT5 account to Python in minutes · €12/month per account*
|
||
|
||
</div>
|