🚀 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
uv sync

# Configure bot
cp config/env.example .env
nano .env  # Add your keys

2. Get Telegram Chat ID

# Use the robust script
uv run python utils/get_telegram_chat_id.py

3. Start Trading!

uv run 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

uv run python utils/demo_stats.py

Shows you exactly what metrics the bot will track.

Test Configuration

uv run 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
uv run 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.py runs 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:price syntax 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

README.md 14 KB 履歴 Raw