trading_bot_v4/docs/setup/README.md

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:

{
  "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:

{
  "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)

# 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)

# 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

# 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:

# 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:

# 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:

MIN_SIGNAL_QUALITY_SCORE_LONG=90    # LONG signals
MIN_SIGNAL_QUALITY_SCORE_SHORT=80   # SHORT signals (more permissive)

Adaptive Leverage:

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)

# 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)

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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.