beijingcao/binance-deribit-btc: a cross-exchange BTC arbitrage bot with Redis recovery

What this bot actually arbitrages

The project targets a specific spread: Deribit BTC options on one side, Binance USDT-M perpetual futures on the other. The README describes the loop as scanning for potential arbitrage between the two venues, then executing orders, monitoring the position, handling settlement, and alerting through Telegram. That is a hedging workflow, not a latency race. You are not competing for the top of the book across ten venues; you are pairing an options position with a perp position and letting the bot manage the resulting exposure.

The audience is narrow and specific. You need funded accounts on both exchanges, API credentials for each, a machine that can reach Deribit, Binance Futures and the Telegram API, and enough Python literacy to edit config.py without breaking the risk parameters. The README's own warning block says to validate on testnet with small size and read-only or low-privilege keys first, which tells you who this is not for: anyone expecting a turnkey product. The default configuration ships with BASE_CONFIG["test_trading"] set to True and BINANCE_CONFIG["use_testnet"] set to True, so a careless first run does not touch real money. That default is the single best design decision in the repository.

How state recovery and the engine mixins fit together

The entry point is binance_deribit.py. Around it sit binance_futures.py for the Binance side, deribit_client.py for Deribit over WebSocket and REST, trade_executor.py for order placement, telegram_handler.py for commands and alerts, db_store.py for SQLite persistence, and fee_calculator.py. The engine/ directory holds what the README calls core engine mixin modules, which is where scan, execution and position-monitoring logic is composed into the main loop.

Redis is the recovery layer, and it is the most interesting piece of the architecture. The README states that Redis stores runtime state so the process can resume after a restart. It also documents a database mapping: mainnet BTC on db 0, mainnet ETH on db 1, testnet BTC on db 2, testnet ETH on db 3. Note that the .env.example template includes DERIBIT_ETH_CLIENT_ID and DERIBIT_ETH_CLIENT_SECRET even though the project name and README describe BTC. The ETH credential slots and the db 1 and db 3 mappings suggest a shared codebase across two instruments; the README documents the BTC workflow only. If you are running BTC, the ETH variables can stay empty, but you should confirm that in your own copy of config.py rather than assuming.

SQLite, via db_store.py, records trades, account equity and peak floating loss. That is a separate concern from Redis: Redis is for live state that must survive a crash, SQLite is the historical record. Both are local files or local services, so neither survives losing the machine.

Installing it and getting to a first testnet run

The README targets Python 3.10 or higher, Redis 6 or higher, and macOS or Ubuntu. Dependencies are listed in requirements.txt: aiohttp, flask, orjson, redis, requests and websockets. Clone and build a virtual environment first.

git clone https://github.com/beijingcao/binance-deribit-btc.git
cd binance-deribit-btc
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Redis has to be running before the bot starts. On Ubuntu the README gives apt install and systemctl commands; on macOS it gives Homebrew. Either way, the check is the same ping.

redis-cli ping

A reply of PONG means Redis is up. Next, copy the environment template and fill in the credentials. The template ships with empty values for the Telegram token and chat id, the Deribit BTC and ETH client id and secret pairs, and the Binance API key and secret.

cp .env.example .env
nano .env

Before starting, open config.py and confirm the testnet flags. The README shows the relevant block explicitly, including leverage 20 and ISOLATED margin on the Binance side.

BASE_CONFIG = {
    "target_currency": "BTC",
    "test_trading": True,
}

BINANCE_CONFIG = {
    "use_testnet": True,
    "use_hedge_mode": True,
    "leverage": 20,
    "margin_type": "ISOLATED",
}

Then run the main program. A preflight check runs at startup and refuses to launch if .env is missing, keys are absent, Redis is down, the exchange REST endpoints are unreachable, authentication fails, or disk space is short.

python binance_deribit.py

The monitor is a separate process on a separate port. Start it in another terminal and open the URL.

python binance-monitor.py --host 127.0.0.1 --port 5556

The README states the default login is admin with password 123456 and that you should change it at /change_password immediately. The Flask app writes .monitor_auth.json locally, holding the password hash and session secret; that file is gitignored.

The preflight gate and where it stops protecting you

Preflight is the project's main safety mechanism, and it is a real one: a missing .env, absent keys, a dead Redis, unreachable exchange REST, failed authentication or low disk space all block startup. The README also documents an override, python binance_deribit.py --force-startup, for the case where you know you have no open positions and want to start despite a failed check. Critically, the README states that if the exchange reports open positions, --force-startup will not bypass the key protections. That is the right call, and it is worth knowing before you reach for the flag.

The gap is what happens after startup. Preflight validates environment and connectivity, not strategy correctness. Nothing in the README describes a maximum-loss circuit breaker beyond the risk parameters you set yourself, and nothing describes a kill switch that flattens both legs automatically. The Telegram handler can pause and resume and adjust some parameters, which gives you a manual brake, but the bot's behaviour under a partial fill, a rejected hedge leg, or a venue outage is not documented. That is the failure mode to think hardest about: an unhedged leg on 20x isolated margin is not a small problem. Treat the README as a deployment guide, not a risk specification, because it does not claim to be one.

Running it as a service and what an upgrade costs

For anything beyond a test, the README recommends tmux or systemd. The systemd unit it provides orders the service after network-online.target and redis-server.service, sets Restart=always with RestartSec=5, and sets PYTHONUNBUFFERED=1 so logs flush. If your paths differ from /opt/binance-deribit-btc, you have to change WorkingDirectory, ExecStart and User together.

[Unit]
Description=Binance Deribit Arbitrage Bot
After=network-online.target redis-server.service
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/binance-deribit-btc
ExecStart=/opt/binance-deribit-btc/.venv/bin/python /opt/binance-deribit-btc/binance_deribit.py
Restart=always
RestartSec=5
User=ubuntu
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

The upgrade path in the README is git pull, reinstall requirements, and restart the unit. There are no retrieved releases, so there is no version tag to pin against and no changelog to read before pulling. That raises the cost of upgrading: you are diffing config.py and the engine/ modules yourself, and a change to a config key or a Redis key layout is the kind of thing that only shows up when the bot restarts mid-position. The Redis state design helps here, since a restart is supposed to resume rather than reset, but it also means stale keys from an old schema are a plausible source of confusing behaviour. The README does not document a schema migration step or a rollback procedure.

The last push to the default branch was on 2026-06-22. The repository is not archived, but roughly three months have passed since that push, so treat the code as stable rather than actively changing and plan to own your fork. The project is MIT licensed, which permits commercial use and modification; the README's security section asks you not to commit .env, real API keys, account screenshots, logs or database files, and the repository's .gitignore is set up for that. Note that the README credits num.cc for compute support and lists a homepage at btc.num.cc described as a live testnet instance, so the project is tied to an external operator even though the code is permissively licensed.

Editorial conclusion

Adopt this if you already run Deribit and Binance Futures accounts, are comfortable reading Python strategy code, and want a self-hosted bot with Redis-backed state recovery and a Telegram control channel. Do not adopt it if you need a documented strategy specification, a backtest harness, or a support contract; the README describes mechanics and deployment, not expected returns. Before risking real money, verify three things in your own checkout: that BASE_CONFIG["test_trading"] and BINANCE_CONFIG["use_testnet"] are both False, that the monitor password has been changed from the admin/123456 default, and that a restart of binance_deribit.py actually rehydrates your position from Redis db 2 instead of opening a second one.

Frequently asked questions

Official sources

1. beijingcao/binance-deribit-btc on GitHub
2. Issues
3. License: MIT
4. Project website
5. README