ManualTrader/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

1. Verify bot token from @BotFather
2. Ensure you messaged your bot first
3. Check Chat ID with utility scripts

Trading Problems

1. Confirm sufficient balance
2. Verify network connectivity
3. 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