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
5705bf03c3
Increment BOT_VERSION to 2.2.150 and enhance notification messages for market orders.
|
il y a 9 heures | |
|---|---|---|
| config | il y a 17 heures | |
| docs | il y a 17 heures | |
| src | il y a 9 heures | |
| tests | il y a 3 jours | |
| utils | il y a 4 jours | |
| .gitignore | il y a 2 jours | |
| LICENSE | il y a 3 jours | |
| README.md | il y a 2 jours | |
| requirements.txt | il y a 4 jours | |
| reset_data.sh | il y a 2 jours | |
| trading_bot.py | il y a 9 heures |
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