Skip to content

Latest commit

 

History

History
286 lines (201 loc) · 8.19 KB

README.md

File metadata and controls

286 lines (201 loc) · 8.19 KB
Raw

Binance Futures Public API Connector Python

Python version License: MIT

This is a lightweight library that works as a connector to Binance Futures public API

  • Supported APIs:
    • USDT-M Futures /fapi/*
    • COIN-M Delivery /dapi/*
    • Futures/Delivery Websocket Market Stream
    • Futures/Delivery User Data Stream
  • Inclusion of examples
  • Customizable base URL, request timeout
  • Response metadata can be displayed

Installation

pip install binance-futures-connector

RESTful APIs

Usage examples:

from binance.cm_futures import CMFutures

cm_futures_client = CMFutures()

# get server time
print(cm_futures_client.time())

cm_futures_client = CMFutures(key='<api_key>', secret='<api_secret>')

# Get account information
print(cm_futures_client.account())

# Post a new order
params = {
    'symbol': 'BTCUSDT',
    'side': 'SELL',
    'type': 'LIMIT',
    'timeInForce': 'GTC',
    'quantity': 0.002,
    'price': 59808
}

response = cm_futures_client.new_order(**params)
print(response)

Please find examples folder to check for more endpoints.

Authentication

Binance supports HMAC and RSA API authentication.

# HMAC Authentication
client = Client(api_key, api_secret)
print(client.account())

# RSA Authentication
key = ""
with open("/Users/john/private_key.pem", "r") as f: # Location of private key file
    private_key = f.read()
private_key_passphrase = "" # Optional: only used for encrypted RSA key

client = Client(key=key, private_key=private_key, private_key_passphrase=private_key_passphrase)
print(client.account())

Please see examples/um_futures/trade/get_account.py or examples/cm_futures/trade/get_account.py for more details.

Base URL

For USDT-M Futures, if base_url is not provided, it defaults to fapi.binance.com.
For COIN-M Delivery, if base_url is not provided, it defaults to dapi.binance.com.
It's recommended to pass in the base_url parameter, even in production as Binance provides alternative URLs

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.query_order('BTCUSDT', orderListId=1)

# Unrecognised parameter name
response = client.query_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.cm_futures import CMFutures

cm_futures_client = CMFutures(key='<api_key>', secret='<api_secret>')
response = cm_futures_client.query_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.cm_futures import CMFutures

client= CMFutures(timeout=1)

Proxy

proxy is supported

from binance.cm_futures import CMFutures

proxies = { 'https': 'http://1.2.3.4:8080' }

client= CMFutures(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.cm_futures import CMFutures

client = CMFutures(show_limit_usage=True)
print(client.time())

returns:

{'limit_usage': {'x-mbx-used-weight-1m': '1'}, 'data': {'serverTime': 1653563092778}}

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 code
      • error_code - Server's error code, e.g. -1102
      • error_message - Server's error message, e.g. Unknown order sent.
      • header - Full response header.
  • binance.error.ServerError
    • This is thrown when server returns 5XX, it's an issue from server side.

Websocket

Connector v4

WebSocket can be established through the following connections:

  • USD-M WebSocket Stream (https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-market-streams/Connect)
  • COIN-M WebSocket Stream (https://developers.binance.com/docs/derivatives/coin-margined-futures/websocket-market-streams/Connect)
# WebSocket Stream Client
import time
from binance.websocket.um_futures.websocket_client import UMFuturesWebsocketClient

def message_handler(_, message):
    logging.info(message)

my_client = UMFuturesWebsocketClient(on_message=message_handler)

# Subscribe to a single symbol stream
my_client.agg_trade(symbol="bnbusdt")
time.sleep(5)
logging.info("closing ws connection")
my_client.stop()

Request Id

Client can assign a request id to each request. The request id will be returned in the response message. Not mandatory in the library, it generates a uuid format string if not provided.

# id provided by client
my_client.agg_trade(symbol="bnbusdt", id="my_request_id")

# library will generate a random uuid string
my_client.agg_trade(symbol="bnbusdt")

Proxy

Proxy is supported for both WebSocket CM futures and UM futures.

To use it, pass in the proxies parameter when initializing the client.

The format of the proxies parameter is the same as the one used in the Spot RESTful API.

It consists on a dictionary with the following format, where the key is the type of the proxy and the value is the proxy URL:

For websockets, the proxy type is http.

proxies = { 'http': 'http://1.2.3.4:8080' }

You can also use authentication for the proxy by adding the username and password parameters to the proxy URL:

proxies = { 'http': 'http://username:password@host:port' }
# WebSocket Stream Client
import time
from binance.websocket.um_futures.websocket_client import UMFuturesWebsocketClient

proxies = {'http': 'http://1.2.3.4:8080'}

def message_handler(_, message):
    logging.info(message)

my_client = UMFuturesWebsocketClient(on_message=message_handler, proxies=proxies)

# Subscribe to a single symbol stream
my_client.agg_trade(symbol="bnbusdt")
time.sleep(5)
logging.info("closing ws connection")
my_client.stop()

Combined Streams

  • If you set is_combined to True, "/stream/" will be appended to the baseURL to allow for Combining streams.
  • is_combined defaults to False and "/ws/" (raw streams) will be appended to the baseURL.

More websocket examples are available in the examples folder

Websocket < v4

import time
from binance.websocket.um_futures.websocket_client import UMFuturesWebsocketClient

def message_handler(message):
    print(message)

my_client = UMFuturesWebsocketClient(on_message=message_handler)

# Subscribe to a single symbol stream
my_client.agg_trade(symbol="bnbusdt")
time.sleep(5)
print("closing ws connection")
my_client.stop()

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.

License

MIT