trading_bot_v3/v4/N8N_WORKFLOW_GUIDE.md

# n8n Workflow Setup Guide - Trading Bot v4

Complete guide to set up the automated trading workflow in n8n.

---

## 🔐 Security Model (Simplified)

This workflow uses **ONE secret** for authentication:

**API_SECRET_KEY** - Authenticates n8n → v4 Trading Bot API
- Set in `v4/.env` (generate with: `openssl rand -hex 32`)
- Set in n8n environment variables (must match v4)
- Used when calling `/api/trading/check-risk` and `/api/trading/execute`

**Your TradingView webhook** (`https://flow.egonetix.de/webhook/tradingview-webhook`) is directly accessible. If you need additional security, use `n8n-workflow-complete.json` which includes optional TradingView secret validation.

---

## 📋 Workflow Overview

```
TradingView Alert (Webhook)
    ↓
Parse Signal (SOL/BTC/ETH, LONG/SHORT)
    ↓
Check Risk Limits (API call to /api/trading/check-risk)
    ↓
Execute Trade (API call to /api/trading/execute)
    ↓
Format Message (Success/Error/Blocked)
    ↓
Send Telegram Notification
```

**Two workflow versions available:**
- `n8n-workflow-simple.json` - **Recommended** - Direct flow without secret validation
- `n8n-workflow-complete.json` - With optional TradingView webhook secret validation

---

## 🚀 Quick Setup

### Step 1: Import Workflow

1. Open your n8n instance (e.g., https://flow.egonetix.de)
2. Click **"+ New Workflow"**
3. Click **"⋮"** (three dots) → **"Import from File"**
4. Select `n8n-workflow-simple.json` (recommended) or `n8n-workflow-complete.json`
5. Click **"Import"**

### Step 2: Configure Environment Variables

In n8n, go to **Settings** → **Environment Variables** and add:

```bash
# Your trading bot API URL (where v4 is running)
TRADING_BOT_API_URL=http://your-server:3000

# API secret key (must match v4/.env)
API_SECRET_KEY=your_secret_key_from_v4_env

# Telegram credentials
TELEGRAM_CHAT_ID=your_telegram_chat_id
```

**Note:** `TRADINGVIEW_WEBHOOK_SECRET` is only needed if using `n8n-workflow-complete.json`

### Step 3: Configure Telegram Credentials

1. In n8n, click **"Telegram - Send Notification"** node
2. Click **"Create New Credential"**
3. Enter your **Telegram Bot Token**
4. Save credential

### Step 4: Get Webhook URL

1. Click **"Webhook - TradingView Alert"** node
2. Click **"Test URL"** or **"Production URL"**
3. Copy the webhook URL (should be: `https://flow.egonetix.de/webhook/tradingview-webhook`)
4. Save this for TradingView setup

### Step 5: Activate Workflow

1. Toggle **"Active"** switch at top right
2. Workflow is now listening for webhooks!

---

## 🔧 Detailed Configuration

### Webhook Node Configuration

**Node:** `Webhook - TradingView Alert`

- **HTTP Method:** POST
- **Path:** `tradingview-webhook` (or customize)
- **Response:** Return on Last Node
- **Raw Body:** Enabled

**What it does:** Receives TradingView alerts directly via webhook

**Your webhook URL:** `https://flow.egonetix.de/webhook/tradingview-webhook`

### Parse TradingView Signal Node

**Node:** `Parse TradingView Signal`

- **Type:** Code (Function)
- **Language:** JavaScript

**What it does:** 
- Extracts symbol, action, timeframe from TradingView alert
- Normalizes data for v4 API (SOL→SOLUSDT, buy→long, etc.)
- Supports various TradingView alert formats

**Supported formats:**
```json
{
  "symbol": "SOLUSDT",
  "action": "buy",
  "timeframe": "5",
  "price": "140.25",
  "timestamp": "2025-10-23T10:00:00Z"
}
```

Or:
```json
{
  "ticker": "SOL-PERP",
  "signal_type": "long",
  "interval": "5m",
  "close": "140.25"
}
```

### Check Risk Limits Node

**Node:** `Check Risk Limits`

- **URL:** `{{$env.TRADING_BOT_API_URL}}/api/trading/check-risk`
- **Method:** POST
- **Headers:**
  - `Authorization: Bearer {{$env.API_SECRET_KEY}}`
  - `Content-Type: application/json`
- **Body:**
  ```json
  {
    "symbol": "{{$json.apiPayload.symbol}}",
    "direction": "{{$json.apiPayload.direction}}"
  }
  ```

**What it does:** 
- Checks daily drawdown limits
- Validates trades per hour
- Ensures cooldown period passed

### Execute Trade Node

**Node:** `Execute Trade on Drift`

- **URL:** `{{$env.TRADING_BOT_API_URL}}/api/trading/execute`
- **Method:** POST
- **Timeout:** 30000ms (30 seconds)
- **Headers:**
  - `Authorization: Bearer {{$env.API_SECRET_KEY}}`
  - `Content-Type: application/json`
- **Body:**
  ```json
  {
    "symbol": "SOLUSDT",
    "direction": "long",
    "timeframe": "5",
    "signalStrength": "strong",
    "signalPrice": 140.25
  }
  ```

**What it does:**
- Opens position on Drift Protocol
- Starts automatic monitoring
- Returns trade details (entry price, TP/SL levels)

### Format Message Nodes

**Three formatting nodes for different scenarios:**

1. **Format Success Message** - Trade executed successfully
2. **Format Error Message** - Trade execution failed
3. **Format Risk Blocked Message** - Trade blocked by risk limits

**Output example (Success):**
```
🟢 TRADE EXECUTED

📊 Symbol: SOL-PERP
📈 Direction: LONG
💰 Entry Price: $140.2350
💵 Position Size: $500.00
⚡ Leverage: 10x

🎯 Targets:
   Stop Loss: $137.90 (-1.5%)
   TP1: $140.98 (+0.7%)
   TP2: $142.10 (+1.5%)

📊 Slippage: 0.015%
⏰ Time: 10/23/2025, 10:00:00 AM

✅ Position is now being monitored automatically.
Auto-exit at TP/SL levels.
```

### Telegram Node

**Node:** `Telegram - Send Notification`

- **Chat ID:** `{{$env.TELEGRAM_CHAT_ID}}`
- **Text:** `{{$json.message}}`
- **Parse Mode:** Markdown

**What it does:** Sends formatted notification to your Telegram

---

## 🎯 TradingView Alert Setup

### Alert Configuration

1. **In TradingView:** Right-click chart → Add Alert
2. **Condition:** Your indicator/strategy (e.g., Green Dot appears)
3. **Alert Name:** "SOL Long Signal" (or similar)
4. **Webhook URL:** 
   ```
   https://flow.egonetix.de/webhook/tradingview-webhook
   ```
   
   **No secret parameter needed!** Just the direct webhook URL.

### Alert Message (JSON)

Use this format in the **Message** field:

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

**Important fields:**
- `symbol`: Stock/crypto symbol (SOLUSDT, BTCUSD, etc.)
- `action`: "buy"/"sell" or "long"/"short"
- `timeframe`: Chart interval (5, 15, 60, etc.)
- `price`: Current price from TradingView

### Notification Settings

✅ **Enable:**
- Webhook URL
- Notify on app
- Play sound (optional)

❌ **Disable:**
- Send email (n8n handles notifications)

---

## 🧪 Testing

### Test 1: Webhook Connection

```bash
# Send test webhook from command line
curl -X POST https://flow.egonetix.de/webhook/tradingview-webhook \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SOLUSDT",
    "action": "buy",
    "timeframe": "5",
    "price": "140.25",
    "timestamp": "2025-10-23T10:00:00Z"
  }'
```

### Test 2: Check n8n Executions

1. In n8n, click **"Executions"** tab
2. Find your test execution
3. Click to view detailed flow
4. Check each node for errors

### Test 3: Verify API Response

Expected response from `/api/trading/execute`:
```json
{
  "success": true,
  "trade": {
    "id": "trade-1234567890",
    "symbol": "SOL-PERP",
    "direction": "long",
    "entryPrice": 140.235,
    "positionSize": 500,
    "leverage": 10,
    "stopLoss": 137.90,
    "takeProfit1": 140.98,
    "takeProfit2": 142.10
  }
}
```

### Test 4: Telegram Message

You should receive a formatted Telegram message with trade details.

---

## 🔍 Troubleshooting

### Webhook Not Receiving Data

**Problem:** n8n workflow not triggering

**Solutions:**
1. Check webhook is **Active** (toggle at top)
2. Verify webhook URL in TradingView matches n8n: `https://flow.egonetix.de/webhook/tradingview-webhook`
3. Test with curl command (see Testing section)
4. Check n8n logs for errors

### Invalid Secret Error

**Problem:** "Unauthorized Webhook" message

**Solutions:**
- **Only applies if using `n8n-workflow-complete.json`**
- If using `n8n-workflow-simple.json`, this error won't occur

### API Authentication Failed

**Problem:** "401 Unauthorized" from trading bot

**Solutions:**
1. Verify `API_SECRET_KEY` in n8n matches v4 `.env`
2. Check `Authorization` header format: `Bearer YOUR_KEY`
3. Regenerate key if needed: `openssl rand -hex 32`

### Trade Not Executing

**Problem:** Risk check passed but no position opened

**Solutions:**
1. Check v4 API logs: `docker-compose logs -f trading-bot`
2. Verify Drift wallet has sufficient collateral
3. Check SOLANA_RPC_URL is working
4. Ensure DRIFT_WALLET_PRIVATE_KEY is correct
5. Test with curl:
   ```bash
   curl -X POST http://localhost:3000/api/trading/execute \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"symbol":"SOLUSDT","direction":"long","timeframe":"5"}'
   ```

### Telegram Not Sending

**Problem:** No Telegram notifications

**Solutions:**
1. Verify Telegram Bot Token in credentials
2. Check TELEGRAM_CHAT_ID is correct
3. Ensure bot is started (send /start to your bot)
4. Test Telegram node individually in n8n

---

## 📊 Monitoring

### View Executions

In n8n:
1. Click **"Executions"** tab
2. Filter by **"Success"** or **"Error"**
3. Click execution to see detailed flow

### Check Active Positions

Query via API:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/trading/positions
```

Or check Drift UI: https://drift.trade

### View Bot Logs

```bash
# Docker logs
docker-compose logs -f trading-bot

# Or if using scripts
cd v4 && ./docker-logs.sh
```

---

## 🔐 Security Best Practices

1. **Use Strong Secrets**
   ```bash
   # Generate secure random secrets
   openssl rand -hex 32  # For API keys
   openssl rand -hex 16  # For webhook secrets
   ```

2. **Protect Environment Variables**
   - Never commit `.env` files
   - Use n8n's environment variable encryption
   - Rotate secrets regularly

3. **IP Whitelisting** (optional)
   - Restrict webhook access to TradingView IPs
   - Use n8n's IP filtering if available

4. **Monitor Failed Attempts**
   - Set up alerts for unauthorized webhook attempts
   - Review n8n execution logs regularly

---

## 🎓 Advanced Configuration

### Custom Risk Parameters

Modify `Check Risk Limits` node to send additional parameters:

```json
{
  "symbol": "SOL-PERP",
  "direction": "long",
  "customPositionSize": 100,
  "customLeverage": 5
}
```

### Multiple Strategies

Clone the workflow for different strategies:
1. Duplicate workflow
2. Change webhook path: `/webhook/tradingview-5min` vs `/webhook/tradingview-15min`
3. Use different risk parameters per timeframe

### Advanced Notifications

Add Discord/Email nodes in parallel with Telegram:
1. Add Discord webhook node
2. Add SMTP email node
3. Connect all to message formatter nodes

---

## 📞 Support

**Workflow Issues:**
- Check n8n documentation: https://docs.n8n.io
- Review execution logs in n8n

**API Issues:**
- See `v4/TESTING.md` for API testing
- Check `v4/DOCKER.md` for container logs

**Trading Issues:**
- See `TRADING_BOT_V4_MANUAL.md` for complete guide
- Check Drift Protocol status

---

## ✅ Checklist

Before going live:

- [ ] Import workflow to n8n
- [ ] Configure all environment variables
- [ ] Add Telegram credentials
- [ ] Copy webhook URL
- [ ] Configure TradingView alert with webhook
- [ ] Test with small position size ($10-50)
- [ ] Verify Telegram notification received
- [ ] Check position opened on Drift
- [ ] Monitor first 5-10 trades closely
- [ ] Gradually increase position size

---

**Your automated trading system is now complete! 🎉**

When TradingView fires an alert → n8n executes the trade → You get a Telegram notification → Bot monitors and auto-exits at TP/SL!