Skip to content

Home

Jump to bottom
Beydah Saglam edited this page Sep 26, 2025 · 1 revision

Project Wiki

Welcome to the official wiki for the TradingView Webhook Bot. This document provides in-depth information about the project's architecture, configuration, and usage.

Table of Contents

  1. Architecture Overview
  2. Configuration Guide
  3. TradingView Alert Setup
  4. Telegram Bot Commands
  5. Troubleshooting

1. Architecture Overview

The bot is designed with a modular architecture, separating concerns into distinct layers: a service layer for business logic, a model layer for data management, and a database layer for persistence.

  • Service Layer (c_service/): This is the core of the application, handling all active processes.

    • sr_b_tradingview: Listens for HTTP requests from TradingView via a Flask/Waitress web server.
    • sr_e_telegram: Manages all communication with the Telegram API, including polling for messages and sending responses.
    • sr_d_transaction: Processes incoming commands from Telegram and manages user state.
    • sr_a_trade: Contains the primary trading logic, including risk management and order calculations.
    • sr_c_binance: A dedicated client for all interactions with the Binance Futures API.

  • Model Layer (d_model/): This layer is responsible for the structure and integrity of the data.

    • Each module corresponds to a JSON file in the e_database/ directory.
    • It handles CRUD (Create, Read, Update, Delete) operations for settings, alerts, orders, and logs.

  • Database Layer (e_database/): A simple file-based database using JSON.

    • db_a_settings.json: Stores all configuration parameters.
    • db_c_alerts.json: A temporary queue for incoming trade signals.
    • db_d_orders.json: A history of all executed trades.
    • db_e_logs.json: A log of all application events, errors, and transactions.

2. Configuration Guide

All configuration is handled in the e_database/db_a_settings.json file. The bot creates this file with default values on its first run. Below is a detailed explanation of each key:

  • binance_api: Your Binance API Key.
  • binance_secret: Your Binance Secret Key.
  • telegram_bot_token: The token for your Telegram bot from BotFather.
  • telegram_user_id: Your personal Telegram user ID.
  • webhook_ip: The IP address for the webhook server to listen on (usually 127.0.0.1 when behind a reverse proxy).
  • webhook_port: The port for the webhook server (e.g., 5001).
  • webhook_domain: Your public domain name (e.g., https://bot.yourdomain.com).
  • alert_key: A secret key you create to authenticate webhook requests from TradingView.
  • alert_long_open, alert_long_close, etc.: The JSON message templates to be used in your TradingView alerts.
  • order_balance: The percentage of your available balance to use for each trade (e.g., "100" for 100%).
  • order_leverage: The default leverage to use for trades (e.g., "2" for 2x).
  • margin_type: The margin type to use on Binance (isolated or cross).

3. TradingView Alert Setup

To connect TradingView to your bot, follow these steps:

  1. Webhook URL: In the TradingView alert settings, set the Webhook URL to your domain (e.g., https://bot.yourdomain.com/webhook).
  2. Message Body: For each alert type (long open, long close, etc.), copy the corresponding JSON template from your db_a_settings.json file into the "Message" field of the alert.
    • The placeholders {{ticker}} and {{close}} will be automatically replaced by TradingView with the symbol and closing price.
    • Ensure the key in the JSON message matches your alert_key setting.

4. Telegram Bot Commands

The bot is controlled via the following commands sent through your Telegram chat:

  • /start: Initializes the bot and displays the main menu.
  • /status: Shows the current status of the bot, including open positions and wallet balance.
  • /settings: Allows you to view and update configuration settings directly from Telegram.
  • /logs: Fetches and displays the latest log entries.
  • /stopbot: Gracefully stops the bot's trading and webhook services.

5. Troubleshooting

  • Webhooks not being received:

    • Ensure your Nginx configuration is correct and that your domain's DNS is pointing to your server's IP.
    • Check your server's firewall to make sure it allows traffic on ports 80 and 443.
    • Verify that the alert_key in your TradingView message matches the one in your settings.

  • Binance API errors:

    • Make sure your API keys have the correct permissions (Futures trading enabled).
    • If you've restricted the API key by IP, ensure your server's IP is correctly whitelisted in Binance.

  • Bot crashes or stops responding:

    • Check the logs using the /logs command in Telegram or by viewing the e_database/db_e_logs.json file directly on the server.

Developer Information

Clone this wiki locally