# ๐ 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) [](#) [](#) ## ๐ฏ 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](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 ## โก **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** ``` 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** ``` /buy 0.001 50000 # Buy 0.001 BTC at $50,000 /sell 0.001 55000 # Sell 0.001 BTC at $55,000 ``` ### **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: ```env # Hyperliquid API (CCXT Style) HYPERLIQUID_PRIVATE_KEY=your_private_key_here HYPERLIQUID_SECRET_KEY=your_secret_key_here 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** ```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) | | **[Project Structure](docs/project-structure.md)** | **Codebase organization** | [๐ docs/project-structure.md](docs/project-structure.md) | | **[Deployment Guide](docs/deployment.md)** | **Production deployment** | [๐ docs/deployment.md](docs/deployment.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** - **Private Key**: From Hyperliquid account settings - **Secret Key**: May be optional depending on implementation - **Keep secure** - never share your private keys ### **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 ## ๐ฏ **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! ๐๐ฑ**