# 📱 Manual Hyperliquid Trading Bot

**Control your Hyperliquid account from your phone with comprehensive trading statistics**

This bot provides complete manual control of your Hyperliquid account via Telegram, with professional-grade statistics tracking including P&L, win rates, Sharpe ratio, Sortino ratio, and all the metrics you'd expect from a trading platform.

## 🎯 What This Bot Does

- 📱 **Phone Control**: Trade from anywhere using Telegram commands
- 📊 **Comprehensive Stats**: Track all your performance metrics from day one
- 💰 **Balance Tracking**: Monitor starting vs current balance with real-time P&L
- 🏆 **Performance Metrics**: Win rate, profit factor, expectancy, consecutive wins/losses
- 📈 **Risk Analysis**: Sharpe ratio, Sortino ratio, max drawdown, VaR (95%)
- 🔄 **Trade History**: Complete trade logging with automatic P&L calculation
- 🛡️ **Safety First**: Order confirmations, testnet mode, comprehensive logging

## 🚀 Quick Start

### 1. Install Dependencies
```bash
# Clone or download this repository
cd trader_hyperliquid

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Set Up Telegram Bot
1. **Create a bot**: Message [@BotFather](https://t.me/BotFather) on Telegram
   - Send `/newbot`
   - Choose a name and username for your bot
   - Save the bot token

2. **Get your Chat ID**: Run the helper script
   ```bash
   python get_telegram_chat_id.py
   ```
   - Start the script and message your bot
   - Copy the displayed Chat ID

### 3. Configure Environment
```bash
# Copy example configuration
cp env.example .env

# Edit .env with your details
nano .env  # or use any text editor
```

**Required settings in `.env`:**
```env
# Hyperliquid API
HYPERLIQUID_PRIVATE_KEY=your_private_key_here
HYPERLIQUID_TESTNET=true

# Telegram Bot
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# Trading Settings
DEFAULT_TRADING_SYMBOL=BTC/USDC:USDC
DEFAULT_TRADE_AMOUNT=0.001
```

### 4. Start Manual Trading
```bash
python manual_trading_bot.py
```

## 📱 Using Your Trading Bot

### Quick Actions (Buttons)
Open Telegram → Find your bot → Send `/start`

You'll see quick action buttons for:
- 💰 **Balance** - Check account balance with P&L
- 📊 **Stats** - Complete trading statistics  
- 📈 **Positions** - Open positions with unrealized P&L
- 📋 **Orders** - Pending orders
- 💵 **Price** - Current market price
- 🔄 **Recent Trades** - Your trade history

### Manual Trading Commands

**Place Orders:**
```
/buy 0.001 50000    # Buy 0.001 BTC at $50,000
/sell 0.001 55000   # Sell 0.001 BTC at $55,000
```

**Monitor Account:**
```
/balance     # Account balance + P&L summary
/positions   # Open positions
/orders      # Pending orders
/trades      # Recent trade history
```

**View Statistics:**
```
/stats       # Complete trading statistics
```

## 📊 Trading Statistics Tracked

### Balance & P&L
- 💰 **Starting Balance**: Recorded when bot first launches
- 💵 **Current Balance**: Real-time balance updates
- 📈 **Total P&L**: Profit/Loss in USD and percentage
- 📅 **Days Active**: Time since first launch

### Performance Metrics  
- 🏆 **Win Rate**: Percentage of profitable trades
- 💎 **Profit Factor**: Total gains ÷ Total losses
- �� **Average Win/Loss**: Mean profit/loss per trade
- 🎯 **Expectancy**: Expected value per trade
- 🔥 **Consecutive Wins/Losses**: Streak tracking

### Risk Metrics
- 📊 **Sharpe Ratio**: Risk-adjusted returns
- 📉 **Sortino Ratio**: Downside risk-adjusted returns  
- 📈 **Max Drawdown**: Largest peak-to-trough decline
- 🌪️ **Volatility**: Annualized price volatility
- ⚠️ **VaR (95%)**: Value at Risk (95% confidence)

### Trade Analytics
- 📝 **Total Trades**: Complete trade count
- 🔄 **Buy/Sell Breakdown**: Order type distribution
- 🎯 **Best/Worst Trades**: Largest wins and losses
- 📊 **Trade History**: Complete audit trail with order IDs

## 🛡️ Safety Features

### Testnet First
- Starts in testnet mode by default
- Test all features before using real money
- Clear warnings when switching to mainnet

### Order Confirmations
- All trades require explicit confirmation
- Clear order details before execution
- Easy cancellation option

### Comprehensive Logging
- All actions logged with timestamps
- Trade history automatically saved
- Statistics persist between bot restarts

### Risk Management
- Balance tracking for drawdown monitoring
- Real-time P&L calculations
- Risk metrics to assess performance

## 📈 Sample Statistics Output

```
📊 Trading Statistics

💰 Balance Overview
• Initial: $1,000.00
• Current: $1,150.00  
• Total P&L: $150.00
• Total Return: 15.00%

📈 Trading Activity
• Total Trades: 25
• Buy Orders: 13
• Sell Orders: 12
• Days Active: 30

🏆 Performance Metrics
• Win Rate: 68.0%
• Profit Factor: 2.15
• Avg Win: $45.50
• Avg Loss: $28.75
• Expectancy: $6.25

📊 Risk Metrics
• Sharpe Ratio: 1.85
• Sortino Ratio: 2.41
• Max Drawdown: 8.5%
• Volatility: 12.3%
• VaR (95%): 3.2%

🎯 Best/Worst
• Largest Win: $125.00
• Largest Loss: $75.00
• Max Consecutive Wins: 5
• Max Consecutive Losses: 2

📅 Since: 2024-01-15
```

## 🔧 Files Overview

| File | Purpose |
|------|---------|
| `manual_trading_bot.py` | **Main launcher** - Start this for manual trading |
| `telegram_bot.py` | Telegram interface with trading commands |
| `trading_stats.py` | Comprehensive statistics tracking |
| `hyperliquid_client.py` | Hyperliquid API wrapper |
| `config.py` | Configuration management |
| `get_telegram_chat_id.py` | Helper to find your Chat ID |
| `trading_stats.json` | Your trading statistics (auto-created) |

## ⚙️ Advanced Configuration

### Custom Trading Symbol
```env
DEFAULT_TRADING_SYMBOL=ETH/USDC:USDC
```

### Adjust Default Trade Size
```env
DEFAULT_TRADE_AMOUNT=0.01
```

### Logging Level
```env
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
```

## 🔍 Troubleshooting

### Bot Won't Start
```bash
# Check configuration
python -c "from config import Config; Config.validate()"

# Check Telegram setup
python get_telegram_chat_id.py
```

### Telegram Not Responding
1. Verify bot token with BotFather
2. Ensure Chat ID is correct
3. Check that bot is started in Telegram

### Trading Issues
1. Confirm sufficient balance
2. Check order parameters
3. Verify network connectivity

## 🌐 Network Modes

### Testnet (Default)
- Safe testing environment
- No real money at risk
- Perfect for learning

### Mainnet (Production)
- Real money trading
- Requires explicit confirmation
- Use with caution

## 📞 Support

This bot is designed for manual trading control via phone. All features are focused on giving you complete control over your Hyperliquid account with professional-grade statistics tracking.

For technical issues:
1. Check configuration with validation commands
2. Review log files for error details
3. Ensure all dependencies are installed

**Happy trading! 🚀📱**