This is a lightweight library that works as a connector to Binance public API.
Project description
Binance Public API Connector Python
This is a lightweight library that works as a connector to Binance public API
- Supported APIs:
/api/*
/sapi/*
- Spot Websocket Market Stream
- Spot User Data Stream
- Inclusion of test cases and examples
- Customizable base URL, request timeout and HTTP proxy
- Response metadata can be displayed
Installation
pip install binance-connector
Documentation
https://binance-connector.readthedocs.io
RESTful APIs
Usage examples:
from binance.spot import Spot
client = Spot()
# Get server timestamp
print(client.time())
# Get klines of BTCUSDT at 1m interval
print(client.klines("BTCUSDT", "1m"))
# Get last 10 klines of BNBUSDT at 1h interval
print(client.klines("BNBUSDT", "1h", limit=10))
# api key/secret are required for user data endpoints
client = Spot(key='<api_key>', secret='<api_secret>')
# Get account and balance information
print(client.account())
# Post a new order
params = {
'symbol': 'BTCUSDT',
'side': 'SELL',
'type': 'LIMIT',
'timeInForce': 'GTC',
'quantity': 0.002,
'price': 9500
}
response = client.new_order(**params)
print(response)
Please find examples
folder to check for more endpoints.
Testnet
Spot Testnet is available, it can be used to test /api/*
endpoints.
/sapi/*
endpoints are not available.- No UI.
- Steps to setup testnet API key. https://dev.binance.vision/t/99
To use testnet:
from binance.spot import Spot as Client
client = Client(base_url='https://testnet.binance.vision')
print(client.time())
Base URL
If base_url
is not provided, it defaults to api.binance.com
.
It's recommended to pass in the base_url
parameter, even in production as Binance provides alternative URLs
in case of performance issues:
https://api1.binance.com
https://api2.binance.com
https://api3.binance.com
Optional parameters
PEP8 suggests lowercase with words separated by underscores, but for this connector, the methods' optional parameters should follow their exact naming as in the API documentation.
# Recognised parameter name
response = client.cancel_oco_order('BTCUSDT', orderListId=1)
# Unrecognised parameter name
response = client.cancel_oco_order('BTCUSDT', order_list_id=1)
RecvWindow parameter
Additional parameter recvWindow
is available for endpoints requiring signature.
It defaults to 5000
(milliseconds) and can be any value lower than 60000
(milliseconds).
Anything beyond the limit will result in an error response from Binance server.
from binance.spot import Spot as Client
client = Client(key, secret)
response = client.get_order('BTCUSDT', orderId=11, recvWindow=10000)
Timeout
timeout
is available to be assigned with the number of seconds you find most appropriate to wait for a server response.
Please remember the value as it won't be shown in error message no bytes have been received on the underlying socket for timeout seconds.
By default, timeout
is None. Hence, requests do not time out.
from binance.spot import Spot as Client
client= Client(timeout=1)
Proxy
Proxy is supported.
from binance.spot import Spot as Client
proxies = { 'https': 'http://1.2.3.4:8080' }
client= Client(proxies=proxies)
Response Metadata
The Binance API server provides weight usages in the headers of each response.
You can display them by initializing the client with show_limit_usage=True
:
from binance.spot import Spot as Client
client = Client(show_limit_usage=True)
print(client.time())
returns:
{'data': {'serverTime': 1587990847650}, 'limit_usage': {'x-mbx-used-weight': '31', 'x-mbx-used-weight-1m': '31'}}
You can also display full response metadata to help in debugging:
client = Client(show_header=True)
print(client.time())
returns:
{'data': {'serverTime': 1587990847650}, 'header': {'Context-Type': 'application/json;charset=utf-8', ...}}
If ClientError
is received, it'll display full response meta information.
Display logs
Setting the log level to DEBUG
will log the request URL, payload and response text.
Error
There are 2 types of error returned from the library:
binance.error.ClientError
- This is thrown when server returns
4XX
, it's an issue from client side. - It has 4 properties:
status_code
- HTTP status codeerror_code
- Server's error code, e.g.-1102
error_message
- Server's error message, e.g.Unknown order sent.
header
- Full response header.
- This is thrown when server returns
binance.error.ServerError
- This is thrown when server returns
5XX
, it's an issue from server side.
- This is thrown when server returns
Websocket
from binance.websocket.spot.websocket_client import SpotWebsocketClient as WebsocketClient
def message_handler(message):
print(message)
ws_client = WebsocketClient()
ws_client.start()
ws_client.mini_ticker(
symbol='bnbusdt',
id=1,
callback=message_handler,
)
# Combine selected streams
ws_client.instant_subscribe(
stream=['bnbusdt@bookTicker', 'ethusdt@bookTicker'],
callback=message_handler,
)
ws_client.stop()
More websocket examples are available in the examples
folder
Heartbeat
Once connected, the websocket server sends a ping frame every 3 minutes and requires a response pong frame back within a 10 minutes period. This package handles the pong responses automatically.
Testnet
from binance.websocket.spot.websocket_client import SpotWebsocketClient as WebsocketClient
ws_client = WebsocketClient(stream_url='wss://testnet.binance.vision')
Test Case
# In case packages are not installed yet
pip install -r requirements/requirements-test.txt
pytest
Limitation
Futures and Vanilla Options APIs are not supported:
/fapi/*
/dapi/*
/vapi/*
- Associated Websocket Market and User Data Streams
Contributing
Contributions are welcome.
If you've found a bug within this project, please open an issue to discuss what you would like to change.
If it's an issue with the API, please open a topic at Binance Developer Community
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for binance_connector-1.11.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 855e5173e0aaa7db6380b7ce1699f0429d2fec785d18c04c3c9c4dded233be4f |
|
MD5 | 054f9e8bb04c06343af94e8a94a6da8b |
|
BLAKE2b-256 | ca70024b5c16d9140cdc47995cce6812ab7698129ec9d5570dba38b30e959248 |