# ⚡ 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_PRIVATE_KEY=your_api_generator_key_here
HYPERLIQUID_WALLET_ADDRESS=your_wallet_address_here
HYPERLIQUID_SECRET_KEY=your_secret_key_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. Generate a dedicated API key for trading
3. **NEVER use your wallet's private key directly**
4. Copy your wallet address (0x...) from your wallet interface
5. Use both the generated API key and wallet address in your `.env` file

### Testnet (Recommended First)
1. Go to [Hyperliquid Testnet](https://app.hyperliquid-testnet.xyz/)
2. Connect/create wallet
3. Note your wallet address from the wallet interface
4. Generate API key from API panel
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 🚀📱**