# ๐ 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. [](https://github.com/ccxt/ccxt) [](#) [](https://repo.codeskraps.com/codeskraps/ManualTrader) [](#) ## ๐ฏ 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](https://github.com/ccxt/ccxt) - **Enhanced parameters** support for advanced trading - **Future-proof** architecture - **Professional configuration** management ## ๐ **Single Command Launch** ```bash 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** ```bash # 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** ```bash # Use the robust script python utils/get_telegram_chat_id.py ``` ### **3. Start Trading!** ```bash 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](docs/project-structure.md)** ## ๐ฑ **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](https://github.com/ccxt/ccxt) for exchange compatibility: > โ ๏ธ **IMPORTANT SECURITY**: Use the **API Generator Key** from [https://app.hyperliquid.xyz/API](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. ```env # 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** ```bash python utils/demo_stats.py ``` Shows you exactly what metrics the bot will track. ### **Test Configuration** ```bash python -c "import sys; sys.path.insert(0, 'src'); from config import Config; Config.validate()" ``` ### **Alternative Chat ID Finder** ```bash # If the main script has issues python utils/simple_chat_id.py ``` ## ๐ **Documentation** | Guide | Purpose | Quick Link | |-------|---------|------------| | **[Setup Guide](docs/setup.md)** | **5-minute installation** | [๐ docs/setup.md](docs/setup.md) | | **[Commands Reference](docs/commands.md)** | **Complete command guide** | [๐ docs/commands.md](docs/commands.md) | | **[Project Structure](docs/project-structure.md)** | **Detailed architecture** | [๐ docs/project-structure.md](docs/project-structure.md) | | **[Deployment Guide](docs/deployment.md)** | **Production deployment** | [๐ docs/deployment.md](docs/deployment.md) | | **[System Integration](docs/system-integration.md)** | **Advanced integration** | [๐ docs/system-integration.md](docs/system-integration.md) | | **[Documentation Index](docs/documentation-index.md)** | **All guides overview** | [๐ docs/documentation-index.md](docs/documentation-index.md) | ## ๐จ **Important Notes** ### **Start with Testnet** - Bot defaults to **testnet mode** (safe testing) - Get testnet keys from [Hyperliquid Testnet](https://app.hyperliquid-testnet.xyz/) - Switch to mainnet only when fully tested ### **Your Keys** - **API Generator Key**: Generate a dedicated API key from [Hyperliquid API Panel](https://app.hyperliquid.xyz/API) - **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** ```bash # 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](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