python-binance/binance/client.py at develop · debugnin/python-binance

739 lines (571 loc) · 22.3 KB
#!/usr/bin/env python
# coding=utf-8
import hashlib
import hmac
import requests
import time
from .exceptions import BinanceAPIException
from .validation import validate_order
if six.PY2:
    from urllib import urlencode
elif six.PY3:
    from urllib.parse import urlencode
class Client(object):
    API_URL = 'https://www.binance.com/api'
    WEBSITE_URL = 'https://www.binance.com'
    PUBLIC_API_VERSION = 'v1'
    PRIVATE_API_VERSION = 'v3'
    _products = None
    def __init__(self, api_key, api_secret):
        """Binance API Client constructor
        :param api_key: Api Key
        :type api_key: str.
        :param api_secret: Api Secret
        :type api_secret: str.
        """
        self.API_KEY = api_key
        self.API_SECRET = api_secret
        self.session = self._init_session()
        # init DNS and SSL cert
        self.ping()
        self.get_products()
    def _init_session(self):
        session = requests.session()
        session.headers.update({'Accept': 'application/json',
                                'User-Agent': 'binance/python',
                                'X-MBX-APIKEY': self.API_KEY})
        return session
    def _create_api_uri(self, path, signed=True):
        v = self.PRIVATE_API_VERSION if signed else self.PUBLIC_API_VERSION
        return self.API_URL + '/' + v + '/' + path
    def _create_website_uri(self, path):
        return self.WEBSITE_URL + '/' + path
    def _generate_signature(self, data):
        query_string = urlencode(data)
        m = hmac.new(bytearray(self.API_SECRET, 'utf-8'), query_string.encode('utf-8'), hashlib.sha256)
        return m.hexdigest()
    def _request(self, method, path, signed, **kwargs):
        uri = self._create_api_uri(path, signed)
        data = kwargs.get('data', None)
        if data and isinstance(data, dict):
            kwargs['data'] = data
        if signed:
            # generate signature
            kwargs['data']['timestamp'] = int(time.time() * 1000)
            kwargs['data']['signature'] = self._generate_signature(kwargs['data'])
        if data and method == 'get':
            kwargs['params'] = kwargs['data']
            del(kwargs['data'])
        response = getattr(self.session, method)(uri, **kwargs)
        return self._handle_response(response)
    def _request_website(self, method, path, **kwargs):
        uri = self._create_website_uri(path)
        data = kwargs.get('data', None)
        if data and isinstance(data, dict):
            kwargs['data'] = data
        if data and method == 'get':
            kwargs['params'] = kwargs['data']
            del(kwargs['data'])
        response = getattr(self.session, method)(uri, **kwargs)
        return self._handle_response(response)
    def _handle_response(self, response):
        """Internal helper for handling API responses from the Binance server.
        Raises the appropriate exceptions when necessary; otherwise, returns the
        response.
        """
        if not str(response.status_code).startswith('2'):
            raise BinanceAPIException(response)
        return response.json()
    def _get(self, path, signed=False, **kwargs):
        return self._request('get', path, signed, **kwargs)
    def _post(self, path, signed=False, **kwargs):
        return self._request('post', path, signed, **kwargs)
    def _put(self, path, signed=False, **kwargs):
        return self._request('put', path, signed, **kwargs)
    def _delete(self, path, signed=False, **kwargs):
        return self._request('delete', path, signed, **kwargs)
    def _parse_products(self, products):
        """
        Parse the response from get_products to use for validation
        :param products:
        :return:
        """
        self._products = {}
        if 'data' in products:
            products = products['data']
        for p in products:
            self._products[p['symbol']] = p
    # Website Endpoints
    def get_products(self):
        """Return list of products currently listed on Binance
        :returns: list - List of product dictionaries
        """
        products = self._request_website('get', 'exchange/public/product')
        self._parse_products(products)
        return products
    # General Endpoints
    def ping(self):
        """Test connectivity to the Rest API.
        https://www.binance.com/restapipub.html#test-connectivity
        :returns: Empty array
        .. code-block:: python
        :raises: BinanceAPIException
        """
        return self._get('ping')
    def get_server_time(self):
        """Test connectivity to the Rest API and get the current server time.
        https://www.binance.com/restapipub.html#check-server-time
        :returns: Current server time
        .. code-block:: python
                "serverTime": 1499827319559
        :raises: BinanceAPIException
        """
        return self._get('time')
    # Market Data Endpoints
    def get_all_tickers(self):
        """Latest price for all symbols.
        https://www.binance.com/restapipub.html#symbols-price-ticker
        :returns: List of market tickers
        .. code-block:: python
                    "symbol": "LTCBTC",
                    "price": "4.00000200"
                    "symbol": "ETHBTC",
                    "price": "0.07946600"
        :raises: BinanceAPIException
        """
        return self._get('ticker/allPrices')
    def get_orderbook_tickers(self):
        """Best price/qty on the order book for all symbols.
        https://www.binance.com/restapipub.html#symbols-order-book-ticker
        :returns: List of order book market entries
        .. code-block:: python
                    "symbol": "LTCBTC",
                    "bidPrice": "4.00000000",
                    "bidQty": "431.00000000",
                    "askPrice": "4.00000200",
                    "askQty": "9.00000000"
                    "symbol": "ETHBTC",
                    "bidPrice": "0.07946700",
                    "bidQty": "9.00000000",
                    "askPrice": "100000.00000000",
                    "askQty": "1000.00000000"
        :raises: BinanceAPIException
        """
        return self._get('ticker/allBookTickers')
    def get_order_book(self, **params):
        """Get the Order Book for the market
        https://www.binance.com/restapipub.html#order-book
        :param symbol: required
        :type symbol: str
        :param limit:  Default 100; max 100
        :type limit: int
        :returns: API response
        .. code-block:: python
                "lastUpdateId": 1027024,
                "bids": [
                        "4.00000000",     # PRICE
                        []                # Can be ignored
                "asks": [
        :raises: BinanceAPIException
        """
        return self._get('depth', data=params)
    def get_aggregate_trades(self, **params):
        """Get compressed, aggregate trades. Trades that fill at the time,
        from the same order, with the same price will have the quantity aggregated.
        https://www.binance.com/restapipub.html#compressedaggregate-trades-list
        :param symbol: required
        :type symbol: str
        :param fromId:  ID to get aggregate trades from INCLUSIVE.
        :type fromId: str
        :param startTime: Timestamp in ms to get aggregate trades from INCLUSIVE.
        :type startTime: int
        :param endTime: Timestamp in ms to get aggregate trades until INCLUSIVE.
        :type endTime: int
        :param limit:  Default 500; max 500.
        :type limit: int
        :returns: API response
        .. code-block:: python
                    "a": 26129,         # Aggregate tradeId
                    "p": "0.01633102",  # Price
                    "q": "4.70443515",  # Quantity
                    "f": 27781,         # First tradeId
                    "l": 27781,         # Last tradeId
                    "T": 1498793709153, # Timestamp
                    "m": true,          # Was the buyer the maker?
                    "M": true           # Was the trade the best price match?
        :raises: BinanceAPIException
        """
        return self._get('aggTrades', data=params)
    def get_klines(self, **params):
        """Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.
        https://www.binance.com/restapipub.html#klinecandlesticks
        :param symbol: required
        :type symbol: str
        :param interval: -
        :type interval: enum
        :param limit: - Default 500; max 500.
        :type limit: int
        :param startTime:
        :type startTime: int
        :param endTime:
        :type endTime: int
        :returns: API response
        .. code-block:: python
                    "0.01577100",       # Close
                    "148976.11427815",  # Volume
                    1499644799999,      # Close time
                    "2434.19055334",    # Quote asset volume
                    308,                # Number of trades
                    "1756.87402397",    # Taker buy base asset volume
                    "28.46694368",      # Taker buy quote asset volume
                    "17928899.62484339" # Can be ignored
        :raises: BinanceAPIException
        """
        return self._get('klines', data=params)
    def get_ticker(self, **params):
        """24 hour price change statistics.
        https://www.binance.com/restapipub.html#24hr-ticker-price-change-statistics
        :param symbol: required
        :type symbol: str
        :returns: API response
        .. code-block:: python
                "priceChange": "-94.99999800",
                "priceChangePercent": "-95.960",
                "weightedAvgPrice": "0.29628482",
                "prevClosePrice": "0.10002000",
                "lastPrice": "4.00000200",
                "bidPrice": "4.00000000",
                "askPrice": "4.00000200",
                "openPrice": "99.00000000",
                "highPrice": "100.00000000",
                "lowPrice": "0.10000000",
                "volume": "8913.30000000",
                "openTime": 1499783499040,
                "closeTime": 1499869899040,
                "fristId": 28385,   # First tradeId
                "lastId": 28460,    # Last tradeId
                "count": 76         # Trade count
        :raises: BinanceAPIException
        """
        return self._get('ticker/24hr', data=params)
    # Account Endpoints
    def create_order(self, disable_validation=False, **params):
        """Send in a new order
        https://www.binance.com/restapipub.html#new-order--signed
        :param disable_validation: disable client side order validation, default False
        :type disable_validation: bool
        :param symbol: required
        :type symbol: str
        :param side: required
        :type side: enum
        :param type: required
        :type type: enum
        :param timeInForce: required if limit order
        :type timeInForce: enum
        :param quantity: required
        :type quantity: decimal
        :param price: required
        :type price: decimal
        :param newClientOrderId: A unique id for the order. Automatically generated if not sent.
        :type newClientOrderId: str
        :param stopPrice: Used with stop orders
        :type stopPrice: decimal
        :param icebergQty: Used with iceberg orders
        :type icebergQty: decimal
        :returns: API response
        .. code-block:: python
                "symbol":"LTCBTC",
                "orderId": 1,
                "clientOrderId": "myOrder1" # Will be newClientOrderId
                "transactTime": 1499827319559
        :raises: BinanceAPIException, BinanceOrderException, BinanceOrderMinAmountException, BinanceOrderMinPriceException, BinanceOrderMinTotalException, BinanceOrderUnknownSymbolException, BinanceOrderInactiveSymbolException
        """
        if not disable_validation:
            validate_order(params, self._products)
        return self._post('order', True, data=params)
    def create_test_order(self, disable_validation=False, **params):
        """Test new order creation and signature/recvWindow long. Creates and validates a new order but does not send it into the matching engine.
        https://www.binance.com/restapipub.html#test-new-order-signed
        :param disable_validation: disable client side order validation, default False
        :type disable_validation: bool
        :param symbol: required
        :type symbol: str
        :param side: required
        :type side: enum
        :param type: required
        :type type: enum
        :param timeInForce: required if limit order
        :type timeInForce: enum
        :param quantity: required
        :type quantity: decimal
        :param price: required
        :type price: decimal
        :param newClientOrderId: A unique id for the order. Automatically generated if not sent.
        :type newClientOrderId: str
        :param stopPrice: Used with stop orders
        :type stopPrice: decimal
        :param icebergQty: Used with iceberg orders
        :type icebergQty: decimal
        :param recvWindow: The number of milliseconds the request is valid for
        :type recvWindow: int
        :returns: API response
        .. code-block:: python
        :raises: BinanceAPIException, BinanceOrderException, BinanceOrderMinAmountException, BinanceOrderMinPriceException, BinanceOrderMinTotalException, BinanceOrderUnknownSymbolException, BinanceOrderInactiveSymbolException
        """
        if not disable_validation:
            validate_order(params, self._products)
        return self._post('order/test', True, data=params)
    def get_order(self, **params):
        """Check an order's status. Either orderId or origClientOrderId must be sent.
        https://www.binance.com/restapipub.html#query-order-signed
        :param symbol: required
        :type symbol: str
        :param orderId: The unique order id
        :type orderId: int
        :param origClientOrderId: optional
        :type origClientOrderId: str
        :param recvWindow: the number of milliseconds the request is valid for
        :type recvWindow: int
        :returns: API response
        .. code-block:: python
                "symbol": "LTCBTC",
                "orderId": 1,
                "clientOrderId": "myOrder1",
                "price": "0.1",
                "origQty": "1.0",
                "executedQty": "0.0",
                "status": "NEW",
                "timeInForce": "GTC",
                "type": "LIMIT",
                "side": "BUY",
                "stopPrice": "0.0",
                "icebergQty": "0.0",
        :raises: BinanceAPIException
        """
        return self._get('order', True, data=params)
    def get_all_orders(self, **params):
        """Get all account orders; active, canceled, or filled.
        https://www.binance.com/restapipub.html#all-orders-signed
        :param symbol: required
        :type symbol: str
        :param orderId: The unique order id
        :type orderId: int
        :param limit: Default 500; max 500.
        :type limit: int
        :param recvWindow: the number of milliseconds the request is valid for
        :type recvWindow: int
        :returns: API response
        .. code-block:: python
                    "symbol": "LTCBTC",
                    "orderId": 1,
                    "clientOrderId": "myOrder1",
                    "price": "0.1",
                    "origQty": "1.0",
                    "executedQty": "0.0",
                    "status": "NEW",
                    "timeInForce": "GTC",
                    "type": "LIMIT",
                    "side": "BUY",
                    "stopPrice": "0.0",
                    "icebergQty": "0.0",
        :raises: BinanceAPIException
        """
        return self._get('allOrders', True, data=params)
    def cancel_order(self, **params):
        """Cancel an active order. Either orderId or origClientOrderId must be sent.
        https://www.binance.com/restapipub.html#cancel-order-signed
        :param symbol: required
        :type symbol: str
        :param orderId: The unique order id
        :type orderId: int
        :param origClientOrderId: optional
        :type origClientOrderId: str
        :param newClientOrderId: Used to uniquely identify this cancel. Automatically generated by default.
        :type newClientOrderId: str
        :param recvWindow: the number of milliseconds the request is valid for
        :type recvWindow: int
        :returns: API response
        .. code-block:: python
                "symbol": "LTCBTC",
                "origClientOrderId": "myOrder1",
                "orderId": 1,
                "clientOrderId": "cancelMyOrder1"
        :raises: BinanceAPIException
        """
        return self._delete('order', True, data=params)
    def get_open_orders(self, **params):
        """Get all open orders on a symbol.
        https://www.binance.com/restapipub.html#current-open-orders-signed
        :param symbol: required
        :type symbol: str
        :param recvWindow: the number of milliseconds the request is valid for
        :type recvWindow: int
        :returns: API response
        .. code-block:: python
                    "symbol": "LTCBTC",
                    "orderId": 1,
                    "clientOrderId": "myOrder1",
                    "price": "0.1",
                    "origQty": "1.0",
                    "executedQty": "0.0",
                    "status": "NEW",
                    "timeInForce": "GTC",
                    "type": "LIMIT",
                    "side": "BUY",
                    "stopPrice": "0.0",
                    "icebergQty": "0.0",
        :raises: BinanceAPIException
        """
        return self._get('openOrders', True, data=params)
    # User Stream Endpoints
    def get_account(self, **params):
        """Get current account information.
        https://www.binance.com/restapipub.html#account-information-signed
        :param recvWindow: the number of milliseconds the request is valid for
        :type recvWindow: int
        :returns: API response
        .. code-block:: python
                "makerCommission": 15,
                "takerCommission": 15,
                "buyerCommission": 0,
                "sellerCommission": 0,
                "canTrade": true,
                "canWithdraw": true,
                "canDeposit": true,
                "balances": [
                        "asset": "BTC",
                        "free": "4723846.89208129",
                        "locked": "0.00000000"
                        "asset": "LTC",
                        "free": "4763368.68006011",
                        "locked": "0.00000000"
        :raises: BinanceAPIException
        """
        return self._get('account', True, data=params)
    def get_my_trades(self, **params):
        """Get trades for a specific account and symbol.
        https://www.binance.com/restapipub.html#account-trade-list-signed
        :param symbol: required
        :type symbol: str
        :param limit: Default 500; max 500.
        :type limit: int
        :param fromId: TradeId to fetch from. Default gets most recent trades.
        :type fromId: int
        :param recvWindow: the number of milliseconds the request is valid for
        :type recvWindow: int
        :returns: API response
        .. code-block:: python
                    "price": "4.00000100",
                    "qty": "12.00000000",
                    "commission": "10.10000000",
                    "commissionAsset": "BNB",
                    "isBuyer": true,
                    "isMaker": false,
                    "isBestMatch": true
        :raises: BinanceAPIException
        """
        return self._get('myTrades', True, data=params)
    # User Stream Endpoints
    def stream_get_listen_key(self):
        """Start a new user data stream and return the listen key
        https://www.binance.com/restapipub.html#start-user-data-stream-api-key
        :returns: API response
        .. code-block:: python
                "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
        :raises: BinanceAPIException
        """
        res = self._post('userDataStream', False, data={})
        return res['listenKey']
    def stream_keepalive(self, **params):
        """PING a user data stream to prevent a time out.
        https://www.binance.com/restapipub.html#keepalive-user-data-stream-api-key
        :returns: API response
        .. code-block:: python
        :raises: BinanceAPIException
        """
        return self._put('userDataStream', False, data=params)
    def stream_close(self, **params):
        """Close out a user data stream.
        https://www.binance.com/restapipub.html#close-user-data-stream-api-key
        :returns: API response
        .. code-block:: python
        :raises: BinanceAPIException
        """
        return self._delete('userDataStream', False, data=params)
FilesExpand file tree

client.py

Latest commit

History

client.py

File metadata and controls
