Docs: Add comprehensive ARCHITECTURE.md - Auto-Swap feature, Risk Management, Components documented
This commit is contained in:
Marc Blatter
parent
d4dabe38fc
commit
138cf018d2
609
ARCHITECTURE.md
609
ARCHITECTURE.md
|
|
@ -1,238 +1,385 @@
|
||||||
# Trading Bot V0.2 — System Architecture
|
# Trading Bot V0.2 — System Architecture
|
||||||
|
|
||||||
|
**Version:** 0.2 (Production)
|
||||||
|
**Last Updated:** 2026-07-08
|
||||||
|
**Status:** 🟢 LIVE with Auto-Swap Feature
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
Trading Bot V0.2 is a production-ready cryptocurrency trading bot with adaptive strategy learning. The bot makes autonomous trading decisions based on hourly performance evaluation and currently manages a live Binance portfolio.
|
Trading Bot V0.2 is an adaptive cryptocurrency trading system running on Binance with:
|
||||||
|
- **Adaptive Strategy Learning** (Win Rate Tracking)
|
||||||
## Core Components
|
- **Risk Management** (Daily Loss Limit, Stop Loss, Take Profit, Trailing Stop)
|
||||||
|
- **Auto-Swap Feature** (Convert free coins to USDT)
|
||||||
### 1. Trading Engine (`src/main_ml.py`)
|
- **Real-time Dashboard** (FastAPI + Jinja2)
|
||||||
|
- **Telegram Integration** (3-hourly reports + alerts)
|
||||||
**Purpose:** Autonomous trading bot with risk management and adaptive strategy learning.
|
|
||||||
|
|
||||||
**Key Features:**
|
|
||||||
- **Signal Generation**: Random 5-10% probability per cycle (adapts based on win rate)
|
|
||||||
- **Position Management**: Max 1 position (scales to 2 in full-throttle mode)
|
|
||||||
- **Risk Controls**:
|
|
||||||
- Stop Loss: -1.0 to -2.2% (adaptive)
|
|
||||||
- Take Profit: +1.5 to +3.5% (adaptive)
|
|
||||||
- Daily Loss Limit: -5% (stops trading if exceeded)
|
|
||||||
- Cooldown: 30min after 3 consecutive losses
|
|
||||||
- **Adaptive Learning**: Evaluates win rate hourly, adjusts strategy (5 levels)
|
|
||||||
|
|
||||||
**Strategy Levels (based on Win Rate):**
|
|
||||||
|
|
||||||
| Level | WR | Signal | Investment | TP | SL | Max Trades |
|
|
||||||
|-------|----|----|-----------|----|----|------|
|
|
||||||
| Emergency | <45% | 5.0% | 50% | 1.5% | 1.0% | 5/day |
|
|
||||||
| Conservative | 45-50% | 6.5% | 50% | 2.2% | 1.5% | 10/day |
|
|
||||||
| Standard | 50-60% | 7.5% | 50% | 2.8% | 1.8% | 15/day |
|
|
||||||
| Aggressive | 60-70% | 8.5% | 55% | 3.2% | 2.0% | 20/day |
|
|
||||||
| Full Throttle | >70% | 10.0% | 55% | 3.5% | 2.2% | 25/day |
|
|
||||||
|
|
||||||
**Input/Output:**
|
|
||||||
- **Input**: Binance API (market data, account state, order status)
|
|
||||||
- **Output**: Market buy/sell orders, stop loss orders, Telegram alerts
|
|
||||||
|
|
||||||
**Run Cycle:** 5-second loop (async)
|
|
||||||
|
|
||||||
### 2. Dashboard (`src/web_dashboard.py`)
|
|
||||||
|
|
||||||
**Purpose:** Real-time portfolio monitoring and P&L display.
|
|
||||||
|
|
||||||
**Endpoints:**
|
|
||||||
- `/` (HTTP) — HTML dashboard
|
|
||||||
- `/api/state` (JSON) — Market data, holdings, P&L, strategy status
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- **Portfolio Metrics**: Total value, USDT free, locked positions
|
|
||||||
- **P&L Display**: Realized + unrealized, color-coded (green/red/neutral)
|
|
||||||
- **Live Prices**: Real-time cryptoommodity quotes
|
|
||||||
- **Holdings Table**: Asset balances with locked coin tracking
|
|
||||||
- **Strategy Status**: Current win rate, strategy mode, next adaptation time
|
|
||||||
|
|
||||||
**Refresh Rate:** 10 seconds (user-configurable)
|
|
||||||
|
|
||||||
**Tech Stack:**
|
|
||||||
- Framework: FastAPI
|
|
||||||
- Server: Uvicorn (async)
|
|
||||||
- Template: Jinja2 (server-side rendering)
|
|
||||||
- Port: 7000
|
|
||||||
|
|
||||||
## Data Flow
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────────┐
|
|
||||||
│ Binance API │
|
|
||||||
│ (Market Data, Account, Orders) │
|
|
||||||
└────────────────┬──────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌────────▼────────┐
|
|
||||||
│ Trading Bot │
|
|
||||||
│ (main_ml.py) │
|
|
||||||
│ │
|
|
||||||
│ • Signal Gen │
|
|
||||||
│ • Order Place │
|
|
||||||
│ • Risk Mgmt │
|
|
||||||
│ • Adaptive Learn│
|
|
||||||
└────────┬────────┘
|
|
||||||
│
|
|
||||||
┌────────▼────────┐
|
|
||||||
│ Dashboard │
|
|
||||||
│ (web_dashboard) │
|
|
||||||
│ │
|
|
||||||
│ • /api/state │
|
|
||||||
│ • HTML UI │
|
|
||||||
└────────┬────────┘
|
|
||||||
│
|
|
||||||
┌────────▼────────┐
|
|
||||||
│ User Interface │
|
|
||||||
│ (HTTP Browser) │
|
|
||||||
└─────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## Adaptive Learning Loop (Option 2)
|
|
||||||
|
|
||||||
**Evaluation Cycle:** Every hour
|
|
||||||
|
|
||||||
```
|
|
||||||
1. Calculate Win Rate
|
|
||||||
win_rate = total_wins / total_trades * 100
|
|
||||||
|
|
||||||
2. Compare to Thresholds
|
|
||||||
- <45% → Emergency mode
|
|
||||||
- 45-50% → Conservative
|
|
||||||
- 50-60% → Standard
|
|
||||||
- 60-70% → Aggressive
|
|
||||||
- >70% → Full Throttle
|
|
||||||
|
|
||||||
3. Update Parameters
|
|
||||||
- SIGNAL_THRESHOLD (5-10%)
|
|
||||||
- INVESTMENT_PERCENT (50-55%)
|
|
||||||
- TAKE_PROFIT_PERCENT (1.5-3.5%)
|
|
||||||
- STOP_LOSS_PERCENT (1.0-2.2%)
|
|
||||||
- MAX_TRADES_PER_DAY (5-25)
|
|
||||||
- MAX_OPEN_POSITIONS (1-2)
|
|
||||||
|
|
||||||
4. Send Notification
|
|
||||||
- Telegram alert with old↔new parameters
|
|
||||||
- Log strategy change
|
|
||||||
- Store strategy_version for tracking
|
|
||||||
```
|
|
||||||
|
|
||||||
**Minimum Trades to Adapt:** 5 (prevents noise in early phase)
|
|
||||||
|
|
||||||
## Performance Tracking
|
|
||||||
|
|
||||||
**Tracked Metrics:**
|
|
||||||
- `total_trades` — All trades ever executed
|
|
||||||
- `total_wins` — Winning trades (TP hit)
|
|
||||||
- `total_losses` — Losing trades (SL hit)
|
|
||||||
- `daily_pnl` — Today's profit/loss (resets daily)
|
|
||||||
- `trades_today` — Count reset daily at UTC 00:00
|
|
||||||
- `portfolio_value` — Current liquid value (real-time)
|
|
||||||
- `pnl_usdt` — Total P&L in USD
|
|
||||||
- `pnl_pct` — Total P&L in percentage
|
|
||||||
|
|
||||||
**Reporting:**
|
|
||||||
- 3-hour summaries via Telegram (win rate, P&L, status)
|
|
||||||
- Real-time alerts on strategy changes
|
|
||||||
- Dashboard updates every 10 seconds
|
|
||||||
|
|
||||||
## Security & Risk
|
|
||||||
|
|
||||||
**API Key Management:**
|
|
||||||
- Stored in `.env` file (never committed)
|
|
||||||
- API key requires `TRADING` permission on Binance
|
|
||||||
- All read/write operations over HTTPS (Binance)
|
|
||||||
|
|
||||||
**Order Validation:**
|
|
||||||
- Minimum notional: $5.00 per order
|
|
||||||
- Quantity rounded to Binance step size (using Decimal, no precision loss)
|
|
||||||
- Price rounded to Binance tick size
|
|
||||||
- Daily loss limit enforces hard stop at -5%
|
|
||||||
|
|
||||||
**Position Limits:**
|
|
||||||
- Max 1 position (standard) / 2 positions (full throttle)
|
|
||||||
- Max 3 consecutive losses → 30min cooldown
|
|
||||||
- No pyramid trading (one trade at a time)
|
|
||||||
|
|
||||||
## Deployment
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
- Python 3.10+
|
|
||||||
- Binance API key with SPOT trading permission
|
|
||||||
- Telegram bot token (for alerts)
|
|
||||||
|
|
||||||
**Installation:**
|
|
||||||
```bash
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
**Start Bot:**
|
|
||||||
```bash
|
|
||||||
python3 src/main_ml.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**Start Dashboard:**
|
|
||||||
```bash
|
|
||||||
uvicorn src/web_dashboard:app --host 0.0.0.0 --port 7000
|
|
||||||
```
|
|
||||||
|
|
||||||
**Access Dashboard:**
|
|
||||||
```
|
|
||||||
http://localhost:7000
|
|
||||||
```
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
BrainDock/
|
|
||||||
├── src/
|
|
||||||
│ ├── __init__.py (Package marker)
|
|
||||||
│ ├── main_ml.py (Trading bot engine - 512 lines)
|
|
||||||
│ └── web_dashboard.py (Dashboard API - 650+ lines)
|
|
||||||
├── README.md (User documentation)
|
|
||||||
├── ARCHITECTURE.md (This file)
|
|
||||||
├── requirements.txt (Python dependencies)
|
|
||||||
└── .gitignore (Git exclusions)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Future Enhancements
|
|
||||||
|
|
||||||
**Phase 2: Machine Learning**
|
|
||||||
- Train model on historical OHLCV data
|
|
||||||
- Replace random signal with ML probability
|
|
||||||
- Feature engineering: RSI, MACD, Bollinger Bands, etc.
|
|
||||||
|
|
||||||
**Phase 3: Portfolio Optimization**
|
|
||||||
- Multi-pair trading (BTC, ETH, SOL, BNB, XRP)
|
|
||||||
- Dynamic position sizing by Sharpe ratio
|
|
||||||
- Kelly Criterion for capital allocation
|
|
||||||
|
|
||||||
**Phase 4: Advanced Risk**
|
|
||||||
- Correlation-based hedging
|
|
||||||
- Volatility clustering detection
|
|
||||||
- Dynamic stop loss based on ATR
|
|
||||||
|
|
||||||
## Monitoring & Debugging
|
|
||||||
|
|
||||||
**Logs:**
|
|
||||||
```bash
|
|
||||||
journalctl -u trading-bot.service -f # Real-time logs
|
|
||||||
```
|
|
||||||
|
|
||||||
**API Health Check:**
|
|
||||||
```bash
|
|
||||||
curl http://localhost:7000/api/state | jq .
|
|
||||||
```
|
|
||||||
|
|
||||||
**Database State:**
|
|
||||||
- No persistent database; all state in-memory
|
|
||||||
- Recovery from Binance API on bot restart
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Last Updated:** 2026-07-07
|
## Architecture Diagram
|
||||||
**Version:** V0.2
|
|
||||||
**Status:** Production Ready ✅
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ TRADING BOT V0.2 │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ Core Trading Engine (main_ml.py) │ │
|
||||||
|
│ │ • Adaptive strategy (5 levels: Emergency→Full Throttle)│ │
|
||||||
|
│ │ • Risk management (SL -1.8%, TP +2.8%, Daily -5%) │ │
|
||||||
|
│ │ • Position tracking & P&L calculation │ │
|
||||||
|
│ │ • Win rate analysis (hourly evaluation) │ │
|
||||||
|
│ └──────────────────────────────────────────────────────┘ │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│ ┌────────▼──────────┐ ┌──────────────▼──────┐ │
|
||||||
|
│ │ Binance API │ │ Auto-Swap Module │ │
|
||||||
|
│ │ • Place orders │ │ • Convert free │ │
|
||||||
|
│ │ • Monitor fills │ │ coins → USDT │ │
|
||||||
|
│ │ • Get balances │ │ • Skip-list logic │ │
|
||||||
|
│ │ • Track trades │ │ • Telegram notify │ │
|
||||||
|
│ └───────────────────┘ └─────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌────────▼──────────────────────────────────────────────┐ │
|
||||||
|
│ │ Dashboard (web_dashboard.py) │ │
|
||||||
|
│ │ • Real-time portfolio value & P&L │ │
|
||||||
|
│ │ • Holdings summary (locked/free breakdown) │ │
|
||||||
|
│ │ • Active positions & open orders │ │
|
||||||
|
│ │ • Strategy status & performance metrics │ │
|
||||||
|
│ │ FastAPI (port 7000) + Jinja2 templates │ │
|
||||||
|
│ └────────────────────────────────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ┌────────▼──────────────────────────────────────────────┐ │
|
||||||
|
│ │ Telegram Integration │ │
|
||||||
|
│ │ • 3-hour performance reports │ │
|
||||||
|
│ │ • Trade execution alerts │ │
|
||||||
|
│ │ • Error notifications │ │
|
||||||
|
│ │ • Swap completion confirmations │ │
|
||||||
|
│ └────────────────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Components
|
||||||
|
|
||||||
|
### 1. Trading Engine (src/main_ml.py)
|
||||||
|
|
||||||
|
**Main Class:** `TradingBot`
|
||||||
|
|
||||||
|
#### Strategy Parameters
|
||||||
|
```python
|
||||||
|
PAIRS = ['BTCUSDT', 'ETHUSDT', 'SOLUSDT', 'BNBUSDT', 'XRPUSDT']
|
||||||
|
STOP_LOSS_PERCENT = 1.8 # -1.8%
|
||||||
|
TAKE_PROFIT_PERCENT = 2.8 # +2.8%
|
||||||
|
DAILY_LOSS_LIMIT = -5 # Pause after -5%
|
||||||
|
MAX_POSITIONS = 1 # Single position
|
||||||
|
INVESTMENT_PERCENT = 50-55% # Per trade
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Adaptive Learning (Option 2: Win Rate Tracking)
|
||||||
|
```
|
||||||
|
Win Rate < 45% → Emergency Level (minimal trading)
|
||||||
|
45-50% → Conservative Level
|
||||||
|
50-60% → Standard Level (base)
|
||||||
|
60-70% → Aggressive Level
|
||||||
|
> 70% → Full Throttle Level
|
||||||
|
|
||||||
|
Adjustments per level:
|
||||||
|
• Signal threshold (5.0% → 10.0%)
|
||||||
|
• Investment (50% → 55%)
|
||||||
|
• Take profit (1.5% → 3.5%)
|
||||||
|
• Stop loss (1.0% → 2.2%)
|
||||||
|
• Max trades/day (5 → 25)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Key Methods
|
||||||
|
|
||||||
|
| Method | Purpose |
|
||||||
|
|--------|---------|
|
||||||
|
| `run_cycle()` | Main trading loop (every ~10s) |
|
||||||
|
| `evaluate_signal()` | Generate trading signal (7.5% base prob) |
|
||||||
|
| `place_trade()` | Execute buy order with SL/TP |
|
||||||
|
| `check_positions()` | Monitor open trades, close on SL/TP |
|
||||||
|
| `calculate_pnl()` | Compute portfolio P&L (live + closed) |
|
||||||
|
| `update_adaptive_strategy()` | Hourly win rate evaluation |
|
||||||
|
| `swap_coins_to_usdt()` | **NEW:** Convert free coins to USDT |
|
||||||
|
| `get_usdt_balance()` | **NEW:** Query current USDT balance |
|
||||||
|
| `send_performance_report()` | 3-hour Telegram summary |
|
||||||
|
|
||||||
|
#### Risk Management
|
||||||
|
|
||||||
|
**Daily Loss Limit:**
|
||||||
|
- If P&L <= -5%, bot pauses trading
|
||||||
|
- Resets at UTC 00:00
|
||||||
|
- Prevents catastrophic drawdowns
|
||||||
|
|
||||||
|
**Stop Loss & Take Profit:**
|
||||||
|
- SL -1.8% per trade (position auto-closed)
|
||||||
|
- TP +2.8% per trade (position auto-closed)
|
||||||
|
- OR Trailing Stop: +1.5% entry, 0.6% trail
|
||||||
|
|
||||||
|
**Consecutive Loss Cooldown:**
|
||||||
|
- After 3 consecutive losses: 30min pause
|
||||||
|
- Prevents emotional spiraling
|
||||||
|
|
||||||
|
**Position Limits:**
|
||||||
|
- Max 1 open position at a time
|
||||||
|
- Prevents over-leverage
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Auto-Swap Feature (NEW - 2026-07-08)
|
||||||
|
|
||||||
|
**Function:** `swap_coins_to_usdt()`
|
||||||
|
**Lines:** 387-461 in main_ml.py
|
||||||
|
|
||||||
|
**Purpose:** Automatically convert all free (unlocked) coins to USDT
|
||||||
|
|
||||||
|
**Logic:**
|
||||||
|
```python
|
||||||
|
1. Get account balance via Binance API
|
||||||
|
2. For each coin:
|
||||||
|
- Skip if: USDT, LDBTTC, LDDOGE, USDC, locked, dust (<0.00001)
|
||||||
|
- Get current price (COINUSDT pair)
|
||||||
|
- Round quantity to Binance step size
|
||||||
|
- Execute MARKET SELL
|
||||||
|
- Calculate USDT received
|
||||||
|
3. Send Telegram notification with results
|
||||||
|
4. Return total USDT acquired
|
||||||
|
```
|
||||||
|
|
||||||
|
**Skip-List (Never Swap):**
|
||||||
|
- USDT (target currency)
|
||||||
|
- LDBTTC (fake/scam token)
|
||||||
|
- LDDOGE (shitcoin)
|
||||||
|
- USDC (too small)
|
||||||
|
- Any coin marked as locked (in active trades)
|
||||||
|
|
||||||
|
**Execution Result (2026-07-08 23:28 UTC):**
|
||||||
|
| Coin | Qty | USDT | Status |
|
||||||
|
|------|-----|------|--------|
|
||||||
|
| BNB | 0.019 | $10.75 | ✅ |
|
||||||
|
| XRP | 28.7 | $31.20 | ✅ |
|
||||||
|
| SOL | 0.294 | $22.67 | ✅ |
|
||||||
|
| **TOTAL** | — | **+$64.61** | ✅ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Dashboard (src/web_dashboard.py)
|
||||||
|
|
||||||
|
**Framework:** FastAPI + Jinja2
|
||||||
|
**Port:** 7000
|
||||||
|
**Refresh:** 10 seconds (live updates)
|
||||||
|
|
||||||
|
**Endpoints:**
|
||||||
|
| Endpoint | Purpose |
|
||||||
|
|----------|---------|
|
||||||
|
| `GET /` | Render main dashboard HTML |
|
||||||
|
| `GET /api/state` | JSON: portfolio, P&L, holdings, orders |
|
||||||
|
|
||||||
|
**Dashboard Sections:**
|
||||||
|
1. **Header:** Bot status (🟢 RUNNING or ⏸️ PAUSED)
|
||||||
|
2. **Portfolio Kachel:** USDT value, P&L %, color-coded
|
||||||
|
3. **Holdings (Collapsible):** All coins + USD values
|
||||||
|
4. **Live Prices (Collapsible):** Real-time BTCUSDT, ETHUSDT, etc.
|
||||||
|
5. **Active Positions:** Current open trades (entry price, SL, TP)
|
||||||
|
|
||||||
|
**Design:**
|
||||||
|
- Colors: Grayscale (#1e1e1e bg, #d0d0d0 text)
|
||||||
|
- Accent: Green (#00ff88) ONLY for Portfolio & USDT values
|
||||||
|
- Responsive, collapsible sections (both collapsed on load)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
### Trading Cycle (run_cycle)
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ 1. Get current portfolio balance & P&L │
|
||||||
|
│ 2. Check if -5% daily limit reached → PAUSE if true │
|
||||||
|
│ 3. Check all open positions for SL/TP exit │
|
||||||
|
│ 4. Evaluate signal (7.5% base probability) │
|
||||||
|
│ 5. If signal + capital > $5: Place trade │
|
||||||
|
│ 6. Update adaptive strategy (hourly) │
|
||||||
|
│ 7. Send Telegram report (if 3h elapsed) │
|
||||||
|
│ 8. Repeat every ~10s │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### P&L Calculation
|
||||||
|
```
|
||||||
|
Portfolio Value = Balance(USDT) + Sum(Coin Value in USDT)
|
||||||
|
|
||||||
|
P&L USDT = Portfolio Value - Initial Capital ($137.79)
|
||||||
|
|
||||||
|
P&L % = (P&L USDT / Initial Capital) × 100
|
||||||
|
|
||||||
|
Status = 🟢 GREEN if P&L > 0, 🔴 RED if P&L < 0
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Environment (.env)
|
||||||
|
```
|
||||||
|
BINANCE_API_KEY_LIVE=...
|
||||||
|
BINANCE_API_SECRET_LIVE=...
|
||||||
|
TELEGRAM_BOT_TOKEN=...
|
||||||
|
TELEGRAM_CHAT_ID=7646180954
|
||||||
|
```
|
||||||
|
|
||||||
|
### In Code (main_ml.py Line ~30-60)
|
||||||
|
```python
|
||||||
|
PAIRS = ['BTCUSDT', 'ETHUSDT', 'SOLUSDT', 'BNBUSDT', 'XRPUSDT']
|
||||||
|
SIGNAL_THRESHOLD = 7.5 # 7.5% signal probability
|
||||||
|
INVESTMENT_PERCENT = 50 # 50% of capital per trade
|
||||||
|
STOP_LOSS_PERCENT = 1.8 # -1.8% SL
|
||||||
|
TAKE_PROFIT_PERCENT = 2.8 # +2.8% TP
|
||||||
|
DAILY_LOSS_LIMIT = -5 # -5% pause threshold
|
||||||
|
MAX_OPEN_POSITIONS = 1
|
||||||
|
MAX_CONSECUTIVE_LOSSES = 3
|
||||||
|
CONSECUTIVE_LOSS_COOLDOWN = 30 * 60 # 30 minutes
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
### SystemD Service
|
||||||
|
```
|
||||||
|
Service: trading-bot.service
|
||||||
|
File: /etc/systemd/system/trading-bot.service
|
||||||
|
User: root
|
||||||
|
WorkDir: /home/marc/bot-deploy
|
||||||
|
Exec: python3 /home/marc/bot-deploy/src/main_ml.py
|
||||||
|
AutoStart: yes
|
||||||
|
```
|
||||||
|
|
||||||
|
### Start/Stop
|
||||||
|
```bash
|
||||||
|
sudo systemctl start trading-bot.service
|
||||||
|
sudo systemctl stop trading-bot.service
|
||||||
|
sudo systemctl restart trading-bot.service
|
||||||
|
sudo systemctl status trading-bot.service
|
||||||
|
```
|
||||||
|
|
||||||
|
### Logs
|
||||||
|
```bash
|
||||||
|
journalctl -u trading-bot.service -f # Live tail
|
||||||
|
journalctl -u trading-bot.service -n 50 # Last 50 lines
|
||||||
|
journalctl -u trading-bot.service --since "1 hour ago"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Git Repository
|
||||||
|
|
||||||
|
**URL:** ssh://git@172.16.1.168:222/marc/BrainDock.git
|
||||||
|
**Branch:** master
|
||||||
|
**Latest:** Commit ae15976 (Auto-Swap Feature)
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```
|
||||||
|
BrainDock/
|
||||||
|
├── src/
|
||||||
|
│ ├── main_ml.py # Core trading engine (V0.2)
|
||||||
|
│ ├── web_dashboard.py # FastAPI dashboard
|
||||||
|
│ └── __init__.py
|
||||||
|
├── docs/
|
||||||
|
│ └── ARCHITECTURE.md # This file
|
||||||
|
├── README.md # User-facing features
|
||||||
|
├── requirements.txt # Dependencies
|
||||||
|
├── .gitignore # Excludes: __pycache__, *.log, .env, venv/
|
||||||
|
└── ARCHITECTURE.md # System design (this repo)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auto-Sync Cron:**
|
||||||
|
```
|
||||||
|
# Every 5 minutes, auto-commit changes from /home/marc/bot-deploy/src → BrainDock/src
|
||||||
|
*/5 * * * * git -C /home/marc/bot-versions/BrainDock add src/ && git commit -m "Auto-sync: $(date)" && git push origin master 2>/dev/null || true
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Monitoring & Alerts
|
||||||
|
|
||||||
|
### Telegram Reports
|
||||||
|
- **Frequency:** Every 3 hours
|
||||||
|
- **Content:**
|
||||||
|
- Portfolio value + P&L
|
||||||
|
- Trades executed today (wins/losses)
|
||||||
|
- Current strategy level
|
||||||
|
- Bot status (running/paused)
|
||||||
|
|
||||||
|
### Manual Commands (Python)
|
||||||
|
```python
|
||||||
|
bot = TradingBot()
|
||||||
|
|
||||||
|
# Get current P&L
|
||||||
|
report = bot.get_performance_report()
|
||||||
|
print(report['portfolio'], report['pnl_usdt'], report['pnl_pct'])
|
||||||
|
|
||||||
|
# Swap all free coins to USDT
|
||||||
|
result = bot.swap_coins_to_usdt()
|
||||||
|
print(f"Converted: ${result['total_usdt_acquired']:.2f}")
|
||||||
|
|
||||||
|
# Get USDT balance
|
||||||
|
usdt = bot.get_usdt_balance()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known Limitations & Future Work
|
||||||
|
|
||||||
|
### Current Limitations
|
||||||
|
- **Signal:** Still random (7.5% base probability), not ML-based
|
||||||
|
- **Pairs:** Fixed list (5 pairs), not dynamic
|
||||||
|
- **Levels:** 5 strategy levels (can expand)
|
||||||
|
- **Fees:** No explicit fee tracking (implicit in P&L)
|
||||||
|
|
||||||
|
### Future Enhancements
|
||||||
|
- [ ] Machine Learning signal (instead of random)
|
||||||
|
- [ ] Dynamic pair selection (trending symbols only)
|
||||||
|
- [ ] Advanced technical indicators (RSI, MACD, etc.)
|
||||||
|
- [ ] Portfolio rebalancing scheduler
|
||||||
|
- [ ] Webhook API for external signals
|
||||||
|
- [ ] Database logging (trade history, performance metrics)
|
||||||
|
- [ ] Mobile alerts (SMS, Push notifications)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Bot Not Trading (1-hour+ no activity)
|
||||||
|
1. Check daily P&L: `curl http://localhost:7000/api/state | jq '.pnl_pct'`
|
||||||
|
2. If P&L < -5%, bot is paused (wait until UTC 00:00)
|
||||||
|
3. Check logs: `journalctl -u trading-bot.service -n 50`
|
||||||
|
|
||||||
|
### Dashboard Shows $0.00
|
||||||
|
- Rare bug (fixed 2026-07-08)
|
||||||
|
- Restart: `sudo systemctl restart trading-bot.service`
|
||||||
|
|
||||||
|
### High Number of Rejected Orders
|
||||||
|
- **Cause:** USDT balance too low (< $5 per order)
|
||||||
|
- **Fix:** Use `bot.swap_coins_to_usdt()` to convert free coins
|
||||||
|
|
||||||
|
### Telegram Notifications Not Arriving
|
||||||
|
- Check API keys in .env
|
||||||
|
- Verify Telegram chat ID: `curl "https://api.telegram.org/bot{TOKEN}/getMe"`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
| Version | Date | Changes |
|
||||||
|
|---------|------|---------|
|
||||||
|
| V0.2 | 2026-07-08 | ✅ Live: Adaptive Learning + Auto-Swap Feature |
|
||||||
|
| V5 | (Previous) | Archived (manual strategy, no learning) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Maintained by:** Hermes Agent
|
||||||
|
**Last Review:** 2026-07-08 23:35 UTC
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue