Explore the docs » · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation & Configuration
   • Running with Docker
3. Usage
4. Testing
5. Governance & Architecture Docs
6. Contributing
7. License
8. Contact

About The Project

This project receives TradingView alerts over a passphrase-gated webhook and executes the corresponding order on Binance. It's a single Django project (backend/) with a Service Layer wrapping the binance-connector SDK, security-hardened settings, and a SQLite database.

Warning

This software places real trades with real money. Read SECURITY.md before deploying — it covers API key restrictions, HTTPS requirements, and the disclaimer of liability. Nothing trades until you set LIVE_TRADING = true under [binance] in config.toml; without it every order goes to Binance's dry-run endpoint. manage.py check tells you which mode you are in.

Key Features:

• Modular Structure: separate apps for webhook intake (Webhook_Receiver) and Binance execution (Binance_Connector).
• Service Layer Architecture: order execution logic lives in BinanceService, decoupled from the views.
• Security: constant-time passphrase check, IsAdminUser-gated direct order endpoint, CSP/HSTS/CORS headers, idempotent webhook processing (a repeated order_id is rejected, never re-executed).
• Structured Logging: configurable JSON/text logs with rotation.
• Auto-Doc: Swagger/Redoc UI, served only when DEBUG=True.

Built With

(back to top)

Getting Started

Prerequisites

• Python 3.12+
• Pip & venv
• Binance API Keys (with Trading permissions enabled)

Installation & Configuration

1. Clone the repository

   git clone https://github.com/GstMirabal/Tradingview2EXCH.git
   cd Tradingview2EXCH

2. Configure Environment Variables

   • Copy .env.example to .env and config.toml.example to config.toml.
   • Fill in .env:
     • DJANGO_SECRET_KEY: a freshly generated key (python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())').
     • WEBHOOK_PASSPHRASE: a secret string to validate incoming webhooks.
     • API_KEY / API_SECRET: your Binance credentials.
   • The database is SQLite only — SQLITE_NAME controls where the file lives; there is no Postgres/MySQL support.

3. Install Dependencies

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

4. Initialize & Run

   python backend/manage.py migrate
   python backend/manage.py runserver

(back to top)

Running with Docker

docker-compose.yml defines a single web service (SQLite needs no separate database container):

docker-compose up --build

The SQLite file persists in the sqlite_data named volume across docker-compose down.

Production note: with DEBUG=False, SECURE_SSL_REDIRECT is on and gunicorn itself never terminates TLS — put a reverse proxy (nginx, Traefik, a cloud load balancer) in front that forwards X-Forwarded-Proto, or every request redirect-loops. If you're running gunicorn directly with no such proxy, set SECURE_SSL_REDIRECT = False in settings.py instead.

(back to top)

Usage

The API provides two Binance-facing endpoints, plus a status check:

1. Webhook Receiver

• Endpoint: POST /webhook-receiver/webhook/
• Security: requires a passphrase field in the JSON body matching your .env configuration.
• Idempotency: a repeated order_id is rejected (400) rather than executed twice.
• Example Payload:

  {
    "passphrase": "your_secret_passphrase",
    "symbol": "{{ticker}}",
    "side": "BUY",
    "type": "MARKET",
    "size": "0.001",
    "exchange": "BINANCE",
    "time": "{{time}}",
    "interval": "{{interval}}",
    "price": "{{close}}",
    "order_id": "TV_ALERT_1",
    "market_position": "{{strategy.market_position_size}}",
    "market_prev_position": "{{strategy.prev_market_position_size}}"
  }

How to Configure in TradingView:

1. Alert Message: use the payload above as your TradingView alert's "Message" field, substituting the placeholders.
2. Webhook URL: set your alert's Webhook URL to http://your-server-ip:8000/webhook-receiver/webhook/.

2. Binance Connector (Internal/Direct)

• Endpoint: POST /binance-connector/binance-params/
• Security: requires an authenticated Django staff session (IsAdminUser) — this is an internal tool, not part of the public webhook flow.
• Purpose: direct order submission outside the TradingView flow.

3. Status Check

• Endpoint: GET /binance-connector/status/ (also IsAdminUser) — returns Binance system status and account assets.

4. API Documentation

When running with DEBUG=True:

• Swagger: http://localhost:8000/swagger/
• Redoc: http://localhost:8000/redoc/

(back to top)

Testing

Run the full test suite from inside backend/ (Django's bare manage.py test discovers relative to the current directory):

cd backend
python manage.py test

(back to top)

Governance & Architecture Docs

This project is governed by the .agents pipeline. For a deeper reference beyond this README:

• docs/0_SYSTEM_OVERVIEW.md — architecture entry point.
• docs/architecture/ — per-module Blueprints (CORE, BINANCE_CONNECTOR, WEBHOOK_RECEIVER).
• docs/decisions/ — ADRs recording architectural decisions.
• CHANGELOG.md — release history.

(back to top)

Contributing

Contributions are welcome and greatly appreciated. See CONTRIBUTING.md for the setup steps, the three local checks to run before opening a PR, and notes on areas that need extra care (config loading, security settings, the webhook field contract).

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

By participating, you agree to abide by our Code of Conduct. For security issues, please follow SECURITY.md instead of opening a public issue.

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Gustavo Mirabal Suarez - gst.mirabal@gmail.com

• LinkedIn: @Gustavo-Mirabal
• GitHub: @GstMirabal
• Twitter: @GstMirabal

Project Link: https://github.com/GstMirabal/Tradingview2EXCH

(back to top)