python-binance: the unofficial wrapper for Binance REST API v3 and websockets

What python-binance actually removes from your code

The README is explicit that this is an unofficial Python wrapper for the Binance exchange REST API v3. That framing matters. It is not a trading framework, it does not model positions or PnL, and it does not decide anything for you. What it removes is the repetitive part of talking to Binance directly: it generates timestamps for you, sends a recvWindow by default, handles authentication with HMAC, RSA and EDDSA keys, and raises typed exceptions when the exchange rejects a request.

The audience is narrow but real. If you are writing a script that pulls historical klines into a dataframe, a service that streams order book depth, or a bot that places spot and futures orders, you are the target user. The feature list covers General, Market Data and Account endpoints, plus Margin, Futures, Portfolio Margin, Vanilla Options, the Gift Card API and withdrawals. If you only need prices, a plain requests call is shorter than a client instance.

Two clients in one package: sync Client and asyncio

The package ships a synchronous Client and an asyncio implementation. Both are constructed the same way, with an API key and secret, and both expose the same endpoint families. The sync client blocks on each call, which is fine for scripts and batch jobs. The async client is what you want when you are running several streams and order calls concurrently.

Websocket handling is where the design gets more interesting. The README describes websocket handling with reconnection and multiplexed connections, and a ThreadedWebsocketManager that runs the event loop on a separate thread so synchronous code can consume streams. Depth cache management is also provided, which saves you from maintaining the local order book yourself. The README also lists CRUD over websockets, meaning create, fetch and edit operations can go through the websocket connection rather than REST, which the project frames as a latency optimisation.

One structural detail worth knowing before you plan an upgrade: the v1.0.0 release converted websocket streams and the Depth Cache Manager to asynchronous context managers, and migrated wallet endpoints from wapi to sapi. Code written against pre-1.0 versions will not run unchanged.

Installing python-binance and placing a first test order

Installation is a single pip command. The README states the package requires v1.0.20 or higher because earlier versions call deprecated endpoints, so check the installed version rather than trusting an old requirements file.

pip install python-binance

Before any authenticated call you need an API key with the relevant permissions, and the README warns that US, Japan and other TLD users must pass tld='us' when creating the client. For a first run, the testnet flag avoids touching real funds.

from binance import Client

client = Client(api_key, api_secret, testnet=True)

# get market depth
depth = client.get_order_book(symbol='BNBBTC')

# place a test market buy order, to place an actual order use the create_order function
order = client.create_test_order(
    symbol='BNBBTC',
    side=Client.SIDE_BUY,
    type=Client.ORDER_TYPE_MARKET,
    quantity=100)

The first call returns the current order book for the pair. The second returns a validation result rather than a live order, because create_test_order only checks the order against exchange rules. Note the parameter name: type, not orderType, and the side and type values come from Client constants rather than raw strings. Historical data uses a different shape, with a date range passed as text.

klines = client.get_historical_klines("BNBBTC", Client.KLINE_INTERVAL_1MINUTE, "1 day ago UTC")

That call returns one-minute candles for the last day. The dateparser dependency is what lets you write ranges as natural language instead of epoch milliseconds.

Where the wrapper stops helping you

The wrapper is thin by design, and that shows up in two places. First, order filters. Binance rejects orders that violate a symbol's price, quantity and notional filters, and python-binance does not resolve those for you. The README links a separate article on understanding Binance order filters rather than documenting them in the API reference, which tells you the project considers that the caller's problem. If you send quantity=100 on a symbol with a tighter step size, you get an exception, not a rounded order.

Second, withdrawals. The README's own example carries the comment "check docs for assumptions around withdrawals", which is a hint that the wrapper does not add a safety layer. A withdrawal call with a wrong address is a withdrawal call.

There is also a versioning trap. The README instructs you to update often and check the changelog for new features and bug fixes. Binance changes endpoints on its own schedule, so a pinned old version can fail silently against a deprecated route. If your deployment process freezes dependencies and you do not read the changelog, this library will drift out from under you.

python-binance compared with ccxt and binance-connector

The README states the project is powered by ccxt, which is worth reading carefully: ccxt is a multi-exchange library with a unified interface, and python-binance wraps Binance specifically. The difference in approach is scope. With ccxt you write one set of calls and switch exchanges by changing a string, at the cost of an abstraction layer over exchange-specific behaviour. With python-binance you get Binance's own endpoint names, its own constants like KLINE_INTERVAL_1WEEK, and its own websocket manager, with no portability to another venue. If you will only ever trade on Binance, the wrapper's naming is closer to the exchange documentation and therefore easier to check against it.

Binance's own binance-connector is the other comparison people search for. The distinction is governance rather than capability: binance-connector is published by the exchange, while python-binance is unofficial and maintained by its author and contributors. An official connector is likely to track API changes first; an unofficial wrapper often carries convenience features that the official one does not, and this README lists several, including the threaded websocket and depth cache managers, orjson parsing, proxy support for both REST and WS, and demo trading through demo=True. Neither choice removes your obligation to read Binance's API documentation.

Licence, maintenance and upgrade cost

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the extent of what can be said here; whether MIT fits your organisation's policy on exchange-trading dependencies is a question for your own review, not something the README addresses.

On maintenance, the last push to the default branch was on 2026-06-08, the same date as the v1.0.37 release. The repository is not archived, and the release cadence visible in the notes runs at roughly one to two months between versions: v1.0.35 on 2026-02-16, v1.0.36 on 2026-03-24, v1.0.37 on 2026-06-08. The upgrade cost is mostly borne at major boundaries. The 1.0 migration rewrote websocket streams and the depth cache as async context managers and moved wallet endpoints to sapi, and the README still warns that anything below v1.0.20 is not recommended. Budget for reading the changelog on each bump rather than assuming a patch release is inert.

Editorial conclusion

Adopt python-binance if you already understand Binance's REST and websocket semantics and want a thin, sync or asyncio client that handles timestamps, recvWindow and reconnection for you. Do not adopt it if you need multi-exchange abstraction, backtesting, or a maintained record of API changes: the README points you at the changelog instead. Before writing live order code, verify three things on your own account: that your installed version is v1.0.20 or higher, that your API key permissions match the endpoints you call, and that your order parameters satisfy the symbol filters the API returns.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sammchardy/python-binance on GitHub