🤖 Hyperliquid AI Trading Bot

An autonomous AI-powered trading bot for Hyperliquid DEX perpetual futures, featuring advanced machine learning strategies, LLM-driven decision making, and a modern web dashboard.

---

✨ Features

🧠 Multi-Regime Ensemble Strategy

• Hidden Markov Model for market regime detection (Trending/Ranging/Volatile)
• Dynamic strategy switching based on market conditions
• Kelly Criterion position sizing with fractional Kelly (25%)
• Academic research-backed approach (57+ peer-reviewed studies)

📊 Advanced Signal Layer

• Volume-Weighted: VWAP deviation, OBV divergence, MFI extremes
• Order Flow: Bid-ask imbalance, market depth slope
• Funding Rate: Arbitrage detection, momentum signals
• Liquidation Cascade: OI surge detection, whale activity

🤖 LLM Intervention System

• Kimi K2.5 integration for autonomous decision making
• Knowledge persistence across trading sessions
• Self-improving through accumulated experience
• Configurable intervention intervals (default: 4 hours)

🐳 Docker Ready

• One-command deployment with Docker Compose
• Non-root container for security
• Health checks and automatic restarts
• Volume persistence for data and logs

🌐 Web Dashboard

• Real-time status monitoring
• Position management with PnL tracking
• Circuit breaker control
• Configuration editor
• Secrets management (masked inputs)
• LLM intervention trigger and history

---

🚀 Quick Start

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/f0x-sketch/hyperliquid-ai-bot.git
cd hyperliquid-ai-bot

# Create environment file
cp .env.example .env
nano .env  # Add your credentials

# Build and run
docker-compose up -d --build

# Access Web UI
open http://localhost:8080

Option 2: Local Installation

# Clone the repository
git clone https://github.com/f0x-sketch/hyperliquid-ai-bot.git
cd hyperliquid-ai-bot

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or: .\venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
nano .env  # Add your credentials

# Run the bot
python run.py

---

⚙️ Configuration

Environment Variables

Variable	Required	Description
HL_PRIVATE_KEY	✅	API wallet private key (for signing orders)
HL_WALLET_ADDRESS	✅	Main wallet address (for queries)
HL_NETWORK	✅	testnet or mainnet
KIMI_API_KEY	⬜	Kimi API key for LLM intervention
OPENROUTER_API_KEY	⬜	OpenRouter API key (fallback)

Strategy Parameters

EnsembleStrategyConfig:
    regime_lookback: 100        # Bars for regime detection
    signal_threshold: 0.6       # Min confidence to trade
    kelly_fraction: 0.25        # Fractional Kelly (25%)
    max_drawdown_limit: 0.15    # 15% max drawdown
    funding_arb_threshold: 0.0005  # 0.05% funding gap

Risk Management

Parameter	Default	Description
Max Leverage	5x	Maximum position leverage
Risk per Trade	2%	Maximum risk per position
Max Drawdown	15%	Circuit breaker threshold
Max Daily Loss	3%	Daily loss limit

---

📁 Project Structure

hyperliquid-ai-bot/
├── 📄 bot.py                 # Main trading bot orchestrator
├── 📄 run.py                 # Entry point with web UI
├── 📄 api.py                 # FastAPI web server
├── 📄 config.py              # Configuration management
├── 📄 executor.py            # Order execution & tracking
├── 📄 risk.py                # Risk management & circuit breaker
├── 📄 market_data.py         # WebSocket + REST data feeds
├── 📄 memory.py              # SQLite trade journal
├── 📄 knowledge.py           # Knowledge management system
├── 📄 llm_intervention.py    # LLM decision engine
├── 📄 strategy_manager.py    # Strategy registry & scoring
├── 📄 backtest.py            # Historical simulation
├── 📄 optimizer.py           # Parameter optimization
├── 📄 llm_reviewer.py        # LLM self-review
├── 📁 strategies/
│   ├── base.py               # Base strategy class
│   ├── ema_cross.py          # EMA crossover strategy
│   ├── bollinger_rsi.py      # Bollinger + RSI strategy
│   ├── ml_signal.py          # XGBoost ML strategy
│   ├── ensemble_strategy.py  # Multi-regime ensemble
│   ├── regime_detector.py    # HMM regime detection
│   └── signal_layer.py       # Advanced signals
├── 📁 tests/                 # Unit tests
├── 📁 static/                # Web UI assets
├── 📁 data/                  # Models & knowledge
├── 📁 logs/                  # Runtime logs
├── 📁 reports/               # Daily reports
├── 🐳 Dockerfile             # Docker image
├── 🐳 docker-compose.yml     # Docker orchestration
└── 📄 requirements.txt       # Python dependencies

---

🌐 Web UI Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/status	Account & positions
GET	/config	Current configuration
POST	/config	Update configuration
POST	/secrets	Update API keys
POST	/circuit-breaker/reset	Reset circuit breaker
POST	/bot/start	Start trading
POST	/bot/stop	Stop trading
GET	/knowledge	Knowledge base
POST	/intervention/trigger	Trigger LLM review
GET	/intervention/history	Intervention history

---

🧪 Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=. --cov-report=html

# Run specific test
pytest tests/test_strategies.py -v

---

🐳 Docker Commands

# Build image
docker-compose build

# Start container
docker-compose up -d

# View logs
docker-compose logs -f

# Check status
docker-compose ps

# Restart
docker-compose restart

# Stop
docker-compose down

# Rebuild after changes
docker-compose up -d --build

---

📊 Expected Performance

Based on academic research benchmarks:

Metric	Expected Range
Sharpe Ratio	1.5 - 2.5
Max Drawdown	< 15%
Win Rate	55 - 65%
Profit Factor	1.8 - 2.5

---

🛡️ Safety Features

1. Circuit Breaker: Halts trading on 15% drawdown
2. Stop-Loss Enforcement: Required on every trade
3. Kelly Criterion: Fractional position sizing
4. Max Leverage: Enforced maximum leverage
5. Testnet First: Always test on testnet before mainnet

---

🔧 Hyperliquid Setup

1. Create API Wallet

1. Go to Hyperliquid
2. Connect your main wallet
3. Navigate to Settings > API
4. Create a new API wallet
5. Copy the API wallet private key to HL_PRIVATE_KEY
6. Use your main wallet address for HL_WALLET_ADDRESS

2. Fund Your Account

• Testnet: Use the Hyperliquid Testnet Faucet
• Mainnet: Deposit USDC to your perps account

3. Approve API Wallet

In Hyperliquid UI, approve your API wallet for trading.

---

📚 Documentation

• Docker Deployment Guide
• Academic Research Report

---

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

---

⚠️ Disclaimer

USE AT YOUR OWN RISK. This bot trades real money. Always:

1. Test thoroughly on testnet first
2. Start with small position sizes
3. Monitor closely for the first 48 hours
4. Never risk more than you can afford to lose

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

• Academic research from arXiv, MDPI, ScienceDirect
• Hyperliquid Python SDK
• Kimi K2.5 for LLM capabilities
• OpenRouter for API access