binance-sdk
binance-sdk
is an another unofficial Binance SDK for python 3.7+, which:
- Based on Binance Official API Docs v3.
- Uses Binance's new websocket stream which supports live pub/sub so that we only need ONE websocket connection.
- Has an optional
pandas.DataFrame
support. If pandas
is installed, columns of all stream data frames are renamed for readability. - Based on python
async
/await
- Manages the order book for you (handled by
OrderBookHandlerBase
), so that you need not to worry about websocket reconnection and message losses. For details, see the section OrderBookHandlerBase
- Supports to change API endpoints, so that we could use faster API hosts.
Install
pip install binance-sdk
or
pip install binance-sdk[pandas]
Basic Usage
import asyncio
from binance import Client
client = Client()
async def main():
print(await client.get_exchange_info())
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
Handling messages
Binance-sdk provides handler-based APIs to handle all websocket messages, and you are able to not worry about websockets.
from binance import Client, TickerHandlerBase, SubType
client = Client(api_key)
async def main():
class TickerPrinter(TickerHandlerBase):
async def receive(self, payload):
"""The function to receive ticker streams.
The function could either be sync or async
Args:
payload (dict): the raw stream payload which is
message['data'] of the original stream message
"""
ticker_df = super().receive(payload)
print(ticker_df)
client.handler(TickerPrinter())
await client.subscribe(SubType.TICKER, 'BTCUSDT')
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.run_forever()
Subscribe to more symbol pairs and types
await client.subscribe(
[
SubType.AGG_TRADE,
SubType.ORDER_BOOK
],
[
'BNB_USDT',
'BNBBTC'
]
)
And since we subscribe to THREE new types of messages, we need to set the handlers each of which should isinstance()
of one of
TradeHandlerBase
AggTradeHandlerBase
OrderBookHandlerBase
KlineHandlerBase
MiniTickerHandlerBase
TickerHandlerBase
AllMarketMiniTickersHandlerBase
AllMarketTickersHandlerBase
AccountInfoHandlerBase
AccountPositionHandlerBase
BalanceUpdateHandlerBase
OrderUpdateHandlerBase
OrderListStatusHandlerBase
HandlerExceptionHandlerBase
a special handler to handle stream exceptions
client.handler(MyTradeHandler(), MyOrderBookHandler(), MyKlineHandler())
Subscribe to user streams
client.secret(api_secret)
await client.subscribe(SubType.USER)
Subscribe to handler exceptions
Binance-sdk
receives stream messages in background tasks, so sometimes it is difficult to detect the exceptions raised in receive
function of user handlers.
Fortunately, we could use HandlerExceptionHandlerBase
from binance import (
HandlerExceptionHandlerBase,
KlineHandlerBase
)
class KlineHandler(KlineHandlerBase):
def receive(self, payload):
raise RuntimeError('this will ruin my day')
class HandlerExceptionHandler(HandlerExceptionHandlerBase):
async def receive(self, exception):
super().receive(exception)
await send_to_monitor(exception)
client.handler(KlineHandler())
client.handler(HandlerExceptionHandler())
If you just want to print error stacks, we could:
client.handler(HandlerExceptionHandlerBase())
APIs
Client(**kwargs)
All arguments of the constructor Client are keyworded arguments and all optional.
- api_key?
str=None
binance api key - api_secret?
str=None
binance api secret - request_params?
dict=None
global request params for aiohttp - stream_retry_policy?
Callable[[int, Exception], Tuple[bool, int, bool]]
retry policy for websocket stream. For details, see RetryPolicy - stream_timeout?
int=5
seconds util the stream reach an timeout error - api_host?
str='https://api.binance.com'
to specify another API host for rest API requests. 这个参数的存在意义,使用方法,不累述,你懂的。 - stream_host?
str='wss://stream.binance.com'
to specify another stream host for websocket connections.
Create a binance client.
Each API method accepts only keyworded arguments (kwargs) and has verbosed Python doc strings (Google style) which you could check out when you are coding.
The following example shows how to create a new order.
from binance import (
OrderSide,
OrderType,
TimeInForce
)
await client.create_order(
symbol='BTCUSDT',
side=OrderSide.BUY,
type=OrderType.LIMIT,
timeInForce=TimeInForce.GTC,
quantity=10.,
price='7000.1'
)
client.key(api_key) -> self
Define or change api key. This method is unnecessary if we only request APIs of SecurityType.NONE
client.secret(api_secret) -> self
Define or change api secret, especially when we have not define api secret in Client
constructor.
api_secret
is not always required for using binance-sdk. See Endpoint security type
await client.get(uri, **kwargs)
await client.post(uri, **kwargs)
await client.put(uri, **kwargs)
await client.delete(uri, **kwargs)
- uri
str
the request url - security_type?
SecurityType
endpoint security type. Defaults to SecurityType.NONE
.
Send a GET/POST/PUT/DELETE HTTPs request.
await client.subscribe(subtype, *subtype_params) -> None
await client.subscribe(*subscriptions) -> None
- subtype
str
subscription type, should be one of SubType.*
s. For details, see SubType - subtype_params
List
params for a certain subtype
- subscriptions
List[Tuple]
a pack of subscriptions each of which is a tuple of subtype
and *subtype_params
.
Subscribe to a stream or multiple streams. If no websocket connection is made up, client.subscribe
will also create a websocket connection.
from binance import SubType, KlineInterval
await client.subscribe(SubType.TICKER, 'BNBUSDT')
await client.subscribe(SubType.ALL_MARKET_MINI_TICKERS)
await client.subscribe(SubType.ALL_MARKET_MINI_TICKERS, 3000)
await client.subscribe(
(SubType.KLINE, 'BTC_USDT', KlineInterval.DAY),
(SubType.TICKER, 'BNBUSDT'),
(
[
SubType.ORDER_BOOK,
SubType.TRADE
],
['BNBUSDT', 'BTCUSDT']
),
(SubType.ALL_MARKET_MINI_TICKERS,)
)
Possible exceptions:
InvalidSubParamsException
UnsupportedSubTypeException
InvalidSubTypeParamException
StreamAbandonedException
client.start() -> self
Start receiving streams
client.stop() -> self
Stop receiving streams
await client.close(code=4999) -> None
- code
int=4999
the custom close code for websocket. It should be in the range 4000 - 4999
Close stream connection, clear all stream subscriptions and clear all handlers.
client.handler(*handlers) -> self
- handlers
List[Union[HandlerExceptionHandlerBase,TradeHandlerBase,...]]
Register message handlers for streams. If we've subscribed to a stream of a certain subtype
with no corresponding handler provided, the messages of subtype
will not be handled.
Except for HandlerExceptionHandlerBase
, handlers each of whose name ends with Base
should be inherited before use.
Typically, we need to override the def receive(self, payload)
method.
class MyTradeHandler(TradeHandlerBase):
async def receive(self, payload):
df = super().receive(payload)
await saveTrade(df)
client.handler(MyTradeHandler())
We could also register multiple handlers at one time
client.handler(MyTradeHandler(), MyTickerHandler())
If we register an invalid handler, an InvalidHandlerException
exception will be raised.
SubType
In this section, we will note the parameters for each subtypes
SubType
with parameters symbol
and interval
And interval
should be one of the KlineInterval
enumerables
SubType
s with a param symbol
SubType.TRADE
SubType.AGG_TRADE
SubType.MINI_TICKER
SubType.TICKER
SubType.ORDER_BOOK
SubType
s with an optional param updateInterval=1000
(ms)
SubType.ALL_MARKET_MINI_TICKERS
SubType.ALL_MARKET_TICKERS
Subtype
with no param
RetryPolicy
Retry policy is used by binance-sdk to determine what to do next after the client fails to do some certain thing.
abandon, delay = stream_retry_policy(info)
OrderBookHandlerBase(**kwargs)
- kwargs
- limit?
int=100
the limit of the depth snapshot - retry_policy?
RetryPolicy=
By default, binance-sdk maintains the orderbook for you according to the rules of the official documentation.
Specifically, OrderBookHandlerBase
does the job.
We could get the managed OrderBook
object by method handler.orderbook(symbol)
.
async def main():
client = Client(api_key)
handler = OrderBookHandlerBase()
client.handler(handler)
await client.subscribe(SubType.ORDER_BOOK, 'BTCUSDT')
orderbook = handler.orderbook('BTCUSDT')
while True:
try:
await orderbook.updated()
except Exception as e:
print('exception occurred')
else:
await doSomethingWith(orderbook.asks, orderbook.bids)
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.run_forever()
OrderBook(symbol, **kwargs)
- symbol
str
the symbol name - kwargs
- limit?
int=100
limit of the orderbook - client
Client=None
the instance of binance.Client
- retry_policy?
Callable[[int, Exception], (bool, int, bool)]
retry policy for depth snapshot which has the same mechanism as Client::stream_retry_policy
OrderBook
is another public class that we could import from binance-sdk and you could also construct your own OrderBook
instance.
async def main():
orderbook = OrderBook('BTCUSDT', client=client)
await orderbook.updated()
print(orderbook.asks)
orderbook.set_client(client) -> None
- client
Client
the instance of binance.Client
Set the client. If client
is not specified in the constructor, then executing this method will make the orderbook to fetch the snapshot for the first time.
orderbook.set_limit(limit) -> None
Set depth limit which is used by binance reset api.
orderbook.set_retry_policy(retry_policy) -> None
Set retry policy of the certain orderbook
property orderbook.ready
-> bool
There is a property getter in orderbook
to detect whether the asks and bids are updated in the orderbook.
If there is a network malfunction of the stream which causing the gap between two depth update messages, orderbook
will fetch a new snapshot from the server, and during that time and before we merge the snapshot, orderbook.ready
is False
.
property orderbook.asks
-> list
property orderbook.bids
-> list
Get asks and bids in ascending order.
orderbook.update(payload) -> bool
- payload
dict
the data payload of the depthUpdate
stream message
Returns True
if the payload is valid and is updated to the orderbook, otherwise False
If the return value is False
, the orderbook will automatically start fetching the snapshot
await orderbook.fetch() -> None
Manually fetch the snapshot.
For most scenarios, you need NOT to call this method because once
there is an invalid payload, the orderbook will fetch the snapshot itself.
await orderbook.updated() -> None
Wait for the next update of the orderbook.
We could also await orderbook.updated()
to make sure the orderbook is ready.
If the orderbook fails to fetch depth snapshot for so many times which means the fetching is abanboned by the retry_policy
, an aiohttp
exception will be raised.
Listen to the updates of orderbook
async def start_listening_updates(orderbook):
while True:
await orderbook.updated()
def start():
return asyncio.create_task(start_listening_updates(orderbook))
task = start()
task.cancel()
License
MIT