chore: Organize workspace structure - move docs, workflows, scripts to subdirectories
Organization: - Created docs/ with setup/, guides/, history/ subdirectories - Created workflows/ with trading/, analytics/, telegram/, archive/ subdirectories - Created scripts/ with docker/, setup/, testing/ subdirectories - Created tests/ for TypeScript test files - Created archive/ for unused reference files Moved files: - 17 documentation files → docs/ - 16 workflow JSON files → workflows/ - 10 shell scripts → scripts/ - 4 test files → tests/ - 5 unused files → archive/ Updated: - README.md with new file structure and documentation paths Deleted: - data/ (empty directory) - screenshots/ (empty directory) Critical files remain in root: - telegram_command_bot.py (active bot - used by Dockerfile) - watch-restart.sh (systemd service dependency) - All Dockerfiles and docker-compose files - All environment files Validation: Containers running (trading-bot-v4, telegram-trade-bot, postgres) API responding (positions endpoint tested) Telegram bot functional (/status command tested) All critical files present in root No code changes - purely organizational. System continues running without interruption. Recovery: git revert HEAD or git reset --hard cleanup-before
This commit is contained in:
mindesbunister
505
docs/guides/N8N_WORKFLOW_GUIDE.md
Normal file
505
docs/guides/N8N_WORKFLOW_GUIDE.md
Normal file
@@ -0,0 +1,505 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user