marc
/
BrainDock
Template
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BrainDock/ARCHITECTURE.md

14 KiB
Raw Blame History

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

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:

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)

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

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

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)

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