Home

GitHub Wiki Documentation

This document contains the content for the project's GitHub Wiki. You can copy each section into a separate page in your GitHub Wiki or keep it as a single reference.

---

🏠 Home

Welcome to the TradingView Webhook Bot Wiki!

This wiki serves as the comprehensive documentation for the TradingView Webhook Bot. Here you will find detailed guides on installation, configuration, usage, and troubleshooting.

📚 Contents

1. Installation Guide: Step-by-step instructions to get the bot running.
2. Configuration: Detailed explanation of all environment variables.
3. TradingView Setup: How to configure alerts to trigger the bot.
4. User Guide: Telegram commands and bot management.
5. Architecture: Technical overview for developers.
6. Troubleshooting: Common issues and solutions.

---

🚀 Installation Guide

You can run the bot using Docker (recommended) or Python.

Prerequisites

• A Virtual Private Server (VPS) with a public IP.
• Docker & Docker Compose installed.
• A Binance Futures account.

Method 1: Docker (Recommended)

1. Clone the Repository

   git clone https://github.com/beydah/TradingView-Webhook-Bot.git
   cd TradingView-Webhook-Bot

2. Setup Configuration

   cp .env.example .env
   nano .env

   Fill in your API keys and settings (see Configuration).

3. Run the Bot

   docker-compose up -d --build

4. Verify Check if the container is running:

   docker ps

   View logs:

   docker logs -f binance-bot

Method 2: Manual (Python)

1. Install Python 3.10+

   sudo apt update && sudo apt install python3 python3-pip python3-venv

2. Create Virtual Environment

   python3 -m venv venv
   source venv/bin/activate

3. Install Dependencies

   pip install -r requirements.txt

4. Run

   python main.py

---

⚙️ Configuration

The bot is configured via the .env file. Do not share this file!

Variable	Required	Description	Example
TELEGRAM_BOT_TOKEN	✅	Token from @BotFather	123456:ABC-DEF...
TELEGRAM_USER_ID	✅	Your Telegram ID from @userinfobot	123456789
BINANCE_API_KEY	✅	Binance Futures API Key	vmPUZE...
BINANCE_SECRET_KEY	✅	Binance Futures Secret Key	NhqPt...
ALERT_KEY	✅	Secret password for Webhook validation	SecretPassword123
WEBHOOK_IP	❌	IP to bind (Default: 0.0.0.0)	0.0.0.0
WEBHOOK_PORT	❌	Port to listen on (Default: 80)	80
BINANCE_TESTNET	❌	Set 'True' to use Testnet	False

---

📈 TradingView Setup

To automate trades, you need to send Webhooks from TradingView to your bot.

1. Create an Alert

On your TradingView chart, click the Alert icon or press Alt + A.

2. Configure Webhook

In the Webhook URL field, enter your server's address: http://YOUR_VPS_IP/webhook

Tip: If you are using port 80 (default), you don't need to specify it. If you used port 5000, use http://YOUR_VPS_IP:5000/webhook.

3. Set the Message (JSON)

The bot expects a specific JSON format in the Message box.

Open Long Position

{
  "symbol": "BTCUSDT",
  "alert": "long_open",
  "price": {{close}},
  "key": "SecretPassword123"
}

Close Long Position

{
  "symbol": "BTCUSDT",
  "alert": "long_close",
  "price": {{close}},
  "key": "SecretPassword123"
}

Open Short Position

{
  "symbol": "BTCUSDT",
  "alert": "short_open",
  "price": {{close}},
  "key": "SecretPassword123"
}

Close Short Position

{
  "symbol": "BTCUSDT",
  "alert": "short_close",
  "price": {{close}},
  "key": "SecretPassword123"
}

Note: Replace SecretPassword123 with the ALERT_KEY from your .env file.

---

📱 User Guide (Telegram)

You can control the bot entirely from Telegram.

Commands

• /start - Wake Up: Starts the bot and shows the menu.
• /help - Help: Lists all available commands.
• /getpos - Positions: Fetches current open positions from Binance.
• /getwallet - Balance: Shows your Futures wallet balance (USDT) and margin usage.
• /getalert - Alerts: Displays the last 20 alerts received from TradingView.
• /getlog - Logs: Generates a text file with the latest bot logs and sends it to you.

Notifications

The bot will automatically send you messages when:

• An order is opened or closed.
• An error occurs.
• The bot starts or stops.

---

🏗️ Architecture

The project follows a modular architecture using modern Python standards.

app/
├── api/             # FastAPI Webhook Router
├── core/            # Core Infrastructure
│   ├── config.py    # Settings Management (Pydantic)
│   ├── database.py  # Database Connection (SQLAlchemy)
│   └── logging.py   # Logging Configuration
├── models/          # Database Models (Log, Order, Alert)
├── services/        # Business Logic Layers
│   ├── binance_service.py      # Binance API Wrapper
│   ├── telegram_service.py     # Telegram Bot Logic
│   ├── trade_service.py        # Trading Logic & Risk Calculation
│   └── tradingview_service.py  # Webhook Queue Manager
└── main.py          # Application Entry Point

Technology Stack:

• Language: Python 3.10
• Web Framework: FastAPI + Uvicorn
• Database: SQLite + SQLAlchemy
• Containerization: Docker
• Trading: python-binance

---

❓ Troubleshooting

Webhook doesn't trigger

• Check Logs: Use /getlog or docker logs binance-bot.
• Check Port: Ensure your VPS firewall allows ingress on Port 80.
• Check Key: Verify ALERT_KEY in TradingView matches .env.

"Invalid API Key" Error

• Your BINANCE_API_KEY or BINANCE_SECRET_KEY is incorrect.
• IP Restriction on Binance does not include your VPS IP.
• Futures trading is not enabled on your Binance account.

Bot doesn't reply on Telegram

• Check TELEGRAM_BOT_TOKEN.
• Ensure the bot is running (docker ps).
• Send /start again.