# unicorn-binance-websocket-api wraps Binance streams in a Python stream buffer

> unicorn-binance-websocket-api is a Python SDK that opens multiplexed Binance websocket connections across the spot, margin, futures, coin futures, options, portfolio margin, US and TR endpoints, and hands the data over through a buffer or a callback. It saves you the connection plumbing, and it leaves the reconnect and backoff policy to you.

**oliver-zehentleitner/unicorn-binance-websocket-api** — A Python SDK to use the Binance Websocket API`s (com+testnet, com-margin+testnet, com-isolated_margin+testnet, com-futures+testnet, com-coin_futures, com-vanilla-options+testnet, com-portfolio_margin, us, tr) in a simple, fast, flexible, robust and fully-featured way.

- Repository: https://github.com/oliver-zehentleitner/unicorn-binance-websocket-api
- Website: https://oliver-zehentleitner.github.io/unicorn-binance-websocket-api
- Stars: 736 · Forks: 170
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/oliver-zehentleitner-unicorn-binance-websocket-api

## Nine Binance environments behind one manager class

Binance does not run a single websocket endpoint. The SDK names them explicitly in its description: com plus testnet, com-margin plus testnet, com-isolated_margin plus testnet, com-futures plus testnet, com-coin_futures, com-vanilla-options plus testnet, com-portfolio_margin, us and tr. That list is the clearest statement of what this project is for. A developer who needs spot trades and a futures kline on the same process, or who has to serve a US account and an international account from one codebase, otherwise ends up with a separate client per environment, each with its own URL, its own subscription format and its own quirks. The package handles that spread. It is published on PyPI and on conda-forge, is written in Python with a minimum of 3.9, and it is part of a larger suite the author calls UNICORN Binance Suite, with sibling packages for the REST API and for the futures side. The audience is therefore Python developers who already trade or analyse on Binance and want a maintained client rather than a websocket wrapper of their own.

## The stream_buffer is the hand-off point between socket and application

The central mechanism is a buffer, not a callback. The README describes creating a multiplex websocket connection to Binance with a stream_buffer, and the manager class that does it is BinanceWebSocketApiManager. You pass the manager an exchange identifier and a list of channels and markets, and it opens one connection carrying all of them. Received events land in the buffer, and your application pulls from it. That is a deliberate inversion of the usual callback-first design, and it has a practical consequence worth naming. Because the data sits in a buffer until you take it, a slow consumer does not lose events as long as the buffer is still holding them, and your processing loop decides its own cadence rather than inheriting the socket's arrival rate. The API surface for reading is a single method, pop_stream_data_from_stream_buffer, which returns the oldest entry, so ordering is preserved and backpressure shows up as a growing buffer rather than as dropped ticks. The README documents this method and the buffer in the wiki, and the whole thing is three lines of setup plus a small loop.

## Callback and async callback delivery for event driven code

The buffer is not the only delivery style. The manager also accepts a process_stream_data callback, and the README shows a synchronous version where the callback prints each received item as it arrives.

```python
from unicorn_binance_websocket_api import BinanceWebSocketApiManager

def process_new_receives(stream_data):
    print(str(stream_data))

ubwa = BinanceWebSocketApiManager(exchange="binance.com")
ubwa.create_stream(channels=['trade', 'kline_1m'], 
                   markets=['btcusdt', 'bnbbtc', 'ethbtc'], 
                   process_stream_data=process_new_receives)
```

There is an asyncio flavour too, with the callback declared as a coroutine.

```python
from unicorn_binance_websocket_api import BinanceWebSocketApiManager
import asyncio

async def process_new_receives(stream_data):
    print(stream_data)
    await asyncio.sleep(1)
```

The synchronous and asynchronous paths let you pick based on the rest of your application rather than on the SDK. The trade off is that the two styles behave differently under load. A callback that blocks holds up whatever thread delivers events, whereas the buffer approach lets you drain at your own speed with a separate consumer. Which one fits depends on whether your downstream work is quick and inline, or slow enough that you would rather queue it.

## Installing the SDK and opening a first multiplex stream

The package is distributed on PyPI and on conda-forge, so installation is a standard pip or conda operation against the name unicorn-binance-websocket-api. There is no build step for the average user, although the setup.py in the repository imports Cython and calls cythonize, so a source install compiles rather than copying pure Python files. Python 3.9 or newer is required. The runtime dependency list is worth reading before you deploy: websocket-client and websockets 15.0 or newer are both present, orjson handles the JSON parsing, python-socks 2.0.0 or newer covers proxy support, psutil and colorama are used for process and console handling, and unicorn-fy plus unicorn-binance-rest-api pull in the futures and REST side of the suite. There is also an optional extra, picows, that installs an alternative websocket client library, which the requirements file describes as selectable with BinanceWebSocketApiManager(websocket_library="picows"). Once installed, the shortest useful program is three lines.

```python
from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(exchange="binance.com")
ubwa.create_stream(channels=['trade', 'kline_1m'], markets=['btcusdt', 'bnbbtc', 'ethbtc'])
```

The exchange argument selects which Binance environment you talk to, the channels list picks trade and one minute kline data, and the markets list names the trading pairs. Four more lines read the buffer and print what arrives.

```python
while True:
    oldest_data_from_stream_buffer = ubwa.pop_stream_data_from_stream_buffer()
    if oldest_data_from_stream_buffer:
        print(oldest_data_from_stream_buffer)
```

Two things to expect on a first run. The channels and markets lists are combined into one multiplexed connection, so the three markets listed above arrive interleaved on a single stream, and the pop call returns the oldest item each time rather than a batch.

## Where the SDK stops: reconnects, signing and your own trading logic

The convenience has an edge, and the edge is operational. The README describes the manager, the buffer, the callbacks and the channel and market selection, but it does not document a reconnect policy, a heartbeat or ping handling, a backoff schedule, or what happens to buffered data when a connection drops. That silence matters, because a websocket to a live exchange will drop. In other words, whether your process survives a network hiccup depends on code you write around the SDK rather than on behaviour the SDK promises. The package name and the dependency set also hint at where the boundary lies. The presence of unicorn-binance-rest-api and unicorn-fy in the dependencies shows that the suite covers REST and futures support around this websocket core, but nothing in the documented surface places an order or signs a request for you. The examples directory makes the intended usage clearer than the README does: there are folders for the spot api, the futures api, portfolio margin, subscribe and unsubscribe handling, user data events, stream signals, a futures best practice example, an Apache Kafka pipeline, and a kline to SQLite writer. That list is the use case profile of a market data consumer, not a trading bot framework.

## How this compares with driving a websocket client yourself

The baseline alternative is to use websocket-client or websockets directly, subscribe to the combined stream endpoints by hand and parse the payload yourself. You get a transparent client with no opinions, and you take on the URL construction per environment, the subscription message format, the JSON parsing, the reconnect logic and the handling of the exchange's stream control messages. The SDK replaces all of that with a manager class and a buffer, and in exchange you inherit a layer you did not write and must read the documentation of. The second alternative is to write against the exchange's own official clients where they exist for your market and language, which ties you to the official surface for that market and leave you handling several environments yourself when you need more than one. A third path is a managed stream service or a framework built for backtesting and live execution, where the market data layer is only one component of something larger. The difference between the SDK and the raw client is the amount of plumbing you accept, and the difference between the SDK and an execution framework is scope: this package is a data pipe with a buffer, not a strategy runner.

## MIT terms and a release line that moves every few weeks

The package is MIT licensed, with the licence text carried in the repository LICENSE file and in the headers of the source files, so commercial use and modification are both straightforward and your own legal review should cover how you ship it in a product. The project is not archived and its last push was on 2026-10-12. The release history shows a steady line rather than bursts: 2.16.1 on 2026-09-21, 2.16.0 on 2026-09-13 and 2.15.2 on 2026-08-26, so a minor version appeared roughly every one to two weeks over that period, with patch releases in between. For a client that talks to a live exchange this matters twice over. A new release can mean new channel support or a fix for a changed exchange format, and it can also mean a change in behaviour that your own code depends on, so pinning an exact version and reading the CHANGELOG.md file before each upgrade is the sensible routine. The repository also carries a TASKS.md file and a wiki, which suggests the author keeps an open list of work, and the releases are built and published to GitHub and PyPI by workflow, with a separate conda-forge build.

## Conclusion

Take unicorn-binance-websocket-api when your Python service needs several Binance websocket streams at once across more than one Binance environment, and when you would rather inherit a tested connection manager than write one. Do not take it if you need documented behaviour around dropped sockets, because the README does not describe a reconnect or backoff policy, or if your deployment forbids the Cython build step its setup.py performs. Before you build on it, connect once to binance.com with the trade channel and kill the network for a minute to see how your own reconnect logic behaves, and pin the package version, since the release line moved from 2.15.2 to 2.16.1 in under a month.

## FAQ

### How do I create a Binance websocket stream with unicorn-binance-websocket-api?

Instantiate BinanceWebSocketApiManager with the exchange you want, for example exchange="binance.com", then call create_stream with your channels and markets. The README shows trade and kline_1m channels across btcusdt, bnbbtc and ethbtc in three lines.

### How do I read data from the stream buffer in unicorn-binance-websocket-api?

Call pop_stream_data_from_stream_buffer, which returns the oldest entry, and loop until you have what you need. The README example prints each returned item inside a while True loop.

### Can unicorn-binance-websocket-api be used with an async callback?

Yes. The create_stream method accepts a process_stream_data callback, and the README shows an async def version that awaits inside the callback, alongside a plain synchronous callback.

## Sources

- [License: MIT](https://github.com/oliver-zehentleitner/unicorn-binance-websocket-api/blob/master/LICENSE)
- [oliver-zehentleitner/unicorn-binance-websocket-api on GitHub](https://github.com/oliver-zehentleitner/unicorn-binance-websocket-api)
- [Project website](https://oliver-zehentleitner.github.io/unicorn-binance-websocket-api)
- [README](https://github.com/oliver-zehentleitner/unicorn-binance-websocket-api/blob/master/README.md)
- [Releases](https://github.com/oliver-zehentleitner/unicorn-binance-websocket-api/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oliver-zehentleitner-unicorn-binance-websocket-api