trading_bot_v3/N8N_SETUP_GUIDE.md

# n8n Setup Guide for Trading Bot v4

## Quick Start

### Option 1: n8n Cloud (Easiest)

1. **Sign up** at https://n8n.io/cloud
2. **Import workflow**:
   - Go to **Workflows** → **Import from File**
   - Upload `n8n-workflow-v4.json`
3. **Set environment variables**:
   - Click **Settings** → **Variables**
   - Add these variables:

```
TRADINGVIEW_WEBHOOK_SECRET=your_secret_key_here
API_SECRET_KEY=your_api_key_here
TRADING_BOT_API_URL=https://your-bot-domain.com
TELEGRAM_CHAT_ID=your_telegram_chat_id
DISCORD_WEBHOOK_URL=your_discord_webhook
```

4. **Configure Telegram credentials**:
   - Go to **Credentials** → **Add Credential**
   - Select **Telegram**
   - Add your bot token from @BotFather

5. **Activate workflow**:
   - Toggle **Active** switch to ON
   - Copy webhook URL
   - Add to TradingView alert

### Option 2: Self-Hosted Docker

```bash
# Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3'

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=admin
      - N8N_BASIC_AUTH_PASSWORD=your_password_here
      - N8N_HOST=your-domain.com
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://your-domain.com/
      - GENERIC_TIMEZONE=America/New_York
    volumes:
      - ~/.n8n:/home/node/.n8n
EOF

# Start n8n
docker-compose up -d

# Check logs
docker-compose logs -f n8n
```

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

### Option 3: npm Global Install

```bash
npm install -g n8n
n8n start
```

## Environment Variables Setup

### In n8n Cloud/UI

1. Go to **Settings** → **Environments**
2. Add these variables:

| Variable | Value | Description |
|----------|-------|-------------|
| `TRADINGVIEW_WEBHOOK_SECRET` | `random_secret_123` | Secret for TradingView webhooks |
| `API_SECRET_KEY` | `your_api_key` | Auth for your trading bot API |
| `TRADING_BOT_API_URL` | `https://your-bot.com` | Your Next.js bot URL |
| `TELEGRAM_CHAT_ID` | `123456789` | Your Telegram chat ID |
| `DISCORD_WEBHOOK_URL` | `https://discord.com/api/webhooks/...` | Discord webhook URL |

### In Docker

Add to `docker-compose.yml` under `environment:`:

```yaml
- TRADINGVIEW_WEBHOOK_SECRET=random_secret_123
- API_SECRET_KEY=your_api_key
- TRADING_BOT_API_URL=https://your-bot.com
- TELEGRAM_CHAT_ID=123456789
- DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```

### In npm Install

Create `.env` file:

```bash
export TRADINGVIEW_WEBHOOK_SECRET=random_secret_123
export API_SECRET_KEY=your_api_key
export TRADING_BOT_API_URL=https://your-bot.com
export TELEGRAM_CHAT_ID=123456789
export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```

Then run:
```bash
source .env
n8n start
```

## Import Workflow

### Method 1: UI Import

1. Open n8n
2. Click **Workflows** → **Import from File**
3. Select `n8n-workflow-v4.json`
4. Click **Import**

### Method 2: API Import

```bash
curl -X POST http://localhost:5678/rest/workflows/import \
  -H "Content-Type: application/json" \
  -u admin:your_password \
  -d @n8n-workflow-v4.json
```

## Configure Credentials

### Telegram Bot

1. **Create bot** with @BotFather on Telegram:
   ```
   /newbot
   Trading Bot V4
   trading_bot_v4_bot
   ```

2. **Get bot token** from BotFather

3. **Get your chat ID**:
   - Send a message to your bot
   - Visit: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
   - Find `"chat":{"id":123456789}`

4. **Add credential in n8n**:
   - Go to **Credentials** → **Add Credential**
   - Select **Telegram**
   - Paste bot token
   - Save

### Discord Webhook (Optional)

1. **Create webhook** in Discord:
   - Go to Server Settings → Integrations → Webhooks
   - Click **New Webhook**
   - Name: "Trading Bot V4"
   - Copy webhook URL

2. **Add to n8n**:
   - Paste URL in `DISCORD_WEBHOOK_URL` variable

## Test Workflow

### Test with Manual Trigger

1. Open workflow in n8n
2. Click **Execute Workflow**
3. Send test webhook:

```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",
    "price": "100.50",
    "timestamp": "2025-10-23T10:00:00Z",
    "signal_type": "buy",
    "strength": "strong",
    "strategy": "5min_scalp_v4"
  }'
```

4. Check execution log in n8n

### Test from TradingView

1. Create alert in TradingView
2. Set webhook URL: `https://your-n8n.com/webhook/tradingview-signal?secret=YOUR_SECRET`
3. Trigger alert manually
4. Check n8n execution log

## Webhook URL Format

Your webhook URL will be:

**n8n Cloud:**
```
https://YOUR_USERNAME.app.n8n.cloud/webhook/tradingview-signal?secret=YOUR_SECRET
```

**Self-hosted:**
```
https://your-domain.com/webhook/tradingview-signal?secret=YOUR_SECRET
```

**Local testing:**
```
http://localhost:5678/webhook-test/tradingview-signal?secret=YOUR_SECRET
```

## Monitoring & Debugging

### View Execution Logs

1. Go to **Executions** in n8n
2. Click on any execution to see:
   - Input data
   - Output from each node
   - Errors
   - Execution time

### Enable Detailed Logging

Add to docker-compose.yml:
```yaml
- N8N_LOG_LEVEL=debug
- N8N_LOG_OUTPUT=console
```

### Webhook Testing Tools

Use these to test webhook:

**Postman:**
```
POST https://your-n8n.com/webhook/tradingview-signal?secret=YOUR_SECRET
Headers:
  Content-Type: application/json
Body:
  {
    "action": "buy",
    "symbol": "SOLUSDT",
    "timeframe": "5",
    "price": "100.50"
  }
```

**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","price":"100.50"}'
```

## Common Issues

### Webhook Not Receiving Data

**Check:**
1. Workflow is activated (toggle is ON)
2. Webhook URL is correct
3. Secret parameter is included
4. TradingView alert is active

**Test:**
```bash
# Test with curl
curl -v -X POST 'https://your-n8n.com/webhook/tradingview-signal?secret=test123' \
  -H 'Content-Type: application/json' \
  -d '{"test":"data"}'
```

### Authentication Errors

**Check:**
1. `API_SECRET_KEY` matches in n8n and Next.js
2. Authorization header is sent correctly
3. Trading bot API is accessible

**Test:**
```bash
# Test API directly
curl -X POST https://your-bot.com/api/trading/check-risk \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"SOL-PERP","direction":"long"}'
```

### Telegram Not Sending

**Check:**
1. Bot token is correct
2. Chat ID is correct
3. You sent a message to bot first
4. Bot is not blocked

**Test:**
```bash
# Send test message
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendMessage" \
  -d "chat_id=<YOUR_CHAT_ID>" \
  -d "text=Test message"
```

## Security Best Practices

1. **Use strong secrets**: Generate with `openssl rand -hex 32`
2. **Enable HTTPS**: Always use HTTPS in production
3. **Restrict access**: Use firewall rules to limit access
4. **Rotate keys**: Change secrets regularly
5. **Monitor logs**: Check for suspicious activity

## n8n Advanced Features for Trading Bot

### Useful n8n Nodes

1. **Function Node**: Custom JavaScript logic
2. **HTTP Request**: Call external APIs
3. **Telegram**: Send notifications
4. **Discord**: Alternative notifications
5. **Email**: Send email alerts
6. **Cron**: Schedule tasks (daily reports, cleanup)
7. **If Node**: Conditional logic
8. **Switch Node**: Multiple conditions
9. **Merge Node**: Combine data streams
10. **Set Node**: Transform data

### Add Daily Report Workflow

Create a separate workflow:

```
Cron (daily 11:59 PM)
  → HTTP Request (GET /api/trading/daily-stats)
  → Function (format report)
  → Telegram (send summary)
```

### Add Position Monitoring

Create monitoring workflow:

```
Cron (every 5 minutes)
  → HTTP Request (GET /api/trading/positions)
  → If (positions exist)
    → HTTP Request (check prices)
    → Function (calculate P&L)
    → If (alert condition met)
      → Telegram (send alert)
```

## Next Steps

1. ✅ Import workflow to n8n
2. ✅ Configure environment variables
3. ✅ Set up Telegram bot
4. ✅ Test webhook with curl
5. ✅ Connect TradingView alert
6. ✅ Test full flow
7. ✅ Set up monitoring

## Resources

- **n8n Docs**: https://docs.n8n.io
- **n8n Community**: https://community.n8n.io
- **Webhook Testing**: https://webhook.site
- **TradingView Alerts**: https://www.tradingview.com/support/solutions/43000529348

---

**Ready to automate! 🚀**