ManualTrader

🚀 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

📊 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

⚙️ 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

⚡ 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

ManualTrader/
├── 🚀 trading_bot.py              # MAIN LAUNCHER (run this!)
├── 📊 trading_stats.json          # Your persistent statistics  
├── 📝 .env                        # Your configuration
│
├── 🔧 src/                        # Core modules
│   ├── config.py                  # CCXT-style configuration
│   ├── hyperliquid_client.py      # Enhanced API wrapper
│   ├── telegram_bot.py            # Mobile-optimized interface
│   └── trading_stats.py           # Professional analytics
│
├── 🛠️ utils/                      # Setup & maintenance tools
│   ├── get_telegram_chat_id.py   # Robust Chat ID finder
│   ├── simple_chat_id.py         # Alternative for servers
│   ├── demo_stats.py             # See sample statistics
│   └── [other utilities]
│
├── ⚙️ config/                     # Configuration templates
├── 📋 logs/                       # Auto-created logs & errors
└── 📖 docs/                       # Organized documentation

📱 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

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

⚠️ 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	Codebase organization	📖 docs/project-structure.md
Deployment Guide	Production deployment	📖 docs/deployment.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

🎯 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

Get institutional-grade trading infrastructure with simple phone control! 🚀📱

📄 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
• Automatic Stop Loss: Inline sl:price syntax for automatic stop loss placement
• 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
• Risk Management: Automatic stop-loss functionality with customizable triggers

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
• External Trade Detection: Automatic monitoring and sync of trades made outside the bot
• Multi-Entry/Exit Support: Advanced tracking for complex trading scenarios with accurate P&L calculations
• 10-Second Monitoring: Real-time order fill detection and automatic stop loss placement
• Data Consistency: Single source of truth eliminates discrepancies between real-time and historical data
• Comprehensive Logging: Advanced log management with cleanup and statistics