# binance-sdk
`binance-sdk` is an another unofficial Binance SDK for python 3.7+, which:
- Based on [Binance Official API Docs v3](https://github.com/binance-exchange/binance-official-api-docs).
- 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`](#orderbookhandlerbasekwargs)
- Supports to change API endpoints, so that we could use faster API hosts.
## Install
```sh
# Without pandas support
pip install binance-sdk
```
or
```sh
# With pandas support
pip install binance-sdk[pandas]
```
## Basic Usage
```py
#!/usr/bin/env python
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.
```py
#!/usr/bin/env python
from binance import Client, TickerHandlerBase, SubType
client = Client(api_key)
async def main():
# Implement your own TickerHandler.
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
"""
# If binance-sdk is installed with pandas support, then
# `ticker` will be a `DataFrame` with columns renamed
# Otherwise, it is unnecessary to call `super().receive`.
ticker_df = super().receive(payload)
# Just print the ticker
print(ticker_df)
# Register the handler for `SubType.TICKER`
client.handler(TickerPrinter())
# Subscribe to ticker change for symbol BTCUSDT
await client.subscribe(SubType.TICKER, 'BTCUSDT')
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
# Run the loop forever to keep receiving messages
loop.run_forever()
# It prints a pandas.DataFrame for each message
# type event_time symbol open high low ...
# 0 24hrTicker 1581597461196 BTCUSDT 10328.26000000 10491.00000000 10080.00000000 ...
# ...(to be continued)
```
### Subscribe to more symbol pairs and types
```py
# This will subscribe to
# - bnbusdt@aggTrade
# - bnbusdt@depth
# - bnbbtc@aggTrade
# - bnbbtc@depth
await client.subscribe(
# We could also subscribe multiple types
# for both `BNBUSDT` and 'BNBBTC'
[
SubType.AGG_TRADE,
SubType.ORDER_BOOK
],
# We could subscribe more than one symbol pairs at a time
[
# Which is equivalent to `BNBUSDT`
'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
```py
client.handler(MyTradeHandler(), MyOrderBookHandler(), MyKlineHandler())
```
### Subscribe to user streams
```py
# Before subscribe to user stream, you need to provide `api_secret` (and also `api_key`)
client.secret(api_secret)
# Or, you should provide `api_secret` when initialize the client
# ```
# client = Client(api_key, api_secret)
# ```
# binance-sdk will handle user listen key internally without your concern
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`
```py
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):
# By calling `super().receive(exception)`,
# it will print the error stack.
super().receive(exception)
await send_to_monitor(exception)
client.handler(KlineHandler())
client.handler(HandlerExceptionHandler())
```
If you just want to print error stacks, we could:
```py
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](#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.
```py
from binance import (
OrderSide,
OrderType,
TimeInForce
)
# All arguments are keyworded arguments.
await client.create_order(
symbol='BTCUSDT',
# You could use string `BUY` (NOT recommended) instead of
# the built-in enum types of Binance-sdk.
# But it is a good practise to use enums which could help
# us to avoid spelling mistakes, and save our money.
side=OrderSide.BUY,
type=OrderType.LIMIT,
timeInForce=TimeInForce.GTC,
# Binance-sdk will not handle Decimals for you,
# so you'd better to know how to deal with python float precisions.
# Or you could use string-type quantity.
quantity=10.,
# It is better to use string type instead of float.
# The same as `quantity`
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`](https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md#endpoint-security-type)
### 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](https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md#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)
- **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.
```py
from binance import SubType, KlineInterval
await client.subscribe(SubType.TICKER, 'BNBUSDT')
# SubType.ALL_MARKET_MINI_TICKERS with default param
await client.subscribe(SubType.ALL_MARKET_MINI_TICKERS)
# SubType.ALL_MARKET_MINI_TICKERS with update interval 3000ms
await client.subscribe(SubType.ALL_MARKET_MINI_TICKERS, 3000)
# Subcribe to multiple types
await client.subscribe(
(SubType.KLINE, 'BTC_USDT', KlineInterval.DAY),
(SubType.TICKER, 'BNBUSDT'),
(
[
SubType.ORDER_BOOK,
SubType.TRADE
],
['BNBUSDT', 'BTCUSDT']
),
(SubType.ALL_MARKET_MINI_TICKERS,) # <-- PAY ATTENTION to the `,` here
)
```
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](https://tools.ietf.org/html/rfc6455#section-7.4.2)
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.
```py
class MyTradeHandler(TradeHandlerBase):
async def receive(self, payload):
# If pandas is installed, then `payload` is a `pandas.DataFrame`,
# otherwise is a dict.
df = super().receive(payload)
# If you don't want the `pandas.DataFrame`, use `payload` directly
await saveTrade(df)
client.handler(MyTradeHandler())
```
We could also register multiple handlers at one time
```py
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`
- `SubType.KLINE`
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
- `SubType.USER`
## RetryPolicy
Retry policy is used by binance-sdk to determine what to do next after the client fails to do some certain thing.
```py
abandon, delay = stream_retry_policy(info)
# `info.fails` is the counter number of
# how many times has the stream encountered the connection failure.
# If the stream is disconnected just now for the first time, `info.fails` will be `1`
# `info.exception` is the exception that raised which caused the failure
# If abandon is `True`, then the client will give up reconnecting.
# Otherwise:
# - The client will asyncio.sleep `delay` seconds before reconnecting.
```
## 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](https://github.com/binance-exchange/binance-official-api-docs/blob/master/web-socket-streams.md#how-to-manage-a-local-order-book-correctly).
Specifically, `OrderBookHandlerBase` does the job.
We could get the managed `OrderBook` object by method `handler.orderbook(symbol)`.
```py
async def main():
client = Client(api_key)
# Unlike other handlers, we usually do not need to inherit `OrderBookHandlerBase`,
# unless we need to receive the raw payload of 'depthUpdate' message
handler = OrderBookHandlerBase()
client.handler(handler)
await client.subscribe(SubType.ORDER_BOOK, 'BTCUSDT')
# Get the reference of OrderBook object for 'BTCUSDT'
orderbook = handler.orderbook('BTCUSDT')
while True:
# If the `retry_policy` never abandon a retry,
# the 'try' block could be emitted
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.
```py
async def main():
# PAY attention that `orderbook` should be run in an event loop
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
- **limit** `int`
Set depth limit which is used by [binance reset api](https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md#order-book).
### orderbook.set_retry_policy(retry_policy) -> None
- **retry_policy** `RetryPolicy`
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`
```py
async def start_listening_updates(orderbook):
# This is an infinite loop
while True:
await orderbook.updated()
# do something
def start():
return asyncio.create_task(start_listening_updates(orderbook))
task = start()
# If we want to stop listening
task.cancel()
```
## License
[MIT](../LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/mastergod/binance-sdk",
"name": "binance-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "binance exchange sdk rest api bitcoin btc bnb ethereum eth neo",
"author": "Master God",
"author_email": "you-dont-know-who@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/aa/29/1b3d6d843d13112eb3d7f5db62e89050578f13f463a8bc7f3edd388484cc/binance_sdk-1.3.4.tar.gz",
"platform": null,
"description": "# binance-sdk\n\n`binance-sdk` is an another unofficial Binance SDK for python 3.7+, which:\n\n- Based on [Binance Official API Docs v3](https://github.com/binance-exchange/binance-official-api-docs).\n- Uses Binance's new websocket stream which supports live pub/sub so that we only need **ONE** websocket connection.\n- Has an optional `pandas.DataFrame` support. If `pandas` is installed, columns of all stream data frames are renamed for readability.\n- Based on python `async`/`await`\n- 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`](#orderbookhandlerbasekwargs)\n- Supports to change API endpoints, so that we could use faster API hosts.\n\n## Install\n\n```sh\n# Without pandas support\npip install binance-sdk\n```\n\nor\n\n```sh\n# With pandas support\npip install binance-sdk[pandas]\n```\n\n## Basic Usage\n\n```py\n#!/usr/bin/env python\n\nimport asyncio\nfrom binance import Client\n\nclient = Client()\n\nasync def main():\n print(await client.get_exchange_info())\n\nloop = asyncio.get_event_loop()\nloop.run_until_complete(main())\n```\n\n## Handling messages\n\nBinance-sdk provides handler-based APIs to handle all websocket messages, and you are able to not worry about websockets.\n\n```py\n#!/usr/bin/env python\n\nfrom binance import Client, TickerHandlerBase, SubType\n\nclient = Client(api_key)\n\nasync def main():\n # Implement your own TickerHandler.\n class TickerPrinter(TickerHandlerBase):\n async def receive(self, payload):\n \"\"\"The function to receive ticker streams.\n The function could either be sync or async\n\n Args:\n payload (dict): the raw stream payload which is\n message['data'] of the original stream message\n \"\"\"\n\n # If binance-sdk is installed with pandas support, then\n # `ticker` will be a `DataFrame` with columns renamed\n # Otherwise, it is unnecessary to call `super().receive`.\n ticker_df = super().receive(payload)\n\n # Just print the ticker\n print(ticker_df)\n\n # Register the handler for `SubType.TICKER`\n client.handler(TickerPrinter())\n\n # Subscribe to ticker change for symbol BTCUSDT\n await client.subscribe(SubType.TICKER, 'BTCUSDT')\n\nloop = asyncio.get_event_loop()\nloop.run_until_complete(main())\n\n# Run the loop forever to keep receiving messages\nloop.run_forever()\n\n# It prints a pandas.DataFrame for each message\n\n# type event_time symbol open high low ...\n# 0 24hrTicker 1581597461196 BTCUSDT 10328.26000000 10491.00000000 10080.00000000 ...\n\n# ...(to be continued)\n```\n\n### Subscribe to more symbol pairs and types\n\n```py\n# This will subscribe to\n# - bnbusdt@aggTrade\n# - bnbusdt@depth\n# - bnbbtc@aggTrade\n# - bnbbtc@depth\nawait client.subscribe(\n # We could also subscribe multiple types\n # for both `BNBUSDT` and 'BNBBTC'\n [\n SubType.AGG_TRADE,\n SubType.ORDER_BOOK\n ],\n # We could subscribe more than one symbol pairs at a time\n [\n # Which is equivalent to `BNBUSDT`\n 'BNB_USDT',\n 'BNBBTC'\n ]\n)\n```\n\nAnd since we subscribe to **THREE** new types of messages, we need to set the handlers each of which should `isinstance()` of one of\n- `TradeHandlerBase`\n- `AggTradeHandlerBase`\n- `OrderBookHandlerBase`\n- `KlineHandlerBase`\n- `MiniTickerHandlerBase`\n- `TickerHandlerBase`\n- `AllMarketMiniTickersHandlerBase`\n- `AllMarketTickersHandlerBase`\n- `AccountInfoHandlerBase`\n- `AccountPositionHandlerBase`\n- `BalanceUpdateHandlerBase`\n- `OrderUpdateHandlerBase`\n- `OrderListStatusHandlerBase`\n- `HandlerExceptionHandlerBase` a special handler to handle stream exceptions\n\n```py\nclient.handler(MyTradeHandler(), MyOrderBookHandler(), MyKlineHandler())\n```\n\n### Subscribe to user streams\n\n```py\n# Before subscribe to user stream, you need to provide `api_secret` (and also `api_key`)\nclient.secret(api_secret)\n\n# Or, you should provide `api_secret` when initialize the client\n# ```\n# client = Client(api_key, api_secret)\n# ```\n\n# binance-sdk will handle user listen key internally without your concern\nawait client.subscribe(SubType.USER)\n```\n\n### Subscribe to handler exceptions\n\n`Binance-sdk` receives stream messages in background tasks, so sometimes it is difficult to detect the exceptions raised in `receive` function of user handlers.\n\nFortunately, we could use `HandlerExceptionHandlerBase`\n\n```py\nfrom binance import (\n HandlerExceptionHandlerBase,\n KlineHandlerBase\n)\n\nclass KlineHandler(KlineHandlerBase):\n def receive(self, payload):\n raise RuntimeError('this will ruin my day')\n\nclass HandlerExceptionHandler(HandlerExceptionHandlerBase):\n async def receive(self, exception):\n # By calling `super().receive(exception)`,\n # it will print the error stack.\n super().receive(exception)\n\n await send_to_monitor(exception)\n\nclient.handler(KlineHandler())\nclient.handler(HandlerExceptionHandler())\n```\n\nIf you just want to print error stacks, we could:\n\n```py\nclient.handler(HandlerExceptionHandlerBase())\n```\n\n# APIs\n\n## Client(**kwargs)\n\nAll arguments of the constructor Client are keyworded arguments and all optional.\n\n- **api_key?** `str=None` binance api key\n- **api_secret?** `str=None` binance api secret\n- **request_params?** `dict=None` global request params for aiohttp\n- **stream_retry_policy?** `Callable[[int, Exception], Tuple[bool, int, bool]]` retry policy for websocket stream. For details, see [RetryPolicy](#retrypolicy)\n- **stream_timeout?** `int=5` seconds util the stream reach an timeout error\n- **api_host?** `str='https://api.binance.com'` to specify another API host for rest API requests. \u8fd9\u4e2a\u53c2\u6570\u7684\u5b58\u5728\u610f\u4e49\uff0c\u4f7f\u7528\u65b9\u6cd5\uff0c\u4e0d\u7d2f\u8ff0\uff0c\u4f60\u61c2\u7684\u3002\n- **stream_host?** `str='wss://stream.binance.com'` to specify another stream host for websocket connections.\n\nCreate a binance client.\n\nEach API method accepts only keyworded arguments (kwargs) and has verbosed Python doc strings (Google style) which you could check out when you are coding.\n\nThe following example shows how to create a new order.\n\n```py\nfrom binance import (\n OrderSide,\n OrderType,\n TimeInForce\n)\n\n# All arguments are keyworded arguments.\nawait client.create_order(\n symbol='BTCUSDT',\n\n # You could use string `BUY` (NOT recommended) instead of\n # the built-in enum types of Binance-sdk.\n\n # But it is a good practise to use enums which could help\n # us to avoid spelling mistakes, and save our money.\n side=OrderSide.BUY,\n type=OrderType.LIMIT,\n timeInForce=TimeInForce.GTC,\n\n # Binance-sdk will not handle Decimals for you,\n # so you'd better to know how to deal with python float precisions.\n # Or you could use string-type quantity.\n quantity=10.,\n\n # It is better to use string type instead of float.\n # The same as `quantity`\n price='7000.1'\n)\n```\n\n### client.key(api_key) -> self\n\nDefine or change api key. This method is unnecessary if we only request APIs of [`SecurityType.NONE`](https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md#endpoint-security-type)\n\n### client.secret(api_secret) -> self\n\nDefine or change api secret, especially when we have not define api secret in `Client` constructor.\n\n`api_secret` is not always required for using binance-sdk. See [Endpoint security type](https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md#endpoint-security-type)\n\n### await client.get(uri, **kwargs)\n### await client.post(uri, **kwargs)\n### await client.put(uri, **kwargs)\n### await client.delete(uri, **kwargs)\n\n- **uri** `str` the request url\n- **security_type?** `SecurityType` endpoint security type. Defaults to `SecurityType.NONE`.\n\nSend a GET/POST/PUT/DELETE HTTPs request.\n\n### await client.subscribe(subtype, *subtype_params) -> None\n### await client.subscribe(*subscriptions) -> None\n\n- **subtype** `str` subscription type, should be one of `SubType.*`s. For details, see [SubType](#subtype)\n- **subtype_params** `List` params for a certain `subtype`\n- **subscriptions** `List[Tuple]` a pack of subscriptions each of which is a tuple of `subtype` and `*subtype_params`.\n\nSubscribe to a stream or multiple streams. If no websocket connection is made up, `client.subscribe` will also create a websocket connection.\n\n```py\nfrom binance import SubType, KlineInterval\n\nawait client.subscribe(SubType.TICKER, 'BNBUSDT')\n\n# SubType.ALL_MARKET_MINI_TICKERS with default param\nawait client.subscribe(SubType.ALL_MARKET_MINI_TICKERS)\n\n# SubType.ALL_MARKET_MINI_TICKERS with update interval 3000ms\nawait client.subscribe(SubType.ALL_MARKET_MINI_TICKERS, 3000)\n\n# Subcribe to multiple types\nawait client.subscribe(\n (SubType.KLINE, 'BTC_USDT', KlineInterval.DAY),\n (SubType.TICKER, 'BNBUSDT'),\n (\n [\n SubType.ORDER_BOOK,\n SubType.TRADE\n ],\n ['BNBUSDT', 'BTCUSDT']\n ),\n (SubType.ALL_MARKET_MINI_TICKERS,) # <-- PAY ATTENTION to the `,` here\n)\n```\n\nPossible exceptions:\n- `InvalidSubParamsException`\n- `UnsupportedSubTypeException`\n- `InvalidSubTypeParamException`\n- `StreamAbandonedException`\n\n### client.start() -> self\n\nStart receiving streams\n\n### client.stop() -> self\n\nStop receiving streams\n\n### await client.close(code=4999) -> None\n\n- **code** `int=4999` the custom close code for websocket. It should be in the [range 4000 - 4999](https://tools.ietf.org/html/rfc6455#section-7.4.2)\n\nClose stream connection, clear all stream subscriptions and clear all handlers.\n\n### client.handler(*handlers) -> self\n\n- **handlers** `List[Union[HandlerExceptionHandlerBase,TradeHandlerBase,...]]`\n\nRegister 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.\n\nExcept for `HandlerExceptionHandlerBase`, handlers each of whose name ends with `Base` should be inherited before use.\n\nTypically, we need to override the `def receive(self, payload)` method.\n\n```py\nclass MyTradeHandler(TradeHandlerBase):\n async def receive(self, payload):\n # If pandas is installed, then `payload` is a `pandas.DataFrame`,\n # otherwise is a dict.\n df = super().receive(payload)\n\n # If you don't want the `pandas.DataFrame`, use `payload` directly\n\n await saveTrade(df)\n\nclient.handler(MyTradeHandler())\n```\n\nWe could also register multiple handlers at one time\n\n```py\nclient.handler(MyTradeHandler(), MyTickerHandler())\n```\n\nIf we register an invalid handler, an `InvalidHandlerException` exception will be raised.\n\n## SubType\n\nIn this section, we will note the parameters for each `subtypes`\n\n### `SubType` with parameters `symbol` and `interval`\n\n- `SubType.KLINE`\n\nAnd `interval` should be one of the `KlineInterval` enumerables\n\n### `SubType`s with a param `symbol`\n\n- `SubType.TRADE`\n- `SubType.AGG_TRADE`\n- `SubType.MINI_TICKER`\n- `SubType.TICKER`\n- `SubType.ORDER_BOOK`\n\n### `SubType`s with an optional param `updateInterval=1000` (ms)\n\n- `SubType.ALL_MARKET_MINI_TICKERS`\n- `SubType.ALL_MARKET_TICKERS`\n\n### `Subtype` with no param\n\n- `SubType.USER`\n\n## RetryPolicy\n\nRetry policy is used by binance-sdk to determine what to do next after the client fails to do some certain thing.\n\n```py\nabandon, delay = stream_retry_policy(info)\n\n# `info.fails` is the counter number of\n# how many times has the stream encountered the connection failure.\n# If the stream is disconnected just now for the first time, `info.fails` will be `1`\n\n# `info.exception` is the exception that raised which caused the failure\n\n# If abandon is `True`, then the client will give up reconnecting.\n# Otherwise:\n# - The client will asyncio.sleep `delay` seconds before reconnecting.\n```\n\n## OrderBookHandlerBase(**kwargs)\n\n- **kwargs**\n - **limit?** `int=100` the limit of the depth snapshot\n - **retry_policy?** `RetryPolicy=`\n\nBy default, binance-sdk maintains the orderbook for you according to the rules of [the official documentation](https://github.com/binance-exchange/binance-official-api-docs/blob/master/web-socket-streams.md#how-to-manage-a-local-order-book-correctly).\n\nSpecifically, `OrderBookHandlerBase` does the job.\n\nWe could get the managed `OrderBook` object by method `handler.orderbook(symbol)`.\n\n```py\nasync def main():\n client = Client(api_key)\n\n # Unlike other handlers, we usually do not need to inherit `OrderBookHandlerBase`,\n # unless we need to receive the raw payload of 'depthUpdate' message\n handler = OrderBookHandlerBase()\n\n client.handler(handler)\n await client.subscribe(SubType.ORDER_BOOK, 'BTCUSDT')\n\n # Get the reference of OrderBook object for 'BTCUSDT'\n orderbook = handler.orderbook('BTCUSDT')\n\n while True:\n # If the `retry_policy` never abandon a retry,\n # the 'try' block could be emitted\n try:\n await orderbook.updated()\n except Exception as e:\n print('exception occurred')\n else:\n await doSomethingWith(orderbook.asks, orderbook.bids)\n\nloop = asyncio.get_event_loop()\nloop.run_until_complete(main())\n\nloop.run_forever()\n```\n\n## OrderBook(symbol, **kwargs)\n\n- **symbol** `str` the symbol name\n- **kwargs**\n - **limit?** `int=100` limit of the orderbook\n - **client** `Client=None` the instance of `binance.Client`\n - **retry_policy?** `Callable[[int, Exception], (bool, int, bool)]` retry policy for depth snapshot which has the same mechanism as `Client::stream_retry_policy`\n\n`OrderBook` is another public class that we could import from binance-sdk and you could also construct your own `OrderBook` instance.\n\n```py\nasync def main():\n # PAY attention that `orderbook` should be run in an event loop\n orderbook = OrderBook('BTCUSDT', client=client)\n\n await orderbook.updated()\n\n print(orderbook.asks)\n```\n\n### orderbook.set_client(client) -> None\n\n- **client** `Client` the instance of `binance.Client`\n\nSet 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.\n\n### orderbook.set_limit(limit) -> None\n\n- **limit** `int`\n\nSet depth limit which is used by [binance reset api](https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md#order-book).\n\n### orderbook.set_retry_policy(retry_policy) -> None\n\n- **retry_policy** `RetryPolicy`\n\nSet retry policy of the certain orderbook\n\n### property `orderbook.ready` -> bool\n\nThere is a property getter in `orderbook` to detect whether the asks and bids are updated in the orderbook.\n\nIf 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`.\n\n### property `orderbook.asks` -> list\n### property `orderbook.bids` -> list\n\nGet asks and bids in ascending order.\n\n### orderbook.update(payload) -> bool\n\n- **payload** `dict` the data payload of the `depthUpdate` stream message\n\nReturns `True` if the payload is valid and is updated to the orderbook, otherwise `False`\n\nIf the return value is `False`, the orderbook will automatically start fetching the snapshot\n\n### await orderbook.fetch() -> None\n\nManually fetch the snapshot.\n\nFor most scenarios, you need **NOT** to call this method because once\nthere is an invalid payload, the orderbook will fetch the snapshot itself.\n\n### await orderbook.updated() -> None\n\nWait for the next update of the orderbook.\n\nWe could also await `orderbook.updated()` to make sure the orderbook is ready.\n\nIf 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.\n\n#### Listen to the updates of `orderbook`\n\n```py\nasync def start_listening_updates(orderbook):\n # This is an infinite loop\n while True:\n await orderbook.updated()\n # do something\n\ndef start():\n return asyncio.create_task(start_listening_updates(orderbook))\n\ntask = start()\n\n# If we want to stop listening\ntask.cancel()\n```\n\n## License\n\n[MIT](../LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Binance Python SDK",
"version": "1.3.4",
"project_urls": {
"Homepage": "https://github.com/mastergod/binance-sdk"
},
"split_keywords": [
"binance",
"exchange",
"sdk",
"rest",
"api",
"bitcoin",
"btc",
"bnb",
"ethereum",
"eth",
"neo"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6c4b5bfb780614350fa5413bcf5086f6cad5d75c1743f761468d1b5a3ba30f7",
"md5": "ad2493f1458aec11b0458c95703e82ba",
"sha256": "0281eeb8619491c915721262bf6781e80df878d8b8d8168dda122fdffa8ea7c1"
},
"downloads": -1,
"filename": "binance_sdk-1.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad2493f1458aec11b0458c95703e82ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 46972,
"upload_time": "2024-10-06T10:38:34",
"upload_time_iso_8601": "2024-10-06T10:38:34.758243Z",
"url": "https://files.pythonhosted.org/packages/e6/c4/b5bfb780614350fa5413bcf5086f6cad5d75c1743f761468d1b5a3ba30f7/binance_sdk-1.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa291b3d6d843d13112eb3d7f5db62e89050578f13f463a8bc7f3edd388484cc",
"md5": "27a70b8a957e11bdd0e6c17613a9835e",
"sha256": "169c48fdeaf3f8fee5664bdc147cc43896cfc192d70b3d65ab8f5c2f2b81a2a9"
},
"downloads": -1,
"filename": "binance_sdk-1.3.4.tar.gz",
"has_sig": false,
"md5_digest": "27a70b8a957e11bdd0e6c17613a9835e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 63358,
"upload_time": "2024-10-06T10:38:36",
"upload_time_iso_8601": "2024-10-06T10:38:36.990876Z",
"url": "https://files.pythonhosted.org/packages/aa/29/1b3d6d843d13112eb3d7f5db62e89050578f13f463a8bc7f3edd388484cc/binance_sdk-1.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-06 10:38:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mastergod",
"github_project": "binance-sdk",
"github_not_found": true,
"lcname": "binance-sdk"
}
JSON
