# chrisleekr/binance-trading-bot: a self-hosted TypeScript bot with backtesting and a dashboard

> A self-hosted Binance bot that separates strategy from the trading loop, runs account-scoped profiles, and replays historical candles before anything goes live. The README's own warning is that it is not recommended for real funds.

**chrisleekr/binance-trading-bot** — Automated Binance trading bot with pluggable strategies, historical backtesting, and a live dashboard

- Repository: https://github.com/chrisleekr/binance-trading-bot
- Website: https://chrisleekr.github.io/binance-trading-bot/
- Stars: 5,569 · Forks: 1,168
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/chrisleekr-binance-trading-bot

## What chrisleekr/binance-trading-bot solves, and who it is actually for

The project is for someone who already has a Binance account and wants to run the trading logic on their own server rather than hand an API key to a hosted service. The README describes the shape of that: you run the app yourself, connect it with an API key, and it watches the market and places buy and sell orders on your behalf. Nothing about the account, the keys or the order history leaves infrastructure you control, which is the main reason to pick this over a hosted bot. The cost is that you also own the database, the queue, the reverse proxy and the upgrade path.

The second audience is a developer who keeps rebuilding the same loop. The README states that a strategy is the rulebook the bot trades by, that three ship today (trailing-trade, momentum and rebalance), and that each lives in its own package behind a shared contract. Adding a fourth is described as mostly a new package plus a registry entry, not a rewrite of the trading loop. If your interest is in the rulebook rather than the plumbing, that separation is the point.

The README's own warning box is blunt: the author cannot guarantee whether you can make money, takes no responsibility for loss, and states the project is under active development and not recommended for real funds. Treat that as the project's own statement of readiness, not as modesty.

## The loop, the profiles and the state commit

The mechanism the README describes is a short repeating loop per monitored symbol: read the market, run the strategy's rules, decide buy, sell or wait, then act. That loop is the same regardless of which strategy is selected, which is what makes the strategies swappable.

Above the loop sits the account and profile model. 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 then runs N independent profiles, and each profile has its own coins, budget and strategy while sharing the account's wallet. That is a real constraint, not a detail: two profiles on the same account draw on the same balance, so a budget set per profile is a planning figure rather than a hard partition of funds.

Persistence is Postgres with TimescaleDB, and cache and queues are Redis with BullMQ; the schema lives in packages/db. The reliability claim in the README is specific: a crash-only worker, idempotent jobs, and a version-aware per-symbol state commit, so that a restart resumes cleanly and never double-places an order. The version-aware part is the interesting one. A per-symbol state record with a version lets the worker detect that it is acting on stale state after a crash rather than re-issuing an order it already sent. The README does not document a rollback procedure for a bad migration, so treat schema changes as forward-only until you confirm otherwise in the operations docs.

## Installing it and running a first backtest

The README's development quick start requires Bun 1.4 or later, pinned to 1.4.2 in .tool-versions, plus Docker with the compose plugin for the local Postgres and Redis stack. Run everything from the repo root. Note the lockfile warning: bun.lock is a lockfileVersion: 2 file that Bun 1.3.x cannot parse, so an older Bun will fail before the app starts.

The setup script installs dependencies, writes .env from .env.example, brings up Postgres and Redis with host ports exposed through the local compose override, and runs migrations.

```bash
bun install
bun run setup
```

After that, turbo starts the api, web, worker and technicals processes together. The SPA is then reachable on port 5173.

```bash
bun run dev
```

If you would rather run the whole stack in containers, the README gives a single command. One app service with ROLE=all serves the SPA and /api on port 53000.

```bash
bun run docker:dev
```

Configuration splits in two. Per-profile settings (grid, indicators, notifier providers, Technicals gates) live in the database and are editable through the SPA after first run. Process-level variables such as DATABASE_URL, REDIS_URL, WEB_ORIGIN and AUTH_SECRET are listed in .env.example. WEB_ORIGIN is a comma-separated allowlist of exact scheme://host:port origins; it gates CORS, Better Auth CSRF and the WebSocket upgrade, and a wildcard is not supported because credentialed requests forbid it. AUTH_SECRET is Zod-enforced at a minimum of 32 characters, and .env.example suggests generating one with openssl rand -hex 32. The first real use after the stack is up is a backtest: configure a strategy per profile, replay it against historical candles, and compare runs, since the README states every run is kept.

## Where it stops being the right tool

The clearest limitation is the one the project states about itself. The README says the software is under active development and not recommended for real funds. A bot that places live orders on your behalf while its own README tells you not to point it at real money is a testnet and paper-trading instrument first.

The second limitation is operational weight. Postgres plus TimescaleDB, Redis plus BullMQ, four processes in development and a compose stack in deployment is a serious footprint for a single-operator tool. If you wanted a script you can run from cron against the Binance API, this is the wrong shape.

The third is the account model. Profiles share one wallet per account, so isolation between strategies is logical rather than financial. If you want each strategy to fail without touching the others' capital, separate accounts with separate API keys are the only real boundary the README describes.

Finally, the deployment path has prerequisites the README does not soften: a 9-step operator runbook, IP-allowlisting the Binance key, and a choice between three TLS options. The README does not document rollback, so an upgrade that goes wrong has no described return path.

## How it differs from a single-file Python bot

The obvious alternative for this job is a small Python script that calls the Binance API directly, which is what a large share of the search interest around Binance bots is looking for. The difference in approach is not the language. A single-file bot puts the signal, the order call and the position state in one process, and its memory of what it has done is whatever the script holds or writes to a local file. This project moves all three apart: strategies are packages behind a shared contract, order placement and state live in a worker with idempotent jobs and a versioned per-symbol commit, and the operator interface is a separate web app reading the same database.

That buys you restart safety, a backtest history you can compare across windows and symbols, and the ability to swap the rulebook without touching the loop. It costs you a database, a queue, a build toolchain and a deployment runbook. If your strategy changes weekly and you want to read the whole bot in one sitting, the script wins. If you want to run the same rulebook on several symbols with a dashboard and a record of what it did, the structure here is the reason to take on the extra moving parts.

Because the strategy layer is pluggable, this is also not a grid-only bot in the sense the topic tags suggest. Grid is one of three strategies the README names, alongside momentum and rebalancing.

## Maintenance, licensing and what an upgrade costs

The repository is not archived and the last push was on 2026-09-22. Releases are frequent and versioned: v1.5.0 on 2026-09-09, v1.4.0 on 2026-08-30 and v1.3.0 on 2026-08-23. Release Please configuration files are present in the repository root, which matches that cadence. Frequent releases also mean the surface you pin moves often.

The README is explicit about how to consume them: images are published to Docker Hub as chrisleekr/binance-trading-bot:vX.Y.Z, and it says to pin a version with IMAGE_TAG rather than tracking :latest. That is the upgrade policy in one line. Budget for reading the changelog between tags, because schema changes ship with the app and migrations are part of the deploy runbook.

Licensing is Apache-2.0 per the LICENSE file and the package.json license field. That is a permissive licence with an explicit patent grant and a NOTICE file requirement, and the repository carries a NOTICE. This is a description of the terms, not legal advice; if you plan to redistribute a modified build, read the licence and NOTICE yourself. The README's disclaimer is separate from the licence and concerns trading losses, not code reuse.

## Conclusion

Adopt it if you want a self-hosted bot whose strategy layer is a separate package, and you are willing to run Postgres, TimescaleDB, Redis and BullMQ yourself. Do not adopt it if you need a bot to trade real funds today: the README says it is under active development and not recommended for real funds, and the author states he cannot guarantee profit. Before anything else, verify the Bun version against .tool-versions and bun.lock, confirm WEB_ORIGIN is an exact scheme://host:port list rather than a wildcard, and run a backtest on your symbol and window before a testnet profile.

## FAQ

### How do I set up chrisleekr/binance-trading-bot?

Install Bun 1.4 or later and Docker with the compose plugin, then run bun install followed by bun run setup from the repo root, which writes .env, starts Postgres and Redis and runs migrations. Start the processes with bun run dev and open the SPA on port 5173.

### How does chrisleekr/binance-trading-bot work?

It runs a short repeating loop per monitored symbol: read the market, run the selected strategy's rules, decide buy, sell or wait, then act. One operator login owns Binance accounts, and each account runs independent profiles with their own coins, budget and strategy over a shared wallet.

### Is chrisleekr/binance-trading-bot profitable?

The README does not make any profit claim. It states that the author cannot guarantee whether you can make money, takes no responsibility for loss, and that the project is under active development and not recommended for real funds.

### Is chrisleekr/binance-trading-bot free?

The source is published under Apache-2.0, so there is no licence fee to run it. You still pay for the server, the Postgres and Redis instances, and Binance's own trading fees.

### What is chrisleekr/binance-trading-bot?

It is a self-hosted automated Binance trading bot written in TypeScript, with pluggable strategies, historical backtesting and a live dashboard. The README describes it as under active development and not recommended for real funds.

## Sources

- [chrisleekr/binance-trading-bot on GitHub](https://github.com/chrisleekr/binance-trading-bot)
- [License: Apache-2.0](https://github.com/chrisleekr/binance-trading-bot/blob/main/LICENSE)
- [Project website](https://chrisleekr.github.io/binance-trading-bot/)
- [README](https://github.com/chrisleekr/binance-trading-bot/blob/main/README.md)
- [Releases](https://github.com/chrisleekr/binance-trading-bot/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chrisleekr-binance-trading-bot