# ⚡ Setup Guide

**5-minute setup for your Hyperliquid trading bot**

## 📋 Prerequisites

- Python 3.11+ installed
- Hyperliquid account (testnet or mainnet)
- Telegram account

## 🚀 Installation

### 1. Clone & Install
```bash
git clone git@repo.codeskraps.com:codeskraps/ManualTrader.git
cd ManualTrader

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Create Telegram Bot
1. **Message @BotFather** on Telegram
2. Send: `/newbot`
3. **Choose name**: "My Trading Bot"
4. **Choose username**: `mytradingbot_123_bot`
5. **Save the token** (format: `123456789:ABCdefGHIjklMNOPqrs`)

### 3. Get Your Chat ID
```bash
python utils/get_telegram_chat_id.py
```
- Enter your bot token
- **Message your bot** in Telegram (send "hello")
- **Copy the Chat ID** displayed in terminal

### 4. Configure Environment
```bash
cp config/env.example .env
nano .env  # Or use your preferred editor
```

**Required settings:**
```env
# Use API Generator Key from https://app.hyperliquid.xyz/API (NOT your wallet private key)
HYPERLIQUID_SECRET_KEY=your_api_generator_key_here
HYPERLIQUID_WALLET_ADDRESS=your_wallet_address_here
HYPERLIQUID_TESTNET=true

# From steps above
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
TELEGRAM_ENABLED=true
```

### 5. Start Trading
```bash
python trading_bot.py
```

**📱 Open Telegram → Send `/start` to your bot**

## 🔑 Getting Hyperliquid Keys

### API Keys (Recommended - SECURE)
1. Go to [Hyperliquid API Panel](https://app.hyperliquid.xyz/API)
2. Click "Generate API Key" or similar
3. **This creates TWO things**:
   - **API Wallet Address**: A NEW wallet address (0x...) different from your main wallet
   - **Secret Key**: The secret key for this API wallet
4. **NEVER use your main wallet's private key directly**
5. Set HYPERLIQUID_SECRET_KEY to the **Secret Key** from the API generator
6. Set HYPERLIQUID_WALLET_ADDRESS to the **API Wallet Address** from the API generator

**Important**: The API wallet address is DIFFERENT from your main MetaMask/wallet address!

### Testnet (Recommended First)
1. Go to [Hyperliquid Testnet](https://app.hyperliquid-testnet.xyz/)
2. Connect your main wallet
3. Go to API panel and generate API credentials
4. Use the API wallet address and secret key (not your main wallet credentials)
5. Use testnet settings in your `.env` file

### Mainnet (Real Money)
1. Go to [Hyperliquid](https://app.hyperliquid.xyz/)
2. Connect wallet
3. Generate API key from API panel

⚠️ **Security Best Practices:**
- Use API generator keys, NOT wallet private keys
- Keep API keys secure and never share them
- Use limited permissions when available
- Test on testnet first

## ✅ Verify Setup

```bash
# Test configuration
python -c "import sys; sys.path.insert(0, 'src'); from config import Config; Config.validate()"

# See sample statistics
python utils/demo_stats.py
```

## 🔧 Common Issues

### "Configuration validation failed"
- Check all required fields in `.env`
- Ensure `TELEGRAM_ENABLED=true`

### "Telegram bot not responding"
- Verify bot token with @BotFather
- Confirm Chat ID from script output
- Message your bot first before running script

### "Import error"
- Activate virtual environment: `source venv/bin/activate`
- Install dependencies: `pip install -r requirements.txt`

## 🎯 Next Steps

Once setup is complete:
- **Test with small amounts** on testnet first
- **Read the main README** for usage instructions
- **Check [Project Structure](project-structure.md)** to understand the codebase
- **Review [Deployment](deployment.md)** for production use

**Setup complete! Your bot is ready for phone trading 🚀📱**