From 138cf018d2516e8076a32d921c7e95761ef2f7dd Mon Sep 17 00:00:00 2001
From: Marc Blatter <marc@braindock.local>
Date: Wed, 8 Jul 2026 23:32:49 +0200
Subject: [PATCH] Docs: Add comprehensive ARCHITECTURE.md - Auto-Swap feature,
 Risk Management, Components documented

---
 ARCHITECTURE.md | 609 ++++++++++++++++++++++++++++++------------------
 1 file changed, 378 insertions(+), 231 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index df2314e..ebe7851 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1,238 +1,385 @@
 # 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 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.
-
-## Core Components
-
-### 1. Trading Engine (`src/main_ml.py`)
-
-**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
+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)
 
 ---
 
-**Last Updated:** 2026-07-07  
-**Version:** V0.2  
-**Status:** Production Ready ✅
+## 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