# 🚀 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