This bot provides complete manual control of your Hyperliquid account via Telegram, with professional-grade statistics tracking including P&L, win rates, Sharpe ratio, Sortino ratio, and all the metrics you'd expect from a trading platform.
Carles Sentis
b39af68d2e
Update BOT_VERSION to 2.2.125 for release preparation
|
35 分鐘之前 | |
|---|---|---|
| config | 2 天之前 | |
| docs | 3 小時之前 | |
| src | 1 小時之前 | |
| tests | 1 天之前 | |
| utils | 3 天之前 | |
| .gitignore | 1 天之前 | |
| LICENSE | 2 天之前 | |
| README.md | 1 天之前 | |
| requirements.txt | 3 天之前 | |
| reset_data.sh | 1 天之前 | |
| trading_bot.py | 35 分鐘之前 |
README.md
🚀 Hyperliquid Manual Trading Bot
Professional-grade manual trading with comprehensive statistics and mobile control
Complete phone control of your Hyperliquid account via Telegram with institutional-level analytics, auto-restart capabilities, and bulletproof data persistence.
🎯 What This Bot Delivers
📱 Phone Trading
- Complete control from anywhere via Telegram
- One-tap actions with inline keyboards
- Instant notifications for trades and errors
- Mobile-optimized interface design
🛡️ 🆕 Bulletproof Stop Loss Management
- Smart edge case detection for cancel/fill race conditions
- 3-second grace period verification before cancelling stop losses
- Recent fill analysis to prevent premature stop loss cancellation
- Order state reconciliation for simultaneous exchange operations
- Enhanced reliability that handles Hyperliquid's timing complexities
📊 Professional Analytics
- Real-time P&L tracking with percentage returns
- Advanced metrics: Sharpe ratio, Sortino ratio, VaR (95%)
- Trade analytics: Win rate, profit factor, expectancy
- Risk monitoring: Max drawdown, volatility analysis
- Complete audit trail with order IDs and timestamps
🛡️ Bulletproof Reliability
- Auto-restart on errors (up to 10 attempts)
- Persistent statistics that survive forever
- Error notifications sent to your phone
- Comprehensive logging with daily files
- Graceful shutdown handling
- 🔥 Enhanced order tracking with edge case handling
⚙️ CCXT Compatibility
- Standard authentication following CCXT patterns
- Enhanced parameters support for advanced trading
- Future-proof architecture
- Professional configuration management
🚀 Single Command Launch
python trading_bot.py
That's it! This one command:
- ✅ Starts Telegram bot automatically
- ✅ Handles all errors and restarts
- ✅ Sends notifications to your phone
- ✅ Manages logging and data persistence
- ✅ Validates configuration before starting
- ✅ 🔥 Monitors stop losses with bulletproof reliability
⚡ Quick Setup (5 Minutes)
1. Install & Configure
# Clone repository
git clone git@repo.codeskraps.com:codeskraps/ManualTrader.git
cd ManualTrader
# Setup environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Configure bot
cp config/env.example .env
nano .env # Add your keys
2. Get Telegram Chat ID
# Use the robust script
python utils/get_telegram_chat_id.py
3. Start Trading!
python trading_bot.py
📱 Open Telegram → Send /start to your bot
📁 Clean Project Structure
trader_hyperliquid/
├── 🚀 trading_bot.py # MAIN LAUNCHER (run this!)
├── 📊 data/ # Persistent data storage
│ ├── trading_stats.sqlite # SQLite database with all trading data
│ └── price_alarms.json # Price alarm configurations
├── 📝 .env # Your configuration
│
├── 🔧 src/ # Core application modules
├── 🛠️ utils/ # Setup & maintenance tools
├── ⚙️ config/ # Configuration templates
├── 📋 logs/ # Auto-created logs & errors
├── 🧪 tests/ # Comprehensive test suite
└── 📖 docs/ # Complete documentation
For detailed architecture and module breakdown, see 📖 Complete Project Structure
📱 Mobile Trading Interface
Quick Commands
/start # Main menu with instant buttons
/balance # Real-time balance + P&L
/stats # Complete trading statistics
/positions # Open positions with P&L
/orders # Pending orders
Trading Commands
/long BTC 100 # Long BTC with $100 USDC (Market)
/long BTC 100 50000 # Long BTC with $100 at $50,000 (Limit)
/long BTC 100 sl:49000 # Long BTC with stop loss at $49,000 🔥
/short ETH 50 # Short ETH with $50 USDC (Market)
/short ETH 50 3500 # Short ETH with $50 at $3,500 (Limit)
/short ETH 50 sl:3600 # Short ETH with stop loss at $3,600 🔥
/exit BTC # Close BTC position
🔥 Enhanced Stop Loss Features
- Bulletproof activation - Stop losses activate even during external cancellations
- Race condition handling - Handles cancel/fill timing issues automatically
- Smart verification - Double-checks order states before critical actions
- Edge case detection - Prevents premature stop loss cancellation
Instant Action Buttons
Send /start for one-tap access to:
- 💰 Balance, 📊 Stats, 📈 Positions, 📋 Orders, 💵 Price
📊 Professional Statistics
📊 Trading Statistics
💰 Balance Overview
• Initial: $1,000.00 ← Starting balance (never lost)
• Current: $1,150.00 ← Real-time balance
• Total P&L: $150.00 ← Profit/Loss
• Total Return: 15.00% ← Percentage return
📈 Trading Activity
• Total Trades: 25 ← Complete trade count
• Buy Orders: 13 ← Order breakdown
• Sell Orders: 12
• Days Active: 30 ← Since first launch
🏆 Performance Metrics
• Win Rate: 68.0% ← Profitable trades %
• Profit Factor: 2.15 ← Gains ÷ Losses
• Avg Win: $45.50 ← Average winning trade
• Avg Loss: $28.75 ← Average losing trade
• Expectancy: $6.25 ← Expected $ per trade
📊 Risk Metrics
• Sharpe Ratio: 1.85 ← Risk-adjusted returns
• Sortino Ratio: 2.41 ← Downside risk metric
• Max Drawdown: 8.5% ← Worst decline from peak
• Volatility: 12.3% ← Price volatility
• VaR (95%): 3.2% ← Value at Risk
🎯 Best/Worst Performance
• Largest Win: $125.00 ← Best single trade
• Largest Loss: $75.00 ← Worst single trade
• Max Consecutive Wins: 5 ← Winning streaks
• Max Consecutive Losses: 2 ← Losing streaks
📅 Tracking Since: 2024-01-15
⚙️ CCXT-Style Configuration
Following CCXT standards for exchange compatibility:
⚠️ IMPORTANT SECURITY: Use the API Generator Key from https://app.hyperliquid.xyz/API for trading operations. DO NOT use your wallet's private key directly for security reasons. Generate a dedicated API key with appropriate permissions for trading through this bot.
# Hyperliquid API (CCXT Style)
HYPERLIQUID_SECRET_KEY=your_api_secret_key_here # ← Secret Key from API generator
HYPERLIQUID_WALLET_ADDRESS=your_api_wallet_address_here # ← API Wallet Address from generator
HYPERLIQUID_TESTNET=true
# Telegram Bot
TELEGRAM_BOT_TOKEN=your_token_from_botfather
TELEGRAM_CHAT_ID=your_chat_id_here
TELEGRAM_ENABLED=true
# Trading Settings
DEFAULT_TRADING_SYMBOL=BTC/USDC:USDC
DEFAULT_TRADE_AMOUNT=0.001
🛡️ Built-in Safety Features
📊 Data Protection
- Statistics never lost - saved to
trading_stats.json - Automatic backups via comprehensive logging
- Persistent between restarts - your data survives forever
🔄 Error Recovery
- Auto-restart up to 10 attempts with exponential backoff
- Telegram error notifications sent to your phone
- Comprehensive logging to daily files
- Graceful shutdown on Ctrl+C
🔥 Enhanced Stop Loss Reliability
- Smart edge case detection for simultaneous cancel/fill scenarios
- 3-second grace periods before cancelling stop losses
- Recent fill verification to prevent premature cancellation
- Order state reconciliation for race condition handling
- Bulletproof tracking that handles Hyperliquid's complexity
⚠️ Trading Safety
- Testnet default - safe testing environment
- Order confirmations - all trades require approval
- Balance monitoring - real-time P&L tracking
- Clear error messages with troubleshooting tips
🎮 Demo & Testing
See Sample Statistics
python utils/demo_stats.py
Shows you exactly what metrics the bot will track.
Test Configuration
python -c "import sys; sys.path.insert(0, 'src'); from config import Config; Config.validate()"
Alternative Chat ID Finder
# If the main script has issues
python utils/simple_chat_id.py
📖 Documentation
| Guide | Purpose | Quick Link |
|---|---|---|
| Setup Guide | 5-minute installation | 📖 docs/setup.md |
| Commands Reference | Complete command guide | 📖 docs/commands.md |
| Project Structure | Detailed architecture | 📖 docs/project-structure.md |
| Deployment Guide | Production deployment | 📖 docs/deployment.md |
| System Integration | Advanced integration | 📖 docs/system-integration.md |
| Documentation Index | All guides overview | 📖 docs/documentation-index.md |
🚨 Important Notes
Start with Testnet
- Bot defaults to testnet mode (safe testing)
- Get testnet keys from Hyperliquid Testnet
- Switch to mainnet only when fully tested
Your Keys
- API Generator Key: Generate a dedicated API key from Hyperliquid API Panel - NEVER use your wallet's private key directly
- Secret Key: May be optional depending on implementation
- Keep secure - never share your API keys or wallet credentials
- Best Practice: Use API keys with limited permissions for trading bots
Statistics Persistence
- ✅ YES - All statistics are permanently saved
- ✅ Survives restarts - data loads automatically
- ✅ Never lost - comprehensive backup via logging
🔍 Troubleshooting
Bot Won't Start
# Check configuration
python -c "import sys; sys.path.insert(0, 'src'); from config import Config; Config.validate()"
# Try alternative Chat ID finder
python utils/simple_chat_id.py
Telegram Issues
- Verify bot token from @BotFather
- Ensure you messaged your bot first
- Check Chat ID with utility scripts
Trading Problems
- Confirm sufficient balance
- Verify network connectivity
- Check logs in
logs/directory
🔥 Stop Loss Issues
- Enhanced detection automatically handles cancel/fill race conditions
- Grace period verification prevents premature cancellation
- Recent fill analysis ensures stop losses activate correctly
- Comprehensive logging provides full audit trail for troubleshooting
🎯 What Makes This Special
- 🚀 One command -
python trading_bot.pyruns everything - 📱 Professional mobile interface - institutional-grade phone trading
- 📊 Complete analytics - every metric you need from day one
- 🛡️ Bulletproof reliability - auto-restart with error notifications
- 💾 Never lose data - statistics persist forever
- ⚙️ CCXT compatible - follows industry standards
- 🧹 Clean organization - logical folder structure
- 📖 Complete documentation - guides for every use case
- 🔥 Enhanced stop loss management - bulletproof edge case handling
Get institutional-grade trading infrastructure with bulletproof stop loss management! 🚀📱🔥
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🎯 Key Features
Enhanced Trading Operations
- Multi-Platform Support: Direct integration with Hyperliquid perpetuals trading
- Smart Order Management: Long/short positions with market and limit orders
- 🔥 Bulletproof Stop Loss: Enhanced
sl:pricesyntax with edge case handling - Advanced Position Tracking: Multi-entry/exit scenarios with weighted average calculations
- Price Alerts: Real-time monitoring with customizable price alarms
- Integrated Analytics: Single source of truth for position tracking and performance analysis
- 🆕 Enhanced Risk Management: Automatic stop-loss with smart order reconciliation
System Architecture
- Unified Position Tracking: Integrated TradingStats system provides consistent position management
- Real-Time Notifications: Context-aware alerts for position opens, increases, reductions, and closes
- 🔥 Enhanced External Trade Detection: Automatic monitoring with bulletproof order linking
- Multi-Entry/Exit Support: Advanced tracking for complex trading scenarios with accurate P&L calculations
- 🆕 Smart Order Monitoring: Real-time fill detection with edge case handling
- Data Consistency: Single source of truth eliminates discrepancies between real-time and historical data
- Comprehensive Logging: Advanced log management with cleanup and statistics
- 🔥 Bulletproof Order Management: 3-second grace periods and recent fill verification