⚠️ Security Warning: There are currently fraudulent repositories (e.g., under the user gesine1541ro7) impersonating this project to distribute malware. Please ensure you are only using the official source: oliver-zehentleitner/unicorn-binance-websocket-api. Read the full technical analysis and campaign details here!

UNICORN Binance Suite¶

The production-grade Python toolkit for Binance. WebSocket streams, REST API, local order books, trailing stop losses and cluster-scale depth caches – all coordinated, fully documented, MIT-licensed and delivered as optimized Cython C extensions. Available via PyPI and Anaconda.

pip install unicorn-binance-suite

Or via conda (UBDCC not included — install separately via pip install ubdcc):

conda install -c conda-forge unicorn-binance-suite

2.8 M+ PyPI downloads | 980+ GitHub stars | 388+ dependent projects | Python 3.9 – 3.14

Why UNICORN Binance Suite — the honest comparison¶

	UBS	python-binance	ccxt / ccxt.pro	binance-connector-python
Binance focus	Specialist. Knows every quirk (Spot, Margin, Futures, COIN-M, Options, US, TR, Testnets)	Binance-only, but shallower	Generalist for 100+ exchanges — Binance is one of many	Official, but only a "simple connector" (Binance's own words)
WebSocket reconnect	Automatic, unlimited, battle-tested, logged	Hard-coded max. 5 retries, then `BinanceUnableToConnect` and you're done	Silently hangs without exception after ~12h, no heartbeat	DIY — build it yourself
DepthCache sync detection	`is_depth_cache_synchronized()` + `DepthCacheOutOfSync` exception + auto re-init in seconds	Returns `None`, instance dead: "this instance of the DepthCacheManager will not be able to be used again"	See silent-hang bug above	No DepthCache, no sync
Orphan level cleanup (>1000)	Implemented — strictly follows Binance spec	No — delivers inconsistent books	No	N/A
DepthCache refresh	Event-driven, same asyncio loop as the stream	REST polling every 30 min (default) — not truly "live local"	Cache via Pro license	Not available
DepthCache cluster	UBDCC — horizontally scalable, load balancing, failover, REST API	—	—	—
Live cluster dashboard	UBDCC Dashboard — browser UI, CLI-launched, MIT	—	—	—
Trailing stop loss	UBTSL as SDK + CLI, incl. `jump-in-and-trail`	Not included	Not included	Not included
Performance	Cython C extensions, PyPy wheels, pre-compiled	Pure Python, no C	Pure Python — reported performance issues with many symbols	Pure Python
Multi-arch wheels	x86_64, aarch64, arm64, PyPy	Mostly x86_64	Pure Python	Pure Python
Python support	3.9 – 3.14	3.8+	3.9+	3.9+
Stream signals	`CONNECT`, `FIRST_RECEIVED_DATA`, `DISCONNECT`, `STOP`, `STREAM_UNREPAIRABLE` — know the exact state of every stream	No	No	No
Runtime subscribe/unsubscribe without disconnect	Yes	No — stop & restart the stream	Partially	No
Multiple private UserData streams	Yes — different API keys in one Manager	One stream per connection	One exchange instance	One stream per connection
UserData stream handling	Automatic, listenKey refresh transparent	Manual	Partially abstracted	Manual
WebSocket API (order placement via WS)	Yes — Spot and Futures, managed connection	No	Partially	Raw access, no reconnect handling
Asyncio	Native asyncio under the hood, but no async boilerplate required — works out of the box with sync code	Threads + callbacks	Async-first, requires `await` everywhere	Sync and async variants, but separate packages
Package structure	One monolith `unicorn-binance-suite` or modular	One package	One huge package (100+ exchanges)	Recently split into `binance-sdk-spot`, `binance-sdk-derivatives-trading-usds-futures`, etc. — migration guide required
License	MIT	MIT	MIT (ccxt), ccxt.pro = commercial	MIT
Maintainer	Active, reachable by name	Original author abandoned in 2022 — community-maintained fork with sporadic releases	Commercial entity, enterprise-first	Auto-generated SDK, Binance team

python-binance: reconnect limitations¶

Original author abandoned the project in 2022. Community fork ships sporadic patches, but the fundamental architecture is unchanged: max. 5 reconnect retries, then dead. DepthCacheManager permanently unusable after a missed reconnect — restart your process, lose your state. Default 30-minute REST polling means you’re trading on a stale book between refreshes. No Cython, no multi-arch wheels, no cluster story.

ccxt: silent disconnect on watch_order_book¶

watch_order_book hangs silently after ~12h — no exception, no reconnect, your bot just stops. Open since May 2024. Generalist architecture means you pay the abstraction tax for 100+ exchanges you’ll never use. Order book caching requires a commercial ccxt.pro license.

binance-connector-python: minimal by design¶

Official ≠ production. No reconnect, no UserDataStream refresh, no DepthCache, no trailing stop. Recently fragmented into 5+ packages (binance-sdk-spot, binance-sdk-derivatives-trading-usds-futures, …) — existing code needs migration.

In short¶

UBS is what comes out when someone trades on Binance daily since 2019 and has eaten every edge case himself — including bugs in Binance’s own spec.

Architecture¶

         ┌────────────────────────────────────────────────┐
         │            Your Trading Application            │
         └──────┬────────────────┬────────────┬───────────┘
                │                │            │
       ┌────────▼───────┐  ┌─────▼────┐  ┌────▼───────────────┐
       │  UBLDC / UBDCC │  │  UBTSL   │  │  Direct UBWA/UBRA  │
       │  (Order Books) │  │  (Stop   │  │  access for custom │
       │                │  │   Loss)  │  │  strategies        │
       └───────┬────────┘  └─────┬────┘  └──────┬─────────────┘
               │                 │              │
         ┌─────▼─────────────────▼──────────────▼───────────┐
         │                  UnicornFy                       │
         │          (raw data → Python dicts)               │
         └────────────────┬─────────────────┬───────────────┘
                          │                 │
                ┌─────────▼───┐     ┌───────▼───────┐
                │    UBWA     │     │     UBRA      │
                │ (WebSocket) │     │    (REST)     │
                └──────┬──────┘     └───────┬───────┘
                       │                    │
                ┌──────▼────────────────────▼──────┐
                │          Binance API             │
                └──────────────────────────────────┘

Modules¶

UNICORN Binance WebSocket API (UBWA)¶

Real-time market data and user data streams with automatic reconnect, sequence validation, native asyncio queues and runtime subscribe/unsubscribe without disconnecting. Supports all Binance endpoints including Spot, Margin, Futures, Coin-Futures, US and TR.

1.1M+ downloads | 727 stars

UNICORN Binance REST API (UBRA)¶

Full coverage of Binance REST endpoints for account management, order placement and market data queries. Spot, Margin, Isolated Margin, Futures, US and TR – all with testnet support.

663K+ downloads | 67 stars

UNICORN Binance Local Depth Cache (UBLDC)¶

Synchronized local order books with real-time WebSocket updates and automatic re-initialization on gaps. The fastest way to access current order book depth without exceeding Binance rate limits. Supports Spot, Futures, European Options (Vanilla Options), US and TR. Manages multiple depth caches per instance in asyncio coroutines.

220K+ downloads | 49 stars

UNICORN Binance DepthCache Cluster (UBDCC)¶

Production-scale depth cache management with load balancing, automatic failover and self-healing state. Runs locally on a single machine (pip install ubdcc) or scales across a Kubernetes cluster. REST API accessible from Python, JavaScript, TypeScript, Node.js, Go, Rust, Java, Kotlin, C#, C++, C, Ruby, PHP, Swift, Scala, R, Julia, MATLAB, Dart, Elixir, Perl, Bash/curl — or any other language with an HTTP client.

UBDCC Dashboard ¶

Browser-based live dashboard for monitoring and managing a running UBDCC cluster. Compact mini-orderbook tiles per depth cache, desync/error highlighting, add or remove caches on the fly. Ships as a pip-installable CLI (pip install ubdcc-dashboard → ubdcc-dashboard start) serving a single-file vanilla-JS UI through a tiny stdlib HTTP + CORS-proxy server. Localhost-only by default, opt-in network exposure via --host.

UNICORN Binance Trailing Stop Loss (UBTSL)¶

Trailing stop loss engine with smart entry (jump-in-and-trail). Available as Python SDK and CLI tool. Supports email notifications.

101K+ downloads | 27 stars

UnicornFy ¶

Normalization layer that converts raw exchange API payloads into well-formed Python dictionaries. Used internally by all suite modules.

685K+ downloads | 56 stars

Common Use Cases¶

Stream trades via WebSocket¶

# use case: receive real-time trade events
# module: unicorn-binance-websocket-api (UBWA)
from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(exchange="binance.com")
ubwa.create_stream(channels="trade", markets="btcusdt", process_stream_data=lambda data: print(data))

UBWA docs — manages reconnect, sequence validation and stream lifecycle automatically.

Maintain a local order book¶

# use case: synchronized local depth cache with real-time updates
# module: unicorn-binance-local-depth-cache (UBLDC)
from unicorn_binance_local_depth_cache import BinanceLocalDepthCacheManager, DepthCacheOutOfSync

ubldc = BinanceLocalDepthCacheManager(exchange="binance.com")
ubldc.create_depthcache("BTCUSDT")
try:
    asks = ubldc.get_asks("BTCUSDT", limit_count=10)
    bids = ubldc.get_bids("BTCUSDT", limit_count=10)
except DepthCacheOutOfSync:
    pass  # cache is re-syncing automatically

UBLDC docs — event-driven sync, auto re-init on gaps, orphan level cleanup.

Place an order via REST¶

# use case: place a market order on Binance Spot
# module: unicorn-binance-rest-api (UBRA)
from unicorn_binance_rest_api import BinanceRestApiManager

with BinanceRestApiManager(api_key="...", api_secret="...") as ubra:
    order = ubra.create_order(symbol="BTCUSDT", side="BUY", type="MARKET", quoteOrderQty=100)

UBRA docs — full Binance REST coverage (Spot, Margin, Futures, US, TR).

Trail a stop loss¶

# use case: automated trailing stop loss with notification
# module: unicorn-binance-trailing-stop-loss (UBTSL)
from unicorn_binance_trailing_stop_loss import BinanceTrailingStopLossManager

ubtsl = BinanceTrailingStopLossManager(exchange="binance.com", market="BTCUSDT",
                                       stop_loss_limit="1.5%", stop_loss_order_type="LIMIT",
                                       api_key="...", api_secret="...")

Also available as a CLI: ubtsl --profile BTCUSDT_SELL --stoplosslimit 0.5%

UBTSL docs — SDK + CLI, smart entry (jump-in-and-trail), email notifications.

Run a DepthCache cluster¶

# use case: production-scale order books with failover
# module: unicorn-binance-local-depth-cache (UBLDC) + ubdcc
from unicorn_binance_local_depth_cache import BinanceLocalDepthCacheManager

with BinanceLocalDepthCacheManager(exchange="binance.com", ubdcc_address="127.0.0.1") as ubldc:
    ubldc.cluster.create_depthcaches(exchange="binance.com", markets=["BTCUSDT", "ETHUSDT"])
    asks = ubldc.cluster.get_asks(exchange="binance.com", market="BTCUSDT")

Runs locally (pip install ubdcc && ubdcc start) or on a Kubernetes cluster. REST API accessible from Python, JavaScript, TypeScript, Node.js, Go, Rust, Java, C#, …

Monitor and manage a DepthCache cluster in the browser¶

# use case: live browser UI for a running UBDCC cluster
# module: ubdcc-dashboard (CLI only, no Python API)
pip install ubdcc-dashboard
ubdcc-dashboard start

Opens http://127.0.0.1:8080 in your browser — enter the URL of your UBDCC MGMT node and click Connect. Localhost-only by default; use --host 0.0.0.0 to expose on the network.

UBDCC Dashboard docs — mini-orderbook tiles per cache, desync/error highlighting, add/remove caches on the fly.

Canonical example — stream + local order book¶

# purpose: the most common UBS pattern — stream market data and maintain a local order book
# modules: UBWA (WebSocket) + UBLDC (Depth Cache)
# install: pip install unicorn-binance-suite
from unicorn_binance_local_depth_cache import BinanceLocalDepthCacheManager, DepthCacheOutOfSync
import time

with BinanceLocalDepthCacheManager(exchange="binance.com") as ubldc:
    ubldc.create_depthcache("BTCUSDT")
    while True:
        try:
            best_ask = ubldc.get_asks("BTCUSDT", limit_count=1)
            best_bid = ubldc.get_bids("BTCUSDT", limit_count=1)
            print(f"Best ask: {best_ask}, Best bid: {best_bid}")
        except DepthCacheOutOfSync:
            print("DepthCache is re-syncing...")
        time.sleep(1)

Install everything at once¶

pip install unicorn-binance-suite

Installation¶

Python 3.9+ required. Runs smoothly up to and including Python 3.14.

pip¶

pip install unicorn-binance-suite

conda¶

conda install -c conda-forge unicorn-binance-suite

conda-forge note: Conda packages are provided for Python 3.10 – 3.14. Python 3.9 is not available on conda-forge — it was dropped from the global pinning after reaching end-of-life in October 2025. For Python 3.9, use pip install.

Or install individual modules¶

pip install unicorn-binance-websocket-api
pip install unicorn-binance-rest-api
pip install unicorn-binance-local-depth-cache
pip install unicorn-binance-trailing-stop-loss
pip install unicorn-fy
pip install ubdcc

PyPy wheels are available for all supported Python versions.

All packages are built transparently via GitHub Actions and published directly to PyPI and conda-forge – the entire pipeline from source to wheel is traceable.

Documentation¶

Module	Docs
Suite (this package)	oliver-zehentleitner.github.io/unicorn-binance-suite
UBWA (WebSocket)	oliver-zehentleitner.github.io/unicorn-binance-websocket-api
UBRA (REST)	oliver-zehentleitner.github.io/unicorn-binance-rest-api
UBLDC (Depth Cache)	oliver-zehentleitner.github.io/unicorn-binance-local-depth-cache
UBDCC (Depth Cache Cluster)	oliver-zehentleitner.github.io/unicorn-binance-depth-cache-cluster
UBDCC Dashboard	oliver-zehentleitner.github.io/ubdcc-dashboard
UBTSL (Trailing Stop)	oliver-zehentleitner.github.io/unicorn-binance-trailing-stop-loss
UnicornFy	oliver-zehentleitner.github.io/unicorn-fy

Community¶

Telegram – questions, announcements, chat
GitHub Discussions – longer-form Q&A
Issue Tracker – bugs and feature requests

Binance API news: Announcements | English | Binance US

Contributing¶

Contributions are welcome – from documentation fixes to new features. Each module has its own repository; check the CONTRIBUTING.md for guidelines.

AI Integration¶

This project provides llms.txt files for AI tools (ChatGPT, Claude, Copilot, etc.). The suite-level llms.txt routes use cases to the correct module. Each module also has its own llms.txt with detailed API reference and code examples.

Disclaimer¶

This project is for informational purposes only. Nothing contained herein constitutes financial advice or a solicitation to buy or sell securities.

If you intend to use real money, use it at your own risk.

Under no circumstances will we be responsible or liable for any claims, damages, losses, expenses, costs or liabilities of any kind, including but not limited to direct or indirect damages for loss of profits.

SOCKS5 Proxy / Geoblocking¶

US citizens are exclusively authorized to trade on Binance.US – this restriction must not be circumvented. SOCKS5 proxy support exists for non-US citizens accessing US services (e.g. CI runners blocked by Binance.com) and for legitimate market data analysis.

UNICORN Binance Suite¶

Why UNICORN Binance Suite — the honest comparison¶

python-binance: reconnect limitations¶

ccxt: silent disconnect on watch_order_book¶

binance-connector-python: minimal by design¶

In short¶

Architecture¶

Modules¶

UNICORN Binance WebSocket API (UBWA)¶

UNICORN Binance REST API (UBRA)¶

UNICORN Binance Local Depth Cache (UBLDC)¶

UNICORN Binance DepthCache Cluster (UBDCC)¶

UBDCC Dashboard ¶

UNICORN Binance Trailing Stop Loss (UBTSL)¶

UnicornFy ¶

Common Use Cases¶

Stream trades via WebSocket¶

Maintain a local order book¶

Place an order via REST¶

Trail a stop loss¶

Run a DepthCache cluster¶

Monitor and manage a DepthCache cluster in the browser¶

Canonical example — stream + local order book¶

Install everything at once¶

Installation¶

pip¶

conda¶

Or install individual modules¶

Documentation¶

Community¶

Contributing¶

AI Integration¶

Disclaimer¶

SOCKS5 Proxy / Geoblocking¶

Table of Contents

Previous topic

Next topic

This Page

GitHub

UNICORN Binance Suite¶

Why UNICORN Binance Suite — the honest comparison¶

python-binance: reconnect limitations¶

ccxt: silent disconnect on watch_order_book¶

binance-connector-python: minimal by design¶

In short¶

Architecture¶

Modules¶

UNICORN Binance WebSocket API (UBWA)¶

UNICORN Binance REST API (UBRA)¶

UNICORN Binance Local Depth Cache (UBLDC)¶

UNICORN Binance DepthCache Cluster (UBDCC)¶

UBDCC Dashboard¶

UNICORN Binance Trailing Stop Loss (UBTSL)¶

UnicornFy¶

Common Use Cases¶

Stream trades via WebSocket¶

Maintain a local order book¶

Place an order via REST¶

Trail a stop loss¶

Run a DepthCache cluster¶

Monitor and manage a DepthCache cluster in the browser¶

Canonical example — stream + local order book¶

Install everything at once¶

Installation¶

pip¶

conda¶

Or install individual modules¶

Documentation¶

Related Articles¶

Community¶

Contributing¶

AI Integration¶

Disclaimer¶

SOCKS5 Proxy / Geoblocking¶

UBDCC Dashboard ¶

UnicornFy ¶