NexusQuant | 灵枢量化

AI-Driven Multi-Strategy, Multi-Timeframe Cryptocurrency Trading Monitor

<div align="center">

Repository: github.com/python-telegramBot/ai-auto-trading

| English | 简体中文 | 日本語 | |:---:|:---:|:---:|

</div>

---

Table of Contents

• Overview
• Core Capabilities
• System Architecture
• Tech Stack
• Quick Start
• Configuration Reference
• Trading Strategies
• Monitoring Dashboard
• Risk Management
• Documentation
• Risk Disclaimer
• License
• Resources & Referrals

---

Overview

NexusQuant (灵枢量化) is a next-generation AI-powered cryptocurrency automated trading system that fundamentally redefines quantitative trading by deeply integrating large language models with institutional-grade trading practices.

Design Philosophy

AI-First Architecture — The system treats AI as an autonomous trading agent, granting it full decision-making authority over market analysis, strategy selection, position management, and risk control.

Adaptive Intelligence — True market adaptability is achieved through a Market State Recognition Engine (8 distinct states), a Dynamic Strategy Router, and an Intelligent Opportunity Scoring System.

Professional Risk Control — Features ATR-adaptive stop-losses, R-Multiple partial take-profits, server-side conditional orders, and database transaction rollback mechanisms to ensure capital protection at every layer.

---

Core Capabilities

1. State-Adaptive Entry System

Automatically identifies 8 distinct market states — including oversold uptrends, overbought downtrends, trend continuations, and range-bound extremes — then intelligently routes to the optimal strategy. This prevents false breakout entries and captures genuine trend reversals.

2. Scientific Stop-Loss System

• ATR-based dynamic stop-loss calculation for market-responsive protection
• Server-side execution ensures protection persists even if the application crashes
• Pre-entry stop-loss space validation before any position is opened
• Intelligent trailing stops that move only in the favorable direction

3. R-Multiple Partial Take-Profit

Institutional risk-multiple thinking automated end-to-end. Positions are partially closed at 2R, 3R, and 5R targets, with stop-losses automatically moved to breakeven or better after each partial exit.

4. Transaction Integrity Protection

Database transaction rollback mechanisms, inconsistency-state logging, and idempotency protection ensure exchange records and local database records remain fully synchronized at all times.

5. Intelligent Opportunity Scoring

A multi-factor quantitative scoring model evaluates every potential trade before entry:

| Factor | Weight | |--------|--------| | Signal Strength | 40% | | Risk/Reward Ratio | 25% | | Market Conditions | 20% | | Position Correlation | 15% |

Only trades exceeding the minimum score threshold are executed.

6. System Health Monitoring

Real-time three-tier health indicators (🟢 Healthy / 🟡 Warning / 🔴 Critical), automated health checks, orphan order detection and cleanup, and proactive alerting keep the system operating reliably around the clock.

---

System Architecture

┌─────────────────────────────────────────────────────────┐
│                   Trading Agent (AI)                    │
│          DeepSeek V3.2 / Grok 4 / Claude / Gemini       │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ├─── Market Data Analysis
                  ├─── Position Management
                  └─── Trade Execution Decisions

┌─────────────────┴───────────────────────────────────────┐
│                    VoltAgent Core                       │
│              (Agent Orchestration & Tool Routing)       │
└─────────┬───────────────────────────────────┬───────────┘
          │                                   │
┌─────────┴──────────┐            ┌───────────┴───────────┐
│    Trading Tools   │            │   Exchange API Client  │
│                    │            │                        │
│ - Market Data      │◄───────────┤ - Order Management     │
│ - Account Info     │            │ - Position Query       │
│ - Trade Execution  │            │ - Market Data Stream   │
└─────────┬──────────┘            └────────────────────────┘
          │
┌─────────┴──────────┐
│   LibSQL Database  │
│                    │
│ - Account History  │
│ - Trade Signals    │
│ - Agent Decisions  │
└────────────────────┘

---

Tech Stack

| Component | Technology | Purpose | |-----------|-----------|---------| | Framework | VoltAgent | AI agent orchestration and tool routing | | AI Models | OpenAI-compatible API | DeepSeek V3.2, Grok 4, Claude 4.5, Gemini 2.5, and more | | Exchanges | Gate.io / Binance | Perpetual futures trading (testnet & mainnet) | | Database | LibSQL (SQLite) | Local data persistence | | Web Server | Hono | High-performance monitoring interface | | Language | TypeScript | Type-safe development | | Runtime | Node.js 20.19+ | JavaScript execution environment |

---

Quick Start

Step 1 — Register an Exchange Account

NexusQuant supports both Gate.io and Binance. Choose based on your needs:

Option A: Gate.io (Recommended for beginners)

Gate.io offers a well-developed testnet environment ideal for learning and strategy validation before risking real capital.

• Register on Gate.io — Referral code: VQBEAwgL
• Testnet: https://testnet.gate.com/

Option B: Binance (World's largest exchange)

Binance offers superior liquidity, high trading volume, and full testnet support.

• Register on Binance — Referral code: GRO_28502_NCRQJ
• Testnet: https://testnet.binancefuture.com/

Beginner's Tip: Always start on the testnet. You get a full trading experience with zero financial risk — perfect for validating your configuration before going live.

---

Step 2 — Prerequisites

Ensure the following are installed on your system:

• Node.js >= 20.19.0
• npm or pnpm
• Git

---

Step 3 — Install the Project

# Clone the repository
git clone <repository-url>
cd ai-auto-trading

# Install dependencies
npm install

---

Step 4 — Configure Environment Variables

cp .env.example .env
nano .env

Key Configuration Options

# ── Server ──────────────────────────────────────────────
PORT=3100

# ── Trading Core ────────────────────────────────────────
TRADING_INTERVAL_MINUTES=5          # How often the agent runs (minutes)
TRADING_STRATEGY=balanced           # Strategy: ultra-short | swing-trend | conservative | balanced | aggressive
TRADING_SYMBOLS=BTC,ETH,SOL,BNB,XRP # Comma-separated list of trading pairs
MAX_LEVERAGE=15                     # Maximum leverage multiplier
MAX_POSITIONS=5                     # Maximum concurrent open positions
INITIAL_BALANCE=1000                # Starting capital (USDT)
ACCOUNT_STOP_LOSS_USDT=50           # Account-level stop-loss threshold
ACCOUNT_TAKE_PROFIT_USDT=20000      # Account-level take-profit threshold

# ── Scientific Stop-Loss System (Recommended) ───────────
ENABLE_SCIENTIFIC_STOP_LOSS=true    # Enable ATR-adaptive stop-loss
ENABLE_TRAILING_STOP_LOSS=true      # Enable trailing stop-loss
ENABLE_STOP_LOSS_FILTER=true        # Require valid stop-loss space before entry

# ── Exchange Selection ───────────────────────────────────
EXCHANGE_NAME=gate                  # Options: gate | binance

# ── Gate.io (required when EXCHANGE_NAME=gate) ──────────
GATE_API_KEY=your_api_key_here
GATE_API_SECRET=your_api_secret_here
GATE_USE_TESTNET=true

# ── Binance (required when EXCHANGE_NAME=binance) ───────
BINANCE_API_KEY=your_api_key_here
BINANCE_API_SECRET=your_api_secret_here
BINANCE_USE_TESTNET=true

# ── AI Model (OpenAI-compatible) ─────────────────────────
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://openrouter.ai/api/v1
AI_MODEL_NAME=deepseek/deepseek-v3.2-exp

Obtaining API Keys

AI Models:

| Provider | URL | |----------|-----| | OpenRouter (multi-model) | https://openrouter.ai/keys | | OpenAI | https://platform.openai.com/api-keys | | DeepSeek | https://platform.deepseek.com/api_keys |