# ๐Ÿš€ 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.

[![CCXT Compatible](https://img.shields.io/badge/CCXT-Compatible-green.svg)](https://github.com/ccxt/ccxt)
[![Testnet Safe](https://img.shields.io/badge/Testnet-Default-blue.svg)](#)
[![Mobile First](https://img.shields.io/badge/Mobile-Optimized-purple.svg)](https://repo.codeskraps.com/codeskraps/ManualTrader)
[![๐Ÿ”ฅ Enhanced](https://img.shields.io/badge/Stop%20Loss-Bulletproof-red.svg)](#)

## ๐ŸŽฏ 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