# 🚀 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://github.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

### 📊 **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) |
| **[Commands Reference](docs/commands.md)** | **Complete command guide** | [📖 docs/commands.md](docs/commands.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! 🚀📱** 

## 🎯 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
- **Advanced Position Tracking**: Multi-entry/exit scenarios with weighted average calculations
- **Integrated Analytics**: Single source of truth for position tracking and performance analysis
- **Risk Management**: Automatic stop-loss functionality with customizable triggers

### 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
- **Multi-Entry/Exit Support**: Advanced tracking for complex trading scenarios with accurate P&L calculations
- **Data Consistency**: Single source of truth eliminates discrepancies between real-time and historical data