# Trading Bot V0.2 — System Architecture

**Version:** 0.2 (Production)  
**Last Updated:** 2026-07-08  
**Status:** 🟢 LIVE with Auto-Swap Feature

## Overview

Trading Bot V0.2 is an adaptive cryptocurrency trading system running on Binance with:
- **Adaptive Strategy Learning** (Win Rate Tracking)
- **Risk Management** (Daily Loss Limit, Stop Loss, Take Profit, Trailing Stop)
- **Auto-Swap Feature** (Convert free coins to USDT)
- **Real-time Dashboard** (FastAPI + Jinja2)
- **Telegram Integration** (3-hourly reports + alerts)

---

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                    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