<div align="center">

Binance Trading Bot

Automated Binance trading bot with pluggable strategies, historical backtesting, and a live dashboard.<br/> Self-hosted. Multiple strategy profiles: grid, momentum, or rebalancing.

Documentation · Quick start · Deploy · Strategies

<img src="docs/assets/readme/dashboard.png" alt="Dashboard showing open positions, open orders, market trend and the monitored symbol table" width="900" /> </div> <!-- prettier-ignore -->

[!WARNING] I cannot guarantee whether you can make money or not. Use it at your own risk. I have no responsibility for any loss or hardship incurred directly or indirectly by using this code. Read the disclaimer before using it.

Under active development and not recommended for real funds.

How it works

You run the app on your own server, connect it to your Binance account with an API key, and it watches the market and places buy and sell orders on your behalf. Once running, it repeats a short loop for every coin you told it to watch: read the market, run your strategy's rules, decide buy / sell / wait, and act.

• Strategy-pluggable. A strategy is the rulebook the bot trades by. Three ship today: trailing-trade, momentum, and rebalance, and you pick one per profile. Each lives in its own package behind a shared contract, so adding a fourth is mostly a new package plus a registry entry, not a rewrite of the trading loop.
• Account-scoped profiles. One operator login owns one or more Binance accounts. Each account is one API key pair, one environment (testnet or live), and one wallet. Each account runs N independent profiles, each with its own coins, budget, and strategy, all sharing that account's wallet.
• Reliability-first. Crash-only worker, idempotent jobs, and a version-aware per-symbol state commit mean a restart resumes cleanly and never double-places an order.

Persistence is Postgres + TimescaleDB; cache and queues are Redis + BullMQ. Schema lives in packages/db.

Act on a symbol

Every monitored symbol gets a workspace: live market data, the strategy's current signal, open orders, and manual overrides in one place.

<img src="docs/assets/readme/symbol-workspace.png" alt="Symbol workspace showing a live candle chart with the entry price and trailing stop drawn on it" width="900" />

Tune a strategy, then backtest it

Configure a strategy per profile, then replay it against historical candles before risking anything. Every run is kept, so you can compare windows and symbols side by side.

<img src="docs/assets/readme/backtest-history.png" alt="Backtest history listing past runs with their window period, status and profit or loss" width="900" />

More screens are covered in the user guide.

Configuration

Per-profile configuration (grid, indicators, notifier providers, Technicals gates) lives in the database and is editable through the SPA after first run. See configure a profile.

Process-level environment variables (DATABASE_URL, REDIS_URL, WEB_ORIGIN, AUTH_SECRET, etc.) are listed in .env.example and described in the environment variable reference.

Quick start (development)

Prerequisites: Bun 1.3+ and Docker (with the compose plugin) for the local Postgres + Redis stack.

Run all commands from the repo root.

# 1. Install deps, write .env from .env.example, bring up Postgres + Redis
#    with host ports exposed (via the local compose override), and run
#    migrations.
bun install
bun run setup

# 2. Start api + web + worker + technicals via turbo
bun run dev

Open the SPA at http://localhost:5173.

To run the whole stack in containers instead, use bun run docker:dev. One app service (ROLE=all) serves the SPA + /api on http://localhost:53000.

Quick start (deploy to a VM)

The 9-step operator runbook lives at deploy/README.md. It covers .env, AUTH_SECRET, image pull, docker compose up, migrations, onboarding, IP-allowlisting the Binance key, smoke tests, and three TLS options.

Images are published to Docker Hub as chrisleekr/binance-trading-bot:vX.Y.Z. Pin a version with IMAGE_TAG rather than tracking :latest.

Documentation

The full guide is at https://chrisleekr.github.io/binance-trading-bot, split by audience:

| Audience | What's there | | --- | --- | | Get started | Install, configure a profile, go live | | User guide | Dashboard, symbol workspace, profile and account settings | | Concepts | Strategies, discovery, technicals, backtesting, notifiers, written for non-experts | | Operations | Deploy, kill switch, environment variables, troubleshooting | | Contributing | Architecture, plugin contracts, CI gates, coding rules, testing |

Build the site locally:

bun run docs:install
bun run docs:serve   # http://127.0.0.1:8000

Contributing

Issues and pull requests are welcome at github.com/chrisleekr/binance-trading-bot.

1. Read CONTRIBUTING.md for the workflow.
2. Read AGENTS.md for the engineering charter and the invariants (CLAUDE.md is a symlink alias for Claude Code).
3. bun run lint and bun run typecheck must be clean before opening a pull request.

Security issues: please follow SECURITY.md rather than opening a public issue.

License

Apache-2.0. Third-party attributions are in NOTICE.

Disclaimer

I give no warranty and accept no responsibility or liability for the accuracy or the completeness of the information and materials contained in this project. Under no circumstances will I be held responsible or liable in any way for any claims, damages, losses, expenses, costs or liabilities whatsoever (including, without limitation, any direct or indirect damages for loss of profits, business interruption or loss of information) resulting from or arising directly or indirectly from your use of or inability to use this code or any code linked to it, or from your reliance on the information and material on this code, even if I have been advised of the possibility of such damages in advance.

So use it at your own risk!