Metadata-Version: 2.1
Name: binance-connector
Version: 1.2.0
Summary: This is a lightweight library that works as a connector to Binance public API.
Home-page: https://github.com/binance/binance-connector-python
License: MIT
Description: # Binance Public API Connector Python
        [![Python 3.6](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/release/python-360/)
        [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
        
        This is a lightweight library that works as a connector to [Binance public API](https://github.com/binance/binance-spot-api-docs)
        
        - 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
        
        ```bash
        pip install binance-connector
        ```
        
        ## Documentation
        
        [https://binance-connector.readthedocs.io/en/latest/](https://binance-connector.readthedocs.io/en/latest/)
        
        ## RESTful APIs
        
        Usage examples:
        ```python
        from binance.spot import Spot 
        
        client = Spot()
        print(client.time())
        
        client = Spot(key='<api_key>', secret='<api_secret>')
        
        # Get account 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
        
        While `/sapi/*` endpoints don't have testnet environment yet, `/api/*` endpoints can be tested in 
        [Spot Testnet](https://testnet.binance.vision/). You can use it by changing the base URL:
        
        ```python
        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`.<br/>
        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.
        
        ```python
        # 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.<br/>
        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.
        
        ```python
        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.<br/>
        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_.<br/>
        By default, `timeout` is None. Hence, requests do not time out.
        
        ```python
        from binance.spot import Spot as Client
        
        client= Client(timeout=1)
        ```
        
        ### Proxy
        
        Proxy is supported.
        
        ```python
        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`:
        
        ```python
        from binance.spot import Spot as Client
        
        client = Client(show_limit_usage=True)
        print(client.time())
        ```
        returns:
        
        ```python
        {'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:
        
        ```python
        client = Client(show_header=True)
        print(client.time())
        ```
        
        returns:
        
        ```python
        {'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
        
        ```python
        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
        
        ```python
        from binance.websocket.spot.websocket_client import SpotWebsocketClient as WebsocketClient
        
        ws_client = WebsocketClient(stream_url='wss://testnet.binance.vision')
        ```
        
        ## Test Case
        
        ```python
        # In case packages are not installed yet
        pip install -r 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.<br/>
        If you've found a bug within this project, please open an issue to discuss what you would like to change.<br/>
        If it's an issue with the API, please open a topic at [Binance Developer Community](https://dev.binance.vision)
        
Keywords: Binance,Public API
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.6
Description-Content-Type: text/markdown
