LLM-TradeBot

LLM-TradeBot

A multi-agent AI trading system using LLMs to optimize strategies and adapt to market conditions in real-time.

Stars: 174

Visit
 screenshot

LLM-TradeBot is an Intelligent Multi-Agent Quantitative Trading Bot based on the Adversarial Decision Framework (ADF). It achieves high win rates and low drawdown in automated futures trading through market regime detection, price position awareness, dynamic score calibration, and multi-layer physical auditing. The bot prioritizes judging 'IF we should trade' before deciding 'HOW to trade' and offers features like multi-agent collaboration, agent configuration, agent chatroom, AUTO1 symbol selection, multi-LLM support, multi-account trading, async concurrency, CLI headless mode, test/live mode toggle, safety mechanisms, and full-link auditing. The system architecture includes a multi-agent architecture with various agents responsible for different tasks, a four-layer strategy filter, and detailed data flow diagrams. The bot also supports backtesting, full-link data auditing, and safety warnings for users.

README:

๐Ÿค– LLM-TradeBot

English ็ฎ€ไฝ“ไธญๆ–‡

Adversarial Intelligence Framework

Intelligent Multi-Agent Quantitative Trading Bot based on the Adversarial Decision Framework (ADF). Achieves high win rates and low drawdown in automated futures trading through market regime detection, price position awareness, dynamic score calibration, and multi-layer physical auditing.

Python License Framework X Follow


๐ŸŒ Web App (Recommended)

Experience the bot immediately through our web interface: ๐Ÿ‘‰ Live Dashboard

Dashboard Highlights

  • LLM toggle stays off by default; turning it on prompts for an API key.
  • Agent Chatroom shows per-cycle agent outputs and the final Decision Core action.
  • Real-time Balance Curve uses a fixed initial balance and PnL-driven current balance.
  • Agent Config lets you edit per-agent parameters and (if applicable) system prompts.

โœจ Key Features

  • ๐Ÿ•ต๏ธ Perception First: Unlike strict indicator-based systems, this framework prioritizes judging "IF we should trade" before deciding "HOW to trade".
  • ๐Ÿค– Multi-Agent Collaboration: Core + optional agents with LLM and Local variants for flexible deployment.
  • ๐ŸŽ›๏ธ Agent Configuration: Enable/disable optional agents via Dashboard, environment variables, or config file for customized strategy.
  • ๐Ÿ’ฌ Agent Chatroom: Chat-style multi-agent outputs per cycle, with Decision Core final decisioning.
  • ๐Ÿงฉ Agent Config Tabs: Configure per-agent parameters and optional system prompts directly in the Dashboard.
  • ๐ŸŽฐ AUTO1 Symbol Selection: Intelligent single-symbol selection based on momentum, volume, and technical indicators.
  • ๐Ÿง  Multi-LLM Support: Seamlessly switch between DeepSeek, OpenAI, Claude, Qwen, and Gemini via Dashboard settings.
  • ๐Ÿ“Š Multi-Account Trading: Manage multiple exchange accounts with unified API abstraction (currently Binance, extensible).
  • โšก Async Concurrency: Currently fetches multi-timeframe data (5m/15m/1h) concurrently, ensuring data alignment at the snapshot moment.
  • ๐Ÿ–ฅ๏ธ CLI Headless Mode: Run without Web UI for headless servers - rich terminal output with 93% less log verbosity.
  • ๐Ÿงช๐Ÿ’ฐ Test/Live Mode Toggle: Quick switch between paper trading and live trading with visual confirmation.
  • ๐Ÿ›ก๏ธ Safety First: Stop-loss direction correction, capital pre-rehearsal, and veto mechanisms to safeguard live trading.
  • ๐Ÿ“Š Full-Link Auditing: Every decision's adversarial process and confidence penalty details are recorded, achieving true "White-Box" decision-making.

๐Ÿ—๏ธ System Architecture Overview

Multi-Agent Architecture (Current)

flowchart TD
  A["๐ŸŽฏ Symbol Selector"] --> B["๐Ÿ•ต๏ธ DataSync (5m/15m/1h)"]
  B --> C["๐Ÿ‘จโ€๐Ÿ”ฌ Quant Analyst"]
  C --> D["๐Ÿงญ Multi-Period Parser"]
  C --> E["๐Ÿ”ฎ Trend / ๐Ÿ“Š Setup / โšก Trigger (LLM or Local)"]
  C --> F["๐Ÿชž Reflection (optional)"]
  D --> G["โš–๏ธ Decision Core"]
  E --> G
  F --> G
  G --> H["๐Ÿ›ก๏ธ Risk Audit"]
  H --> I["๐Ÿš€ Execution Engine"]

Design highlights

  1. Symbol Selection chooses the active symbol(s) before analysis.
  2. DataSync aligns multi-timeframe data at the same snapshot moment.
  3. Quant Analyst produces numeric signals (trend/osc/sentiment/traps).
  4. Semantic Agents (Trend/Setup/Trigger) provide human-readable reasoning (LLM or local).
  5. Multi-Period Parser compresses 1h/15m/5m alignment into a Decision Core input.
  6. Decision Core fuses all enabled agent outputs into final action/confidence.
  7. Risk Audit can veto or adjust before execution.
  8. Reflection summarizes performance and feeds back into decisions.

๐Ÿ“– Detailed Docs: See Data Flow Analysis for complete mechanisms.


๐Ÿค Supported Ecosystem

Supported Exchanges

CEX (Centralized Exchanges)

Exchange Status Register (Fee Discount)
Binance โœ… Supported Register
Bybit ๐Ÿ—“๏ธ Coming Soon Register
OKX ๐Ÿ—“๏ธ Coming Soon Register
Bitget ๐Ÿ—“๏ธ Coming Soon Register

Perp-DEX (Decentralized Perpetual Exchanges)

Exchange Status Register (Fee Discount)
Hyperliquid ๐Ÿ—“๏ธ Coming Soon Register
Aster DEX ๐Ÿ—“๏ธ Coming Soon Register
Lighter ๐Ÿ—“๏ธ Coming Soon Register

Supported AI Models

AI Model Status Get API Key
DeepSeek โœ… Supported Get API Key
Qwen โœ… Supported Get API Key
OpenAI (GPT) โœ… Supported Get API Key
Claude โœ… Supported Get API Key
Gemini โœ… Supported Get API Key
Grok ๐Ÿ—“๏ธ Coming Soon Get API Key
Kimi ๐Ÿ—“๏ธ Coming Soon Get API Key

๐Ÿ“š What You Need to Know

For Complete Beginners:

  • This is an automated trading bot that trades cryptocurrency futures on Binance
  • It uses AI (LLM) and machine learning to make trading decisions
  • Test mode lets you practice with virtual money before risking real funds
  • The bot runs 24/7 and makes decisions based on market analysis

Technical Level: Intermediate Python knowledge recommended but not required for basic usage.


๐Ÿš€ Quick Start (One-Click Installation)

๐ŸŽฏ Recommended: One-Click Installation

No need to manually configure Python environment! Use our automated installation scripts:

Method 1: Local Installation (Development)

# 1. Clone the project
git clone <your-repo-url>
cd LLM-TradeBot

# 2. One-click install
chmod +x install.sh
./install.sh

# 3. Configure API keys
vim .env  # Edit and add your API keys

# 4. One-click start
./start.sh

Visit Dashboard: http://localhost:8000

Method 2: Docker Deployment (Production)

# 1. Clone the project
git clone <your-repo-url>
cd LLM-TradeBot

# 2. Configure environment
cp .env.example .env
vim .env  # Edit and add your API keys

# 3. One-click start
cd docker && docker-compose up -d

๐Ÿ“– Detailed Guide: See QUICKSTART.md


โš™๏ธ Prerequisites

Before you start, make sure you have:

For One-Click Installation (Recommended)

  • โœ… Git installed (Download here)
  • โœ… Python 3.11+ OR Docker (installation script will check)

For Test Mode (Beginners)

  • โœ… Nothing else needed! Test mode uses virtual balance

For Live Trading (Advanced)

  • โœ… Binance Account (Sign up here)
  • โœ… Binance Futures API Keys with trading permissions
  • โœ… USDT in Futures Wallet (minimum $100 recommended)
  • โš ๏ธ Risk Warning: Only trade with money you can afford to lose

๐Ÿง  LLM Configuration (Multi-Provider Support)

The bot supports 8 LLM providers. Configure via environment variables or Dashboard Settings:

Supported Providers

Provider Model Cost Speed Get API Key
DeepSeek (Recommended) deepseek-chat ๐Ÿ’ฐ Low โšก Fast platform.deepseek.com
OpenAI gpt-4o, gpt-4o-mini ๐Ÿ’ฐ๐Ÿ’ฐ๐Ÿ’ฐ High โšก Fast platform.openai.com
Claude claude-3-5-sonnet ๐Ÿ’ฐ๐Ÿ’ฐ Medium โšก Fast console.anthropic.com
Qwen qwen-turbo, qwen-plus ๐Ÿ’ฐ Low โšก Fast dashscope.console.aliyun.com
Gemini gemini-1.5-pro ๐Ÿ’ฐ Low โšก Fast aistudio.google.com
Kimi moonshot-v1-8k ๐Ÿ’ฐ Low โšก Fast platform.moonshot.ai
MiniMax MiniMax-M2.1 ๐Ÿ’ฐ Low โšก Fast platform.minimax.io
GLM glm-4-flash ๐Ÿ’ฐ Low โšก Fast open.bigmodel.cn

Configuration Methods

Method 1: Environment Variables (Recommended)

Edit your .env file:

# Select LLM Provider (required)
LLM_PROVIDER=deepseek  # Options: deepseek, openai, claude, qwen, gemini, kimi, minimax, glm

# Configure API Key for your selected provider
DEEPSEEK_API_KEY=sk-xxx     # if using DeepSeek
OPENAI_API_KEY=sk-xxx       # if using OpenAI
CLAUDE_API_KEY=sk-xxx       # if using Claude
QWEN_API_KEY=sk-xxx         # if using Qwen
GEMINI_API_KEY=xxx          # if using Gemini
KIMI_API_KEY=sk-xxx         # if using Kimi
MINIMAX_API_KEY=sk-xxx      # if using MiniMax
GLM_API_KEY=sk-xxx          # if using GLM

Method 2: Dashboard Settings

  1. Open Dashboard at http://localhost:8000
  2. Click โš™๏ธ Settings โ†’ API Keys tab
  3. Select your preferred LLM provider and enter API key
  4. Click Save - changes apply on next trading cycle

Method 3: Config File (config.yaml)

llm:
  provider: "deepseek"  # or: openai, claude, qwen, gemini, kimi, minimax, glm
  model: "deepseek-chat"  # provider-specific model
  temperature: 0.3
  max_tokens: 2000
  api_keys:
    deepseek: "sk-xxx"
    openai: "sk-xxx"
    # ... other providers

๐Ÿ“– Manual Installation (Advanced)

If you prefer manual setup:

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

# Copy environment variable template
cp .env.example .env

# Set API Keys
./set_api_keys.sh

3. Configure Trading Parameters

# Copy config template
cp config.example.yaml config.yaml

Edit config.yaml to set parameters:

  • Trading pair (symbol)
  • Max position size (max_position_size)
  • Leverage (leverage)
  • Stop loss/Take profit % (stop_loss_pct, take_profit_pct)

โš™๏ธ Dashboard Settings

You can also configure all settings from the Dashboard:

Settings Modal with 4 tabs: API Keys (LLM Provider), Accounts (Multi-Account), Trading, Strategy (Prompt)

4. Start the Bot

Built-in modern real-time monitoring dashboard.

๐Ÿงช Test Mode (Recommended for beginners)

Simulates trading with virtual balance ($1000). No real trades executed.

# Start with test mode
python main.py --test --mode continuous

๐Ÿ–ฅ๏ธ CLI Headless Mode (For Servers)

Run the bot without Web Dashboard, perfect for headless servers or terminal-only environments.

# Basic CLI mode (manual start required)
python main.py --test --headless

# Custom interval (1 minute cycles)
python main.py --test --headless --interval 1

Features:

  • โœ… No Web UI - runs entirely in terminal
  • โœ… Rich formatted output with colors and tables
  • โœ… Real-time price updates and trading decisions
  • โœ… Account summary panel after each cycle
  • โœ… Graceful shutdown with session statistics (Ctrl+C)
  • โœ… Optimized log output (93% less verbose than Web mode)

Output Example:

โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
โ•‘ ๐Ÿค– LLM-TradeBot CLI - TEST MODE                      โ•‘
โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Cycle #1 | LINKUSDT, NEARUSDT โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
  ๐Ÿ” Analyzing LINKUSDT...
  โœ… Data ready: $13.29
  
  โธ๏ธ  HOLD | Confidence: 45.0%
     Reason: No clear 1h trend

โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Account Summary โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ ๐Ÿ’ฐ Equity:    $1,000.00                           โ”‚
โ”‚ ๐Ÿ“Š Available:   $900.00                           โ”‚
โ”‚ ๐Ÿ“ˆ PnL:          $0.00 (0.00%)                    โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

  โณ Next cycle in 1.0 minutes...

๐Ÿš€ Simplified CLI Mode (Live Trading)

For production live trading, use the simplified CLI script that skips non-essential components:

# Activate virtual environment first
source venv/bin/activate

# Test mode - single run
python simple_cli.py --mode once

# Test mode - continuous (3-minute intervals)
python simple_cli.py --mode continuous --interval 3

# LIVE mode - continuous trading (โš ๏ธ REAL MONEY)
python simple_cli.py --mode continuous --interval 3 --live

# Custom symbols (overrides .env)
python simple_cli.py --mode continuous --symbols BTCUSDT,ETHUSDT --live

# AUTO3 mode - automatic symbol selection
python simple_cli.py --mode continuous --symbols AUTO3 --live

Features:

  • โœ… Minimal footprint - only core trading components loaded
  • โœ… Production-ready - designed for stable 24/7 operation
  • โœ… AUTO3 support - automatic best symbol selection via backtest
  • โœ… LLM integration - full multi-agent decision system
  • โœ… Risk management - built-in risk audit and position limits
  • โœ… Graceful shutdown - Ctrl+C for clean exit

Configuration:

The script reads trading symbols from .env file by default:

# In your .env file
TRADING_SYMBOLS=BTCUSDT,ETHUSDT
# Or use AUTO3 for automatic selection
TRADING_SYMBOLS=AUTO3

โš ๏ธ Live Trading Prerequisites:

  • Valid Binance Futures API keys in .env
  • Sufficient USDT balance in Futures wallet
  • API permissions: Read + Futures Trading enabled
  • DeepSeek/OpenAI API key for LLM decisions

๐Ÿ”ด Live Trading Mode (Web Dashboard)

โš ๏ธ WARNING: Executes real trades on Binance Futures!

# Start live trading
python main.py --mode continuous

Prerequisites for Live Trading:

  • Valid Binance Futures API keys configured in .env
  • Sufficient USDT balance in Futures wallet
  • API permissions: Read + Futures Trading enabled

After startup, visit: http://localhost:8000 (or use our Cloud Hosting)

Dashboard Features:

  • Dashboard Preview

  • ๐Ÿงช๐Ÿ’ฐ Test/Live Mode Toggle: Quick switch between paper trading and real trading with visual confirmation

  • ๐Ÿ“ˆ Real-time Balance Curve: Fixed initial balance with PnL-driven current balance

  • ๐Ÿ’ฌ Agent Chatroom: Per-cycle multi-agent outputs with Decision Core final action

  • ๐Ÿงญ Multi-Period Summary: Alignment snapshot from 1h/15m/5m signals

  • ๐Ÿงฉ Agent Config Tabs: Per-agent parameters + optional system prompts

  • ๐Ÿ“œ Trade History: Complete record of all trades with Open/Close cycles and PnL statistics

  • ๐Ÿ“‹ Live Log Output: Real-time scrolling logs with agent documentation sidebar, simplified/detailed mode toggle

๐Ÿ“‹ Recent Decisions Indicator Guide

All indicators use semantic icons and two-line display format for quick visual scanning:

๐Ÿ“Š System Columns

  • Time: Decision timestamp
  • Cycle: Trading cycle number
  • Symbol: Trading pair (e.g., BTCUSDT)

โš–๏ธ Critic (Decision Core)

  • Result: Final action (LONG/SHORT/WAIT)
  • Conf: Decision confidence (0-100%)
  • Reason: Decision rationale (hover for full text)

๐Ÿ‘จโ€๐Ÿ”ฌ Strategist (Quant Analysis)

  • 1h/15m/5m: Multi-timeframe signals
    • Format: T:UP (Trend) / O:DN (Oscillator)
    • Colors: Green (UP), Red (DN), Gray (NEU)
  • Sent: Sentiment score with icon (๐Ÿ“ˆ/๐Ÿ“‰/โž–)

๐Ÿ”ฎ Prophet (ML Prediction)

  • Format: ๐Ÿ”ฎโ†— + 65%
  • Direction: โ†—UP (>55%), โž–NEU (45-55%), โ†˜DN (<45%)

๐Ÿ‚๐Ÿป Bull/Bear (Adversarial Analysis)

  • Bull: โ†—Bull / ๐Ÿ”ฅBull + confidence %
  • Bear: โ†˜Bear / ๐Ÿ”ฅBear + confidence %
  • Stance: ๐Ÿ”ฅStrong, โ†—Slight, โž–Neutral, โ“Unclear

๐ŸŒ Context (Market State)

  • Regime: ๐Ÿ“ˆUP / ๐Ÿ“‰DN / ใ€ฐ๏ธCHOP
  • Position: ๐Ÿ”HIGH / โž–MID / ๐Ÿ”ปLOW + percentage

๐Ÿ›ก๏ธ Guardian (Risk Control)

  • Risk: โœ…SAFE / โš ๏ธWARN / ๐ŸšจDANGER
  • Guard: โœ…PASS / โ›”BLOCK (with reason on hover)
  • Aligned: โœ… Multi-period aligned / โž– Not aligned

5. Common Operations

# Stop the bot
pkill -f "python main.py"

# Restart the bot (Test Mode)
pkill -f "python main.py"; sleep 2; python main.py --test --mode continuous

# View running processes
ps aux | grep "python main.py"

# View logs in terminal (if running in background)
tail -f logs/trading_$(date +%Y%m%d).log

๐Ÿ“ Project Structure

Directory Description

LLM-TradeBot/
โ”œโ”€โ”€ src/                    # Core Source Code
โ”‚   โ”œโ”€โ”€ agents/            # Multi-Agent Definitions (DataSync, Quant, Decision, Risk)
โ”‚   โ”œโ”€โ”€ api/               # Binance API Client
โ”‚   โ”œโ”€โ”€ data/              # Data Processing (processor, validator)
โ”‚   โ”œโ”€โ”€ exchanges/         # ๐Ÿ†• Multi-Account Exchange Abstraction
โ”‚   โ”‚   โ”œโ”€โ”€ base.py       # BaseTrader ABC + Data Models
โ”‚   โ”‚   โ”œโ”€โ”€ binance_trader.py  # Binance Futures Implementation
โ”‚   โ”‚   โ”œโ”€โ”€ factory.py    # Exchange Factory
โ”‚   โ”‚   โ””โ”€โ”€ account_manager.py # Multi-Account Manager
โ”‚   โ”œโ”€โ”€ execution/         # Order Execution Engine
โ”‚   โ”œโ”€โ”€ features/          # Feature Engineering
โ”‚   โ”œโ”€โ”€ llm/               # ๐Ÿ†• Multi-LLM Interface
โ”‚   โ”‚   โ”œโ”€โ”€ base.py       # BaseLLMClient ABC
โ”‚   โ”‚   โ”œโ”€โ”€ openai_client.py  # OpenAI Implementation
โ”‚   โ”‚   โ”œโ”€โ”€ deepseek_client.py # DeepSeek Implementation
โ”‚   โ”‚   โ”œโ”€โ”€ claude_client.py  # Anthropic Claude
โ”‚   โ”‚   โ”œโ”€โ”€ qwen_client.py    # Alibaba Qwen
โ”‚   โ”‚   โ”œโ”€โ”€ gemini_client.py  # Google Gemini
โ”‚   โ”‚   โ””โ”€โ”€ factory.py    # LLM Factory
โ”‚   โ”œโ”€โ”€ monitoring/        # Monitoring & Logging
โ”‚   โ”œโ”€โ”€ risk/              # Risk Management
โ”‚   โ”œโ”€โ”€ strategy/          # LLM Decision Engine
โ”‚   โ””โ”€โ”€ utils/             # Utilities (DataSaver, TradeLogger, etc.)
โ”‚
โ”œโ”€โ”€ docs/                  # Documentation
โ”‚   โ”œโ”€โ”€ data_flow_analysis.md          # Data Flow Analysis
โ”‚   โ”œโ”€โ”€ ScreenShot_2026-01-21_003126_160.png # Dashboard
โ”‚   โ””โ”€โ”€ Backtesting.png                # Backtesting UI
โ”‚
โ”œโ”€โ”€ data/                  # Structured Data Storage (Archived by Date)
โ”‚   โ”œโ”€โ”€ market_data/       # Raw K-Line Data
โ”‚   โ”œโ”€โ”€ indicators/        # Technical Indicators
โ”‚   โ”œโ”€โ”€ features/          # Feature Snapshots
โ”‚   โ”œโ”€โ”€ decisions/         # Final Decision Results
โ”‚   โ””โ”€โ”€ execution/         # Execution Records
โ”‚
โ”œโ”€โ”€ config/                # Configuration Files
โ”‚   โ””โ”€โ”€ accounts.example.json  # ๐Ÿ†• Multi-Account Config Template
โ”‚
โ”œโ”€โ”€ logs/                  # System Runtime Logs
โ”œโ”€โ”€ tests/                 # Unit Tests
โ”‚
โ”œโ”€โ”€ main.py                # Main Entry Point (Multi-Agent Loop)
โ”œโ”€โ”€ config.yaml            # Trading Parameters
โ”œโ”€โ”€ .env                   # API Key Configuration
โ””โ”€โ”€ requirements.txt       # Python Dependencies

๐ŸŽฏ Core Architecture

Multi-Agent Collaborative Framework + Four-Layer Strategy

The system uses a Four-Layer Strategy Filter with a multi-agent pipeline. Core agents are always enabled, while optional agents can be configured via Dashboard or config.yaml.

Key Feature: Agents have LLM and Local variants - LLM versions use AI for semantic analysis, while Local versions use fast rule-based heuristics.

Core Agents (Always Enabled)

Agent Role Responsibility
๐Ÿ•ต๏ธ DataSyncAgent The Oracle Async concurrent fetch of 5m/15m/1h K-lines, ensuring snapshot consistency
๐Ÿ‘จโ€๐Ÿ”ฌ QuantAnalystAgent The Strategist Generates trend scores, oscillators, sentiment, and OI Fuel (Volume Proxy)
๐Ÿ›ก๏ธ RiskAuditAgent The Guardian Risk audit with absolute veto power on all trades
๐Ÿงญ MultiPeriodParserAgent The Summarizer Multi-period alignment summary for Decision Core

Symbol Selection Layer (Optional)

Agent Role Responsibility
๐ŸŽฐ SymbolSelectorAgent AUTO1/3 Selector Two-stage backtest selection: AI500 Top10 + Majors โ†’ Top 5 (1h) โ†’ Top 2 (15m)

Prediction & Analysis Layer (Optional)

Agent Role Responsibility
๐ŸŽฏ PredictAgent The Prophet Predicts price probability using LightGBM ML model (auto-retrain every 2h)
๐Ÿค– AIPredictionFilterAgent AI Validator AI-Trend alignment verification with veto power
๐Ÿ”ฎ RegimeDetectorAgent Regime Analyzer Detects market state (Trending/Choppy/Ranging) and ADX strength
๐Ÿ“ PositionAnalyzerAgent Position Tracker Price position analysis (High/Mid/Low zone) and S/R level detection
โšก TriggerDetectorAgent Entry Scanner 5m pattern detection and trigger signal scoring

Semantic Analysis Layer (LLM or Local)

Agent LLM Version Local Version Responsibility
๐Ÿ“ˆ TrendAgent TrendAgentLLM TrendAgent 1h trend semantic analysis (UPTREND/DOWNTREND)
๐Ÿ“Š SetupAgent SetupAgentLLM SetupAgent 15m setup zone analysis (KDJ, Bollinger Bands, entry zones)
๐Ÿ”ฅ TriggerAgent TriggerAgentLLM TriggerAgent 5m trigger signal analysis (CONFIRMED/WAITING)

Decision & Execution Layer

Agent Role Responsibility
โš–๏ธ DecisionCoreAgent The Critic Aggregates multi-agent outputs into a final action
๐Ÿš€ ExecutionEngine The Executor Precision order execution and state management
๐Ÿชž ReflectionAgent The Philosopher Trade reflection every 10 trades (LLM or Local variant)

Agent Configuration

Agents can be configured in multiple ways (priority order):

  1. Dashboard Settings โ†’ Agents tab with checkboxes for each optional agent
  2. Environment Variables โ†’ AGENT_<NAME>=true/false (e.g., AGENT_PREDICT_AGENT=false)
  3. config.yaml โ†’ agents: section
# config.yaml example
agents:
  # Prediction & Analysis
  predict_agent: true              # ML probability prediction
  ai_prediction_filter_agent: true # AI veto mechanism
  regime_detector_agent: true      # Market state detection
  position_analyzer_agent: false   # Price position analysis
  trigger_detector_agent: true     # 5m pattern detection
  
  # Semantic Analysis - LLM variants (expensive, disabled by default)
  trend_agent_llm: false           # 1h trend LLM analysis
  setup_agent_llm: false           # 15m setup LLM analysis
  trigger_agent_llm: false         # 5m trigger LLM analysis
  
  # Semantic Analysis - Local variants (fast, enabled by default)
  trend_agent_local: true          # 1h trend rule-based analysis
  setup_agent_local: true          # 15m setup rule-based analysis
  trigger_agent_local: true        # 5m trigger rule-based analysis
  
  # Reflection
  reflection_agent_llm: false      # Trade reflection via LLM
  reflection_agent_local: true     # Trade reflection via rules
  
  # Symbol Selection
  symbol_selector_agent: true      # AUTO symbol selection

Four-Layer Strategy Filter

Layer 1: Trend + Fuel (1h EMA + Volume Proxy)
    โ†“ PASS/FAIL
Layer 2: AI Filter (PredictAgent direction alignment)
    โ†“ PASS/VETO
Layer 3: Setup (15m KDJ + Bollinger Bands entry zone)
    โ†“ READY/WAIT
Layer 4: Trigger (5m Pattern + RVOL volume confirmation)
    โ†“ CONFIRMED/WAITING
    โ†“
๐Ÿง  LLM Decision (DeepSeek Bull/Bear Debate)
    โ†“
๐Ÿ›ก๏ธ Risk Audit (Veto Power)
    โ†“
๐Ÿš€ Execution

Data Flow Diagrams

๐Ÿ“– See System Architecture Overview section above for visual diagrams.

๐Ÿ“ Mermaid Diagram (Interactive)
graph TB
    subgraph "1๏ธโƒฃ Data Collection Layer"
        A["๐Ÿ•ต๏ธ DataSyncAgent<br/>(The Oracle)"] --> MS["MarketSnapshot<br/>5m/15m/1h K-lines"]
    end
    
    subgraph "2๏ธโƒฃ Quant Analysis Layer"
        MS --> QA["๐Ÿ‘จโ€๐Ÿ”ฌ QuantAnalystAgent<br/>(The Strategist)"]
        QA --> TS["๐Ÿ“ˆ TrendSubAgent"]
        QA --> OS["๐Ÿ“Š OscillatorSubAgent"]
        QA --> SS["๐Ÿ’น SentimentSubAgent"]
        TS & OS & SS --> QR["Quant Signals"]
    end

    subgraph "3๏ธโƒฃ Prediction Layer"
        MS --> PA["๐Ÿ”ฎ PredictAgent<br/>(The Prophet)"]
        PA --> ML["LightGBM Model<br/>Auto-Train 2h"]
        ML --> PR["P_Up Prediction"]
    end

    subgraph "4๏ธโƒฃ Bull/Bear Adversarial Layer"
        MS --> BULL["๐Ÿ‚ Bull Agent<br/>(The Optimist)"]
        MS --> BEAR["๐Ÿป Bear Agent<br/>(The Pessimist)"]
        BULL --> BP["Bull Perspective"]
        BEAR --> BRP["Bear Perspective"]
    end
    
    subgraph "5๏ธโƒฃ Reflection Layer"
        TH["๐Ÿ“œ Trade History<br/>Last 10 Trades"] --> REF["๐Ÿง  ReflectionAgent<br/>(The Philosopher)"]
        REF --> RI["Reflection Insights<br/>Patterns & Recommendations"]
    end
    
    subgraph "6๏ธโƒฃ Decision Layer"
        QR & PR & BP & BRP & RI --> DC["โš–๏ธ DecisionCoreAgent<br/>(The Critic)"]
        DC --> RD["RegimeDetector"]
        DC --> POS["PositionAnalyzer"]
        RD & POS --> VR["VoteResult<br/>Action + Confidence"]
    end
    
    subgraph "7๏ธโƒฃ Risk Audit Layer"
        VR --> RA["๐Ÿ›ก๏ธ RiskAuditAgent<br/>(The Guardian)"]
        RA --> AR["AuditResult<br/>Risk Level + Guard"]
    end
    
    subgraph "8๏ธโƒฃ Execution Layer"
        AR --> EE["๐Ÿš€ ExecutionEngine<br/>(The Executor)"]
        EE -.->|"Trade Complete"| TH
    end
    
    %% Styling for Agent Nodes
    style A fill:#4A90E2,color:#fff,stroke:#2563EB,stroke-width:2px
    style QA fill:#7ED321,color:#fff,stroke:#059669,stroke-width:2px
    style PA fill:#BD10E0,color:#fff,stroke:#9333EA,stroke-width:2px
    style BULL fill:#F8E71C,color:#333,stroke:#CA8A04,stroke-width:2px
    style BEAR fill:#F8E71C,color:#333,stroke:#CA8A04,stroke-width:2px
    style REF fill:#00CED1,color:#fff,stroke:#0891B2,stroke-width:2px
    style DC fill:#F5A623,color:#fff,stroke:#EA580C,stroke-width:2px
    style RA fill:#D0021B,color:#fff,stroke:#DC2626,stroke-width:2px
    style EE fill:#9013FE,color:#fff,stroke:#7C3AED,stroke-width:2px
    
    %% Styling for Output Nodes
    style MS fill:#1E3A5F,color:#fff
    style QR fill:#1E3A5F,color:#fff
    style PR fill:#1E3A5F,color:#fff
    style BP fill:#1E3A5F,color:#fff
    style BRP fill:#1E3A5F,color:#fff
    style RI fill:#1E3A5F,color:#fff
    style VR fill:#1E3A5F,color:#fff
    style AR fill:#1E3A5F,color:#fff
    style TH fill:#1E3A5F,color:#fff

๐Ÿ“– Detailed Docs: See Data Flow Analysis for complete mechanisms.


๐Ÿงช Backtesting

Professional-grade backtesting system for strategy validation before live trading:

Backtesting Interface

Features:

  • ๐Ÿ“Š Multi-Tab Parallel Backtests: Run up to 5 backtests simultaneously with independent configurations
  • ๐Ÿ“ˆ Real-time Progress: Live equity curve, drawdown chart, and trade markers
  • ๐ŸŽฏ LLM-Enhanced Mode: Test the full multi-agent decision system including DeepSeek analysis
  • ๐Ÿ“… Flexible Date Ranges: Quick presets (1/3/7/14/30 days) or custom date selection
  • โš™๏ธ Advanced Parameters: Configurable leverage, stop-loss, take-profit, and trailing stops
  • ๐Ÿ“‹ Detailed Metrics: Total return, Sharpe/Sortino ratios, win rate, max drawdown, and more
  • ๐Ÿ’พ Full Logging: All decisions and LLM interactions saved for analysis

Access: Visit http://localhost:8000/backtest after starting the bot.


๐Ÿ“„ Full-Link Data Auditing

Storage Organization

The system automatically records intermediate processes for each cycle in the data/ directory, organized by date for easy review and debugging:

data/
โ”œโ”€โ”€ market_data/           # Raw Multi-Timeframe K-Lines
โ”‚   โ””โ”€โ”€ {date}/
โ”‚       โ”œโ”€โ”€ BTCUSDT_5m_{timestamp}.json
โ”‚       โ”œโ”€โ”€ BTCUSDT_5m_{timestamp}.csv
โ”‚       โ”œโ”€โ”€ BTCUSDT_5m_{timestamp}.parquet
โ”‚       โ”œโ”€โ”€ BTCUSDT_15m_{timestamp}.json
โ”‚       โ””โ”€โ”€ BTCUSDT_1h_{timestamp}.json
โ”‚
โ”œโ”€โ”€ indicators/            # Full Technical Indicators DataFrames
โ”‚   โ””โ”€โ”€ {date}/
โ”‚       โ”œโ”€โ”€ BTCUSDT_5m_{snapshot_id}.parquet
โ”‚       โ”œโ”€โ”€ BTCUSDT_15m_{snapshot_id}.parquet
โ”‚       โ””โ”€โ”€ BTCUSDT_1h_{snapshot_id}.parquet
โ”‚
โ”œโ”€โ”€ features/              # Feature Snapshots
โ”‚   โ””โ”€โ”€ {date}/
โ”‚       โ”œโ”€โ”€ BTCUSDT_5m_{snapshot_id}_v1.parquet
โ”‚       โ”œโ”€โ”€ BTCUSDT_15m_{snapshot_id}_v1.parquet
โ”‚       โ””โ”€โ”€ BTCUSDT_1h_{snapshot_id}_v1.parquet
โ”‚
โ”œโ”€โ”€ context/               # Quant Analysis Summary
โ”‚   โ””โ”€โ”€ {date}/
โ”‚       โ””โ”€โ”€ BTCUSDT_quant_analysis_{snapshot_id}.json
โ”‚
โ”œโ”€โ”€ llm_logs/              # LLM Input Context & Voting Process
โ”‚   โ””โ”€โ”€ {date}/
โ”‚       โ””โ”€โ”€ BTCUSDT_{snapshot_id}.md
โ”‚
โ”œโ”€โ”€ decisions/             # Final Weighted Vote Results
โ”‚   โ””โ”€โ”€ {date}/
โ”‚       โ””โ”€โ”€ BTCUSDT_{snapshot_id}.json
โ”‚
โ””โ”€โ”€ execution/             # Execution Tracking
    โ””โ”€โ”€ {date}/
        โ””โ”€โ”€ BTCUSDT_{timestamp}.json

Data Formats

  • JSON: Human-readable, used for configuration and decision results
  • CSV: High compatibility, easy for Excel import
  • Parquet: Efficient compression, used for large-scale time-series data

๐Ÿ›ก๏ธ Safety Warning

โš ๏ธ Important Safety Measures:

  1. API Keys: Keep them safe, DO NOT commit to version control.
  2. Test First: Use --test argument to run simulations first.
  3. Risk Control: Set reasonable stop-loss and position limits in config.yaml.
  4. Minimal Permissions: Grant only necessary Futures Trading permissions to API keys.
  5. Monitoring: Regularly check the logs/ directory for anomalies.

๐Ÿ“š Documentation Navigation

Document Description
README.md Project Overview & Quick Start
Data Flow Analysis Complete Data Flow Mechanisms
API Key Guide API Key Configuration Guide
Config Example Trading Parameters Template
Env Example Environment Variables Template

๐ŸŽ‰ Latest Updates

2026-02-07:

  • โœ… Multi-Agent Chatroom: Per-cycle agent outputs with Decision Core final action.
  • โœ… Agent Config Tabs: Per-agent parameters + optional system prompts in the UI.
  • โœ… LLM Toggle (default off): Enables LLM only when key is provided.
  • โœ… Multi-Period Parser: 1h/15m/5m alignment summarized for Decision Core.
  • โœ… Balance & PnL Fixes: Initial balance fixed, PnL-driven current balance.

2026-01-07:

  • โœ… AUTO3 Two-Stage Symbol Selection: Enhanced SymbolSelectorAgent with two-stage filtering.
    • Stage 1 (Coarse Filter): 1h backtest on AI500 Top10 + Major coins (~16 symbols) โ†’ Top 5
    • Stage 2 (Fine Filter): 15m backtest on Top 5 โ†’ Top 2 performers
    • Expanded candidate pool: AI500 (30+ AI/Data coins) + Majors (BTC, ETH, SOL, BNB, XRP, DOGE)
    • Auto-refresh every 6 hours with smart caching
  • โœ… BacktestAgentRunner Parity: Full consistency between backtest and live trading environments.
    • Risk Audit Agent integrated into backtest flow
    • Four-Layer Strategy Filter applied in backtests
    • Position analysis and regime detection enabled
  • โœ… Enhanced Backtest CLI: python backtest.py with support for:
    • Multi-symbol backtesting
    • Agent strategy mode (--strategy-mode agent)
    • LLM enhancement option (--use-llm)
    • Detailed HTML reports with equity curves

2025-12-31:

  • โœ… Full Chinese Internationalization (i18n): Complete bilingual support with language toggle button.
    • Dashboard UI elements (headers, tables, buttons) fully translated
    • Agent documentation sidebar with Chinese descriptions
    • Seamless language switching without page reload

2025-12-28:

  • โœ… Dashboard Log Mode Toggle: Switch between Simplified (agent summaries) and Detailed (full debug) log views.
  • โœ… Net Value Curve Enhancement: Smart x-axis labels that adapt to data volume while preserving first cycle timestamp.

2025-12-25:

  • โœ… ReflectionAgent (The Philosopher): New agent that analyzes every 10 trades and provides insights to improve future decisions.
  • โœ… Trading Retrospection: Automatic pattern detection, confidence calibration, and actionable recommendations.
  • โœ… Decision Integration: Reflection insights are injected into Decision Agent prompts for continuous learning.

2025-12-24:

  • โœ… Multi-LLM Support: Added support for 8 LLM providers (DeepSeek, OpenAI, Claude, Qwen, Gemini, Kimi, MiniMax, GLM) with unified interface.
  • โœ… Dashboard LLM Settings: Switch LLM provider and API keys directly from Dashboard Settings.
  • โœ… Multi-Account Architecture: New src/exchanges/ module with BaseTrader abstraction for multi-exchange support.
  • โœ… Account Manager: Manage multiple trading accounts via Dashboard or config/accounts.json.

2025-12-21:

  • โœ… ML Model Upgrade: Upgraded PredictAgent to use LightGBM machine learning model.
  • โœ… Auto-Training: Implemented automatic model retraining every 2 hours to adapt to market drifts.
  • โœ… Dashboard Refinement: Enhanced dashboard with auto-scrolling logs, robust scrollbars, and ML probability display.

2025-12-20:

  • โœ… Adversarial Decision Framework: Introduced PositionAnalyzer and RegimeDetector.
  • โœ… Confidence Score Refactor: Implemented dynamic confidence penalties.
  • โœ… Full-Link Auditing: Implemented complete intermediate state archiving.

โ“ Frequently Asked Questions (FAQ)

For Beginners

Q: Is this safe to use? Will I lose money? A: Test mode is 100% safe - it uses virtual money. For live trading, only use funds you can afford to lose. Cryptocurrency trading is risky.

Q: Do I need to know Python to use this? A: No! Just follow the Quick Start guide. You only need Python installed, not programming knowledge.

Q: How much money do I need to start? A: Test mode is free. For live trading, minimum $100 USDT recommended, but start small while learning.

Q: Will the bot trade 24/7? A: Yes, once started in continuous mode, it runs non-stop analyzing markets and making decisions.

Q: How do I know if it's working? A: Open http://localhost:8000 in your browser to see the real-time dashboard with live logs and charts.

Technical Questions

Q: Which exchanges are supported? A: Currently only Binance Futures. Spot trading and other exchanges are not supported.

Q: Can I customize the trading strategy? A: Yes! Edit config.yaml for basic parameters. Advanced users can modify agent logic in src/ directory.

Q: What's the difference between Test and Live mode? A: Test mode simulates trading with $1000 virtual balance. Live mode executes real trades on Binance.

Q: How do I stop the bot? A: Press Ctrl+C in the terminal, or run pkill -f "python main.py"

Q: Why is the dashboard not loading? A: Make sure the bot is running and visit http://localhost:8000. Check firewall settings if issues persist.

Troubleshooting

Q: "ModuleNotFoundError" when starting A: Run pip install -r requirements.txt to install all dependencies.

Q: "API Key invalid" error A: Check your .env file has correct Binance API keys. For test mode, API keys are optional.

Q: Bot keeps saying "WAIT" and not trading A: This is normal! The bot is conservative and only trades when conditions are favorable. Check the dashboard logs for reasoning.

Q: How do I update to the latest version? A: Run git pull origin main then restart the bot.


๐Ÿค Contribution

Issues and Pull Requests are welcome!


This project is licensed under the MIT License. See the LICENSE file for details.


Empowered by AI, Focused on Precision, Starting a New Era of Intelligent Quant! ๐Ÿš€

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for LLM-TradeBot

Similar Open Source Tools

For similar tasks

For similar jobs