trading_bot_v4/docs/guides/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:

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

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

Or:

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

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

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

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

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

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

   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:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3000/api/trading/positions

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

View Bot Logs

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

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

---

🔐 Security Best Practices

1. Use Strong Secrets

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

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