# Setup Guides & Configuration

**Step-by-step guides for setting up trading bot components.**

This directory contains setup instructions for TradingView alerts, n8n workflows, external services, and infrastructure configuration.

---

## 🚀 Quick Setup Guides

### **Essential Setup (Required for Trading)**
- `SIGNAL_QUALITY_SETUP_GUIDE.md` - **Signal quality system**
  - TradingView alert configuration
  - Webhook payload format (ATR, ADX, RSI, volume, price position)
  - n8n Parse Signal Enhanced setup
  - Quality scoring thresholds
  - **Status:** ✅ PRODUCTION

- `N8N_MARKET_DATA_SETUP.md` - **1-minute data collection**
  - TradingView 1-minute alerts for market data cache
  - Webhook endpoint: `/api/trading/market-data`
  - Purpose: Smart Entry Validation Queue price updates
  - Alert frequency: Every 1-5 minutes
  - **Status:** ✅ ACTIVE

### **Infrastructure Setup**
- `EPYC_SETUP_COMPREHENSIVE.md` - **EPYC cluster configuration**
  - SSH configuration (nested hop through worker1)
  - Python environment setup (3.11.2 + pandas + numpy)
  - Package deployment (tar.gz transfer)
  - Worker initialization scripts
  - **Location:** Also in `../cluster/` directory
  - **Status:** ✅ OPERATIONAL

### **Development Setup**
- `QUICK_SETUP_CARD.md` - **Development environment**
  - Docker Compose configuration
  - Environment variables (.env file)
  - Database initialization (PostgreSQL + Prisma)
  - Local testing procedures
  - **Status:** ✅ CURRENT

---

## 📋 TradingView Alert Setup

### **Production Trading Signals (5-minute chart)**

**Alert Message Format:**
```json
{
  "action": "{{strategy.order.action}}",
  "symbol": "{{ticker}}",
  "timeframe": "{{interval}}",
  "currentPrice": {{close}},
  "atr": {{ta.atr(14)}},
  "adx": {{ta.dmi(14, 14)}},
  "rsi": {{ta.rsi(14)}},
  "volumeRatio": {{volume / ta.sma(volume, 20)}},
  "pricePosition": {{(close - ta.lowest(low, 100)) / (ta.highest(high, 100) - ta.lowest(low, 100)) * 100}},
  "indicatorVersion": "v9"
}
```

**Alert Settings:**
- **Condition:** Strategy entry/exit
- **Trigger:** Once Per Bar Close
- **Expiration:** None (always active)
- **Webhook URL:** `https://your-domain.com/api/trading/execute`

**Required Fields:**
- ✅ `atr` - ATR-based TP/SL system (CRITICAL)
- ✅ `adx` - Trend strength filtering
- ✅ `rsi` - Momentum confirmation
- ✅ `volumeRatio` - Volume validation
- ✅ `pricePosition` - Range position (0-100%)
- ✅ `timeframe` - Distinguishes 5min (trade) vs 15min/1H (data collection)
- ✅ `indicatorVersion` - Track strategy performance (v9 current)

### **Market Data Alerts (1-minute chart)**

**Alert Message Format:**
```json
{
  "action": "market_data",
  "symbol": "{{ticker}}",
  "timeframe": "{{interval}}",
  "currentPrice": {{close}},
  "atr": {{ta.atr(14)}},
  "adx": {{ta.dmi(14, 14)}},
  "rsi": {{ta.rsi(14)}},
  "volumeRatio": {{volume / ta.sma(volume, 20)}},
  "pricePosition": {{(close - ta.lowest(low, 100)) / (ta.highest(high, 100) - ta.lowest(low, 100)) * 100}}
}
```

**Alert Settings:**
- **Condition:** Time trigger (every bar close)
- **Trigger:** Once Per Bar Close
- **Expiration:** None
- **Webhook URL:** `https://your-domain.com/api/trading/market-data`

**Purpose:**
- Updates market data cache for Smart Entry Validation Queue
- Provides fresh prices for re-entry validation
- Enables sub-5-minute confirmation thresholds

---

## 🔧 n8n Workflow Setup

### **Parse Signal Enhanced**

**Location:** `workflows/trading/parse_signal_enhanced.json`

**Functions:**
1. **Extract Metrics:** ADX, ATR, RSI, volume, price position
2. **Normalize Timeframe:** "5", "15", "60", "240", "D"
3. **Extract Indicator Version:** "IND:v9" → "v9"
4. **Detect MA Crossovers:** "crossing" keyword → flags
5. **Route to Execute:** Calls `/api/trading/execute`

**Key Nodes:**
- HTTP Request node → Receives TradingView webhook
- Code node → Parses JSON payload
- Set node → Normalizes field names
- HTTP Request node → Sends to execute endpoint

### **Market Data Collector**

**Location:** `workflows/trading/market_data_collector.json`

**Functions:**
1. Receives 1-minute TradingView alerts
2. Validates symbol format (SOLUSDT → SOL-PERP)
3. Updates market data cache via `/api/trading/market-data`
4. Logs cache update timestamp

---

## 🗄️ Database Setup

### **Initial Setup (First Time)**
```bash
# 1. Start PostgreSQL container
cd /home/icke/traderv4
docker compose up -d trading-bot-postgres

# 2. Generate Prisma client
npx prisma generate

# 3. Run migrations
DATABASE_URL="postgresql://postgres:your_password@localhost:5432/trading_bot_v4" \
npx prisma migrate dev

# 4. Verify tables created
docker exec trading-bot-postgres psql -U postgres -d trading_bot_v4 -c "\\dt"
```

### **Schema Updates (After Code Changes)**
```bash
# 1. Generate migration
DATABASE_URL="postgresql://...@localhost:5432/..." \
npx prisma migrate dev --name describe_changes_here

# 2. Regenerate client
npx prisma generate

# 3. Rebuild Docker image (includes new Prisma client)
docker compose build trading-bot

# 4. Restart container
docker compose up -d --force-recreate trading-bot
```

### **Database Backup**
```bash
# Backup to SQL file
docker exec trading-bot-postgres pg_dump -U postgres trading_bot_v4 > backup_$(date +%Y%m%d_%H%M%S).sql

# Restore from backup
cat backup_file.sql | docker exec -i trading-bot-postgres psql -U postgres -d trading_bot_v4
```

---

## 🔐 Environment Variables Setup

### **Required Variables (.env file)**

**Trading Configuration:**
```bash
# Drift Protocol (REQUIRED)
DRIFT_WALLET_PRIVATE_KEY="[91,24,...]"  # JSON array or base58
API_SECRET_KEY="your-secret-key-here"

# Solana RPC (REQUIRED - use Helius!)
SOLANA_RPC_URL="https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"
BACKUP_RPC_URL="https://api.mainnet-beta.solana.com"

# Database (REQUIRED)
DATABASE_URL="postgresql://postgres:password@trading-bot-postgres:5432/trading_bot_v4"
POSTGRES_PASSWORD="your-secure-password"

# Telegram (REQUIRED for notifications)
TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
TELEGRAM_CHAT_ID="123456789"
```

**Position Sizing:**
```bash
# Per-Symbol Configuration
SOLANA_ENABLED=true
SOLANA_POSITION_SIZE=100        # Percentage (1-100)
SOLANA_LEVERAGE=15              # Leverage multiplier

ETHEREUM_ENABLED=false
ETHEREUM_POSITION_SIZE=100
ETHEREUM_LEVERAGE=1

# Global Fallback (BTC, etc.)
MAX_POSITION_SIZE_USD=100
LEVERAGE=1
```

**Quality Thresholds:**
```bash
MIN_SIGNAL_QUALITY_SCORE_LONG=90    # LONG signals
MIN_SIGNAL_QUALITY_SCORE_SHORT=80   # SHORT signals (more permissive)
```

**Adaptive Leverage:**
```bash
USE_ADAPTIVE_LEVERAGE=true
HIGH_QUALITY_LEVERAGE=10            # Quality ≥ threshold
LOW_QUALITY_LEVERAGE=5              # Quality < threshold
QUALITY_LEVERAGE_THRESHOLD_LONG=95  # LONG threshold
QUALITY_LEVERAGE_THRESHOLD_SHORT=90 # SHORT threshold
```

**See:** `../.github/copilot-instructions.md` Environment Variable Reference for complete list (100+ variables)

---

## 🐳 Docker Setup

### **Development (docker-compose.dev.yml)**
```bash
# Start all services
docker compose -f docker-compose.dev.yml up -d

# View logs
docker compose -f docker-compose.dev.yml logs -f trading-bot

# Stop all services
docker compose -f docker-compose.dev.yml down
```

### **Production (docker-compose.yml)**
```bash
# Build and start
docker compose up -d --build trading-bot

# Restart with force recreate
docker compose up -d --force-recreate trading-bot

# Check status
docker compose ps
docker logs -f trading-bot-v4
```

### **Telegram Bot (docker-compose.telegram-bot.yml)**
```bash
# Start Telegram bot
docker compose -f docker-compose.telegram-bot.yml up -d

# View logs
docker logs -f trading-bot-telegram

# Test command
# Send "long sol" to Telegram bot
```

---

## 🧪 Testing Setup

### **Test Trade Execution**
```bash
# Via Settings UI
# 1. Open http://localhost:3001/settings
# 2. Scroll to "Test Trading" section
# 3. Click "Test SOL LONG" or "Test SOL SHORT"
# 4. Monitor docker logs for execution

# Via Telegram Bot
# Send message: "long sol --force"
# Watch for confirmation message
```

### **Verify Position Manager**
```bash
# 1. Execute test trade
# 2. Watch logs for monitoring cycle
docker logs -f trading-bot-v4 | grep -E "Position Manager|TP1|TP2|SL"

# 3. Check database
docker exec trading-bot-postgres psql -U postgres -d trading_bot_v4 -c \
  "SELECT symbol, direction, entryPrice, currentSize, tp1Hit FROM \"Trade\" WHERE exitReason IS NULL;"
```

### **API Health Checks**
```bash
# Drift account health
curl http://localhost:3001/api/drift/account-health

# Market data cache
curl http://localhost:3001/api/trading/market-data

# Cluster status
curl http://localhost:3001/api/cluster/status

# Analytics
curl http://localhost:3001/api/analytics/last-trade
```

---

## 🛠️ Troubleshooting

### **Container Won't Start**
```bash
# Check logs for errors
docker logs trading-bot-v4

# Common issues:
# - DATABASE_URL incorrect (check connection string)
# - DRIFT_WALLET_PRIVATE_KEY format (JSON array or base58)
# - Port 3000 already in use (check with: lsof -i :3000)
```

### **TradingView Alerts Not Received**
```bash
# 1. Check n8n workflow execution log
# 2. Test webhook manually:
curl -X POST http://localhost:5678/webhook/parse-signal \
  -H "Content-Type: application/json" \
  -d '{"action":"buy","symbol":"SOLUSDT","timeframe":"5",...}'

# 3. Verify webhook URL in TradingView alert settings
# 4. Check firewall allows incoming webhooks
```

### **Database Connection Failed**
```bash
# 1. Verify PostgreSQL running
docker ps | grep postgres

# 2. Test connection
docker exec trading-bot-postgres psql -U postgres -c "SELECT 1"

# 3. Check DATABASE_URL matches container name
# Runtime: postgresql://postgres:pass@trading-bot-postgres:5432/...
# Prisma CLI: postgresql://postgres:pass@localhost:5432/...
```

### **RPC Rate Limiting (429 Errors)**
```bash
# Symptom: Logs show "429 Too Many Requests"
# Fix: Switch to Helius RPC (higher rate limits)
# Update .env:
SOLANA_RPC_URL="https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"

# Restart container
docker compose restart trading-bot
```

---

## 📚 Additional Resources

**External Documentation:**
- Drift Protocol: https://docs.drift.trade
- Pyth Network: https://docs.pyth.network
- Helius RPC: https://docs.helius.dev
- TradingView Alerts: https://www.tradingview.com/support/solutions/43000529348

**Internal Documentation:**
- **Main README:** `../README.md`
- **Architecture:** `../architecture/` directory
- **Roadmaps:** `../roadmaps/` directory
- **Common Pitfalls:** `../.github/copilot-instructions.md`

---

See `../README.md` for overall documentation structure.