trading_bot_v3/TRADING_BOT_V4_MANUAL.md

# Trading Bot v4 - Complete Implementation Manual

## 🎯 Project Overview

**Trading Bot v4** is a fully automated 5-minute scalping system for Drift Protocol (Solana DEX) with the following features:

- **TradingView Signal Detection**: Green/red dot signals on 5-minute charts
- **Webhook-Driven Execution**: n8n workflow automation
- **10x Leverage Trading**: $1000 capital with tight risk management
- **Real-Time Monitoring**: Pyth Network price feeds (2-second updates)
- **Smart Exit Logic**: Partial profit-taking with trailing stops
- **Risk Management**: Daily limits, cooldown periods, and emergency stops

---

## 📋 Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Prerequisites](#prerequisites)
3. [Phase 1: TradingView Alert Setup](#phase-1-tradingview-alert-setup)
4. [Phase 2: n8n Workflow Configuration](#phase-2-n8n-workflow-configuration)
5. [Phase 3: Next.js Backend Setup](#phase-3-nextjs-backend-setup)
6. [Phase 4: Drift Protocol Integration](#phase-4-drift-protocol-integration)
7. [Phase 5: Price Monitoring System](#phase-5-price-monitoring-system)
8. [Phase 6: Trade Execution & Monitoring](#phase-6-trade-execution--monitoring)
9. [Phase 7: Testing & Deployment](#phase-7-testing--deployment)
10. [Configuration & Settings](#configuration--settings)
11. [Troubleshooting](#troubleshooting)

---

## 🏗️ Architecture Overview

```
┌─────────────────┐
│  TradingView    │
│  5min Chart     │
│  Green/Red Dots │
└────────┬────────┘
         │ Alert triggers
         ↓
┌─────────────────┐
│  TradingView    │
│  Webhook Alert  │
└────────┬────────┘
         │ POST request
         ↓
┌─────────────────────────────────────────┐
│           n8n Workflow                   │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │ 1. Webhook Receiver               │  │
│  └──────────┬───────────────────────┘  │
│             │                            │
│  ┌──────────▼───────────────────────┐  │
│  │ 2. Risk Check                     │  │
│  │    - Daily limits                 │  │
│  │    - Cooldown period              │  │
│  │    - Max trades/hour              │  │
│  └──────────┬───────────────────────┘  │
│             │                            │
│  ┌──────────▼───────────────────────┐  │
│  │ 3. Signal Validation              │  │
│  │    - Verify signal strength       │  │
│  │    - Check market conditions      │  │
│  └──────────┬───────────────────────┘  │
│             │                            │
│  ┌──────────▼───────────────────────┐  │
│  │ 4. Execute Trade (Next.js API)   │  │
│  └──────────┬───────────────────────┘  │
│             │                            │
│  ┌──────────▼───────────────────────┐  │
│  │ 5. Send Notifications             │  │
│  │    - Telegram                     │  │
│  │    - Discord                      │  │
│  │    - Email                        │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
         │
         ↓
┌─────────────────────────────────────────┐
│      Next.js Trading Bot API             │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │ POST /api/trading/execute         │  │
│  └──────────┬───────────────────────┘  │
│             │                            │
│  ┌──────────▼───────────────────────┐  │
│  │ Drift Trading Strategy            │  │
│  │  - Open position (market order)   │  │
│  │  - Set SL/TP targets              │  │
│  │  - Start monitoring               │  │
│  └──────────┬───────────────────────┘  │
│             │                            │
│  ┌──────────▼───────────────────────┐  │
│  │ Pyth Price Monitor                │  │
│  │  - WebSocket subscription         │  │
│  │  - 2-second polling fallback      │  │
│  │  - Real-time price updates        │  │
│  └──────────┬───────────────────────┘  │
│             │                            │
│  ┌──────────▼───────────────────────┐  │
│  │ Position Manager                  │  │
│  │  - Check exit conditions          │  │
│  │  - Execute market closes          │  │
│  │  - Update database                │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
         │
         ↓
┌─────────────────────────────────────────┐
│        Drift Protocol (Solana)           │
│                                          │
│  - Open/Close positions                  │
│  - 10x leverage perpetuals               │
│  - Real-time oracle prices (Pyth)        │
└─────────────────────────────────────────┘
```

---

## 🔧 Prerequisites

### Required Accounts & Services

1. **TradingView Pro/Premium** (for webhook alerts)
2. **n8n Instance** (cloud or self-hosted)
3. **Solana Wallet** with funded account
4. **Drift Protocol Account** (create at drift.trade)
5. **RPC Provider** (Helius, QuickNode, or Alchemy)
6. **Notification Services** (optional):
   - Telegram bot token
   - Discord webhook
   - Email SMTP

### Required Software

```bash
Node.js >= 18.x
npm or yarn
Docker (for deployment)
PostgreSQL (for trade history)
```

### Environment Variables

Create `.env.local`:

```bash
# Solana & Drift
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
DRIFT_WALLET_PRIVATE_KEY=your_base58_private_key
DRIFT_PROGRAM_ID=dRiftyHA39MWEi3m9aunc5MzRF1JYuBsbn6VPcn33UH

# n8n Integration
N8N_WEBHOOK_SECRET=your_random_secret_key_here
N8N_API_URL=https://your-n8n-instance.com

# Pyth Network
PYTH_HERMES_URL=https://hermes.pyth.network

# TradingView
TRADINGVIEW_WEBHOOK_SECRET=another_random_secret

# Risk Management
MAX_POSITION_SIZE_USD=1000
LEVERAGE=10
STOP_LOSS_PERCENT=-1.5
TAKE_PROFIT_1_PERCENT=0.7
TAKE_PROFIT_2_PERCENT=1.5
EMERGENCY_STOP_PERCENT=-2.0
MAX_DAILY_DRAWDOWN=-150
MAX_TRADES_PER_HOUR=6
MIN_TIME_BETWEEN_TRADES=600

# Notifications
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
DISCORD_WEBHOOK_URL=your_discord_webhook
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=587
EMAIL_FROM=your-email@gmail.com
EMAIL_TO=notification-email@gmail.com
EMAIL_PASSWORD=your_app_password

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/trading_bot_v4

# Monitoring
PRICE_CHECK_INTERVAL_MS=2000
```

---

## 📊 Phase 1: TradingView Alert Setup

### Step 1.1: Create Your Trading Strategy

Your 5-minute chart should have:
- Green dots = Buy signal (long)
- Red dots = Sell signal (short)

### Step 1.2: Configure Alert

1. Right-click on your chart → **Add Alert**
2. **Condition**: Your indicator with green/red dot logic
3. **Alert name**: `SOLUSDT.P Buy Signal` or `SOLUSDT.P Sell Signal`
4. **Message** (JSON format):

```json
{
  "action": "{{strategy.order.action}}",
  "symbol": "{{ticker}}",
  "timeframe": "{{interval}}",
  "price": "{{close}}",
  "timestamp": "{{timenow}}",
  "signal_type": "buy",
  "strength": "strong",
  "strategy": "5min_scalp_v4"
}
```

### Step 1.3: Configure Notifications Tab (see screenshot)

✅ **Enable these:**
- ✅ Notify in app
- ✅ Show toast notification  
- ✅ **Webhook URL** ← This is critical!
- ✅ Play sound

❌ **Disable these:**
- ❌ Send email (we'll use n8n for this)
- ❌ Send plain text

### Step 1.4: Set Webhook URL

**Webhook URL format:**
```
https://your-n8n-instance.com/webhook/tradingview-signal
```

Or if using n8n cloud:
```
https://your-username.app.n8n.cloud/webhook/tradingview-signal
```

**Important:** Add a secret parameter:
```
https://your-n8n-instance.com/webhook/tradingview-signal?secret=YOUR_SECRET_KEY
```

### Step 1.5: Test Alert

1. Click **Save** on alert
2. Manually trigger alert to test
3. Check n8n workflow execution logs

---

## 🔄 Phase 2: n8n Workflow Configuration

### Step 2.1: Install n8n

**Option A: Docker (Recommended)**
```bash
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  n8nio/n8n
```

**Option B: npm**
```bash
npm install -g n8n
n8n start
```

Access at: `http://localhost:5678`

### Step 2.2: Import Trading Bot Workflow

Create a new workflow with these nodes:

#### Node 1: Webhook Trigger
```json
{
  "name": "TradingView Signal",
  "type": "n8n-nodes-base.webhook",
  "typeVersion": 1,
  "position": [250, 300],
  "parameters": {
    "path": "tradingview-signal",
    "authentication": "headerAuth",
    "responseMode": "responseNode",
    "options": {}
  }
}
```

#### Node 2: Verify Secret
```javascript
// Function node
const secret = $json.query?.secret;
const expectedSecret = 'YOUR_SECRET_KEY'; // Use environment variable

if (secret !== expectedSecret) {
  throw new Error('Invalid webhook secret');
}

return {
  json: {
    verified: true,
    ...$json.body
  }
};
```

#### Node 3: Extract Signal Data
```javascript
// Function node
const signal = {
  action: $json.action || 'buy',
  symbol: $json.symbol || 'SOL-PERP',
  timeframe: $json.timeframe || '5',
  price: parseFloat($json.price) || 0,
  timestamp: $json.timestamp || new Date().toISOString(),
  signalType: $json.signal_type || 'buy',
  strength: $json.strength || 'moderate',
  strategy: $json.strategy || '5min_scalp_v4'
};

// Normalize symbol for Drift Protocol
if (signal.symbol.includes('SOL')) {
  signal.driftSymbol = 'SOL-PERP';
} else if (signal.symbol.includes('BTC')) {
  signal.driftSymbol = 'BTC-PERP';
} else if (signal.symbol.includes('ETH')) {
  signal.driftSymbol = 'ETH-PERP';
}

// Determine direction
signal.direction = signal.action === 'buy' ? 'long' : 'short';

return { json: signal };
```

#### Node 4: Risk Check API Call
```json
{
  "name": "Check Risk Limits",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 3,
  "position": [650, 300],
  "parameters": {
    "method": "POST",
    "url": "https://your-trading-bot.com/api/trading/check-risk",
    "authentication": "predefinedCredentialType",
    "nodeCredentialType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Authorization",
          "value": "Bearer YOUR_API_KEY"
        }
      ]
    },
    "sendBody": true,
    "bodyParameters": {
      "parameters": [
        {
          "name": "symbol",
          "value": "={{ $json.driftSymbol }}"
        }
      ]
    },
    "options": {}
  }
}
```

#### Node 5: IF Risk Passed
```json
{
  "name": "Risk Check Passed?",
  "type": "n8n-nodes-base.if",
  "typeVersion": 1,
  "position": [850, 300],
  "parameters": {
    "conditions": {
      "boolean": [
        {
          "value1": "={{ $json.allowed }}",
          "value2": true
        }
      ]
    }
  }
}
```

#### Node 6: Execute Trade
```json
{
  "name": "Execute Trade",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 3,
  "position": [1050, 250],
  "parameters": {
    "method": "POST",
    "url": "https://your-trading-bot.com/api/trading/execute",
    "authentication": "predefinedCredentialType",
    "nodeCredentialType": "httpHeaderAuth",
    "sendBody": true,
    "bodyParameters": {
      "parameters": [
        {
          "name": "symbol",
          "value": "={{ $json.driftSymbol }}"
        },
        {
          "name": "direction",
          "value": "={{ $json.direction }}"
        },
        {
          "name": "timeframe",
          "value": "={{ $json.timeframe }}"
        },
        {
          "name": "signalStrength",
          "value": "={{ $json.strength }}"
        }
      ]
    }
  }
}
```

#### Node 7: Send Success Notification (Telegram)
```json
{
  "name": "Telegram Success",
  "type": "n8n-nodes-base.telegram",
  "typeVersion": 1,
  "position": [1250, 200],
  "parameters": {
    "chatId": "={{ $env.TELEGRAM_CHAT_ID }}",
    "text": "🎯 Trade Executed!\n\n📊 Symbol: {{ $json.symbol }}\n📈 Direction: {{ $json.direction }}\n💰 Entry: ${{ $json.entryPrice }}\n🎲 Leverage: 10x\n⏱️ Time: {{ $json.timestamp }}\n\n✅ Position opened successfully"
  }
}
```

#### Node 8: Send Error Notification
```json
{
  "name": "Telegram Error",
  "type": "n8n-nodes-base.telegram",
  "typeVersion": 1,
  "position": [1050, 450],
  "parameters": {
    "chatId": "={{ $env.TELEGRAM_CHAT_ID }}",
    "text": "❌ Trade Blocked\n\n⚠️ Reason: {{ $json.reason }}\n📊 Symbol: {{ $json.symbol }}\n⏱️ Time: {{ $json.timestamp }}"
  }
}
```

#### Node 9: Webhook Response
```json
{
  "name": "Response",
  "type": "n8n-nodes-base.respondToWebhook",
  "typeVersion": 1,
  "position": [1450, 300],
  "parameters": {
    "respondWith": "json",
    "responseBody": "={{ JSON.stringify($json) }}"
  }
}
```

### Step 2.3: Save and Activate Workflow

1. Click **Save** button
2. Click **Active** toggle to enable
3. Copy webhook URL
4. Test with TradingView alert

### Step 2.4: Add Additional Notification Nodes (Optional)

**Discord Notification:**
```javascript
// HTTP Request node
{
  "method": "POST",
  "url": "YOUR_DISCORD_WEBHOOK_URL",
  "body": {
    "content": null,
    "embeds": [{
      "title": "🎯 New Trade Executed",
      "color": 5814783,
      "fields": [
        { "name": "Symbol", "value": "{{ $json.symbol }}", "inline": true },
        { "name": "Direction", "value": "{{ $json.direction }}", "inline": true },
        { "name": "Entry Price", "value": "${{ $json.entryPrice }}", "inline": true },
        { "name": "Stop Loss", "value": "${{ $json.stopLoss }}", "inline": true },
        { "name": "Take Profit 1", "value": "${{ $json.takeProfit1 }}", "inline": true },
        { "name": "Take Profit 2", "value": "${{ $json.takeProfit2 }}", "inline": true }
      ],
      "timestamp": "{{ $json.timestamp }}"
    }]
  }
}
```

**Email Notification:**
Use n8n's built-in Email node with HTML template

---

## 💻 Phase 3: Next.js Backend Setup

### Step 3.1: Create Required Files

Run this command to create the file structure:

```bash
mkdir -p lib/v4
mkdir -p app/api/trading
mkdir -p prisma
```

### Step 3.2: Update Prisma Schema

I'll create the database schema in the next step.

### Step 3.3: Install Dependencies

```bash
npm install @solana/web3.js @coral-xyz/anchor @drift-labs/sdk
npm install @pythnetwork/price-service-client
npm install @prisma/client
npm install ws # WebSocket support
npm install -D prisma
```

---

## 🚀 Phase 4: Drift Protocol Integration

I'll create the Drift integration files next.

---

## 📡 Phase 5: Price Monitoring System

Implementation of Pyth Network real-time price monitoring.

---

## 🎯 Phase 6: Trade Execution & Monitoring

Complete trading logic with risk management.

---

## 🧪 Phase 7: Testing & Deployment

Testing procedures and deployment guide.

---

## ⚙️ Configuration & Settings

### Risk Management Settings

```typescript
export const DEFAULT_RISK_CONFIG = {
  positionSize: 1000,        // $1000 per trade
  leverage: 10,              // 10x leverage = $10,000 position
  stopLossPercent: -1.5,     // -1.5% = -15% account loss
  takeProfit1Percent: 0.7,   // +0.7% = +7% account gain (50% close)
  takeProfit2Percent: 1.5,   // +1.5% = +15% account gain (50% close)
  emergencyStopPercent: -2.0, // -2% = -20% hard stop
  maxDailyDrawdown: -150,    // Stop trading at -$150 loss
  maxTradesPerHour: 6,       // Max 6 trades per hour
  minTimeBetweenTrades: 600, // 10 minutes cooldown
}
```

### Supported Markets

```typescript
const SUPPORTED_MARKETS = {
  'SOL-PERP': 0,   // Solana perpetual
  'BTC-PERP': 1,   // Bitcoin perpetual
  'ETH-PERP': 2,   // Ethereum perpetual
  // Add more markets as Drift adds them
}
```

---

## 🔍 Troubleshooting

### Common Issues

**1. Webhook not receiving alerts**
- Check TradingView alert is active
- Verify webhook URL is correct
- Check n8n workflow is activated
- Test webhook with curl:
```bash
curl -X POST https://your-n8n.com/webhook/tradingview-signal?secret=YOUR_SECRET \
  -H "Content-Type: application/json" \
  -d '{"action":"buy","symbol":"SOLUSDT","timeframe":"5"}'
```

**2. Trade execution fails**
- Check Solana wallet has sufficient SOL for gas
- Verify Drift account is initialized
- Check RPC endpoint is responding
- Review error logs in Next.js console

**3. Price monitoring not updating**
- Verify Pyth WebSocket connection
- Check RPC rate limits
- Review price cache timestamps
- Test with manual price fetch

**4. Position not closing at targets**
- Check price monitoring is active
- Verify exit condition logic
- Review slippage tolerance settings
- Check Drift market liquidity

---

## 📈 Expected Performance

Based on your strategy:

### Win Scenarios
- **Small wins (1%)**: ~60% of trades
- **Medium wins (1.5%)**: ~30% of trades  
- **Large wins (2%+)**: ~10% of trades

### Risk Per Trade
- **Max loss**: -$150 (-15% account)
- **Average loss**: -$100 (-10% account)
- **Win/Loss ratio**: Target 2:1

### Daily Targets
- **Trades per day**: 12-24 (based on 6/hour limit)
- **Target profit**: $200-400 daily (+20-40%)
- **Max drawdown**: -$150 (-15%)

---

## 🎓 Next Steps

After reading this manual, we'll implement:

1. ✅ Complete file structure (next message)
2. ✅ Database schema and migrations
3. ✅ Drift Protocol integration code
4. ✅ Pyth price monitoring system
5. ✅ Trade execution engine
6. ✅ n8n workflow export file
7. ✅ Testing scripts
8. ✅ Deployment guide

---

## 📞 Support & Resources

- **Drift Protocol Docs**: https://docs.drift.trade
- **Pyth Network Docs**: https://docs.pyth.network
- **n8n Docs**: https://docs.n8n.io
- **Solana Docs**: https://docs.solana.com

---

**Ready to implement? Let's build Trading Bot v4! 🚀**