{"id":18895635,"url":"https://github.com/binance/binance-futures-connector-python","last_synced_at":"2025-05-14T16:12:03.649Z","repository":{"id":38841705,"uuid":"428168836","full_name":"binance/binance-futures-connector-python","owner":"binance","description":"Simple python connector to Binance Futures API","archived":false,"fork":false,"pushed_at":"2024-10-31T07:09:49.000Z","size":3712,"stargazers_count":1070,"open_issues_count":35,"forks_count":287,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-04-30T13:57:49.894Z","etag":null,"topics":["binance-api","connector","crypto","futures","library","market-data","python","real-time","trading"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binance.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-15T07:48:07.000Z","updated_at":"2025-04-30T02:26:24.000Z","dependencies_parsed_at":"2024-06-18T15:25:57.095Z","dependency_job_id":"bb189eb1-7d21-4fec-a3b3-aad44e988e5a","html_url":"https://github.com/binance/binance-futures-connector-python","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binance%2Fbinance-futures-connector-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binance","download_url":"https://codeload.github.com/binance/binance-futures-connector-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254179905,"owners_count":22027884,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binance-api","connector","crypto","futures","library","market-data","python","real-time","trading"],"created_at":"2024-11-08T08:29:08.649Z","updated_at":"2025-05-14T16:12:03.602Z","avatar_url":"https://github.com/binance.png","language":"Python","readme":"# Binance Futures Public API Connector Python\n[![Python version](https://img.shields.io/pypi/pyversions/binance-futures-connector)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThis is a lightweight library that works as a connector to [Binance Futures public API](https://developers.binance.com/docs/derivatives/Introduction)\n\n- Supported APIs:\n    - USDT-M Futures `/fapi/*`\n    - COIN-M Delivery `/dapi/*`\n    - Futures/Delivery Websocket Market Stream\n    - Futures/Delivery User Data Stream\n- Inclusion of examples\n- Customizable base URL, request timeout\n- Response metadata can be displayed\n\n## Installation\n\n```bash\npip install binance-futures-connector\n```\n\n\n## RESTful APIs\n\nUsage examples:\n```python\n\nfrom binance.cm_futures import CMFutures\n\ncm_futures_client = CMFutures()\n\n# get server time\nprint(cm_futures_client.time())\n\ncm_futures_client = CMFutures(key='\u003capi_key\u003e', secret='\u003capi_secret\u003e')\n\n# Get account information\nprint(cm_futures_client.account())\n\n# Post a new order\nparams = {\n    'symbol': 'BTCUSDT',\n    'side': 'SELL',\n    'type': 'LIMIT',\n    'timeInForce': 'GTC',\n    'quantity': 0.002,\n    'price': 59808\n}\n\nresponse = cm_futures_client.new_order(**params)\nprint(response)\n```\nPlease find `examples` folder to check for more endpoints.\n\n## Authentication\nBinance supports HMAC and RSA API authentication.\n\n```python\n# HMAC Authentication\nclient = Client(api_key, api_secret)\nprint(client.account())\n\n# RSA Authentication\nkey = \"\"\nwith open(\"/Users/john/private_key.pem\", \"r\") as f: # Location of private key file\n    private_key = f.read()\nprivate_key_passphrase = \"\" # Optional: only used for encrypted RSA key\n\nclient = Client(key=key, private_key=private_key, private_key_passphrase=private_key_passphrase)\nprint(client.account())\n```\nPlease see `examples/um_futures/trade/get_account.py` or `examples/cm_futures/trade/get_account.py` for more details.\n\n### Base URL\n\nFor USDT-M Futures, if `base_url` is not provided, it defaults to `fapi.binance.com`.\u003cbr/\u003e\nFor COIN-M Delivery, if `base_url` is not provided, it defaults to `dapi.binance.com`.\u003cbr/\u003e\nIt's recommended to pass in the `base_url` parameter, even in production as Binance provides alternative URLs\n\n### Optional parameters\n\nPEP8 suggests _lowercase with words separated by underscores_, but for this connector,\nthe methods' optional parameters should follow their exact naming as in the API documentation.\n\n```python\n# Recognised parameter name\nresponse = client.query_order('BTCUSDT', orderListId=1)\n\n# Unrecognised parameter name\nresponse = client.query_order('BTCUSDT', order_list_id=1)\n```\n\n### RecvWindow parameter\n\nAdditional parameter `recvWindow` is available for endpoints requiring signature.\u003cbr/\u003e\nIt defaults to `5000` (milliseconds) and can be any value lower than `60000`(milliseconds).\nAnything beyond the limit will result in an error response from Binance server.\n\n```python\nfrom binance.cm_futures import CMFutures\n\ncm_futures_client = CMFutures(key='\u003capi_key\u003e', secret='\u003capi_secret\u003e')\nresponse = cm_futures_client.query_order('BTCUSDT', orderId=11, recvWindow=10000)\n```\n\n### Timeout\n\n`timeout` is available to be assigned with the number of seconds you find most appropriate to wait for a server response.\u003cbr/\u003e\nPlease remember the value as it won't be shown in error message _no bytes have been received on the underlying socket for timeout seconds_.\u003cbr/\u003e\nBy default, `timeout` is None. Hence, requests do not time out.\n\n```python\nfrom binance.cm_futures import CMFutures\n\nclient= CMFutures(timeout=1)\n```\n\n### Proxy\nproxy is supported\n\n```python\nfrom binance.cm_futures import CMFutures\n\nproxies = { 'https': 'http://1.2.3.4:8080' }\n\nclient= CMFutures(proxies=proxies)\n```\n\n### Response Metadata\n\nThe Binance API server provides weight usages in the headers of each response.\nYou can display them by initializing the client with `show_limit_usage=True`:\n\n```python\nfrom binance.cm_futures import CMFutures\n\nclient = CMFutures(show_limit_usage=True)\nprint(client.time())\n```\nreturns:\n\n```python\n{'limit_usage': {'x-mbx-used-weight-1m': '1'}, 'data': {'serverTime': 1653563092778}}\n```\nYou can also display full response metadata to help in debugging:\n\n```python\nclient = Client(show_header=True)\nprint(client.time())\n```\n\nreturns:\n\n```python\n{'data': {'serverTime': 1587990847650}, 'header': {'Context-Type': 'application/json;charset=utf-8', ...}}\n```\n\nIf `ClientError` is received, it'll display full response meta information.\n\n### Display logs\n\nSetting the log level to `DEBUG` will log the request URL, payload and response text.\n\n### Error\n\nThere are 2 types of error returned from the library:\n- `binance.error.ClientError`\n    - This is thrown when server returns `4XX`, it's an issue from client side.\n    - It has 4 properties:\n        - `status_code` - HTTP status code\n        - `error_code` - Server's error code, e.g. `-1102`\n        - `error_message` - Server's error message, e.g. `Unknown order sent.`\n        - `header` - Full response header.\n- `binance.error.ServerError`\n    - This is thrown when server returns `5XX`, it's an issue from server side.\n\n## Websocket\n\n### Connector v4\n\nWebSocket can be established through the following connections:\n- USD-M WebSocket Stream (`https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-market-streams/Connect`)\n- COIN-M WebSocket Stream (`https://developers.binance.com/docs/derivatives/coin-margined-futures/websocket-market-streams/Connect`)\n\n```python\n# WebSocket Stream Client\nimport time\nfrom binance.websocket.um_futures.websocket_client import UMFuturesWebsocketClient\n\ndef message_handler(_, message):\n    logging.info(message)\n\nmy_client = UMFuturesWebsocketClient(on_message=message_handler)\n\n# Subscribe to a single symbol stream\nmy_client.agg_trade(symbol=\"bnbusdt\")\ntime.sleep(5)\nlogging.info(\"closing ws connection\")\nmy_client.stop()\n```\n\n#### Request Id\n\nClient 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.\n\n```python\n# id provided by client\nmy_client.agg_trade(symbol=\"bnbusdt\", id=\"my_request_id\")\n\n# library will generate a random uuid string\nmy_client.agg_trade(symbol=\"bnbusdt\")\n```\n#### Proxy\n\nProxy is supported for both WebSocket CM futures and UM futures.\n\nTo use it, pass in the `proxies` parameter when initializing the client.\n\nThe format of the `proxies` parameter is the same as the one used in the Spot RESTful API.\n\nIt consists on a dictionary with the following format, where the key is the type of the proxy and the value is the proxy URL:\n\nFor websockets, the proxy type is `http`.\n\n```python\nproxies = { 'http': 'http://1.2.3.4:8080' }\n```\n\nYou can also use authentication for the proxy by adding the `username` and `password` parameters to the proxy URL:\n\n```python\nproxies = { 'http': 'http://username:password@host:port' }\n```\n\n```python\n# WebSocket Stream Client\nimport time\nfrom binance.websocket.um_futures.websocket_client import UMFuturesWebsocketClient\n\nproxies = {'http': 'http://1.2.3.4:8080'}\n\ndef message_handler(_, message):\n    logging.info(message)\n\nmy_client = UMFuturesWebsocketClient(on_message=message_handler, proxies=proxies)\n\n# Subscribe to a single symbol stream\nmy_client.agg_trade(symbol=\"bnbusdt\")\ntime.sleep(5)\nlogging.info(\"closing ws connection\")\nmy_client.stop()\n```\n\n\n#### Combined Streams\n- If you set `is_combined` to `True`, `\"/stream/\"` will be appended to the `baseURL` to allow for Combining streams.\n- `is_combined` defaults to `False` and `\"/ws/\"` (raw streams) will be appended to the `baseURL`.\n\nMore websocket examples are available in the `examples` folder\n\n## Websocket \u003c v4\n\n```python\nimport time\nfrom binance.websocket.um_futures.websocket_client import UMFuturesWebsocketClient\n\ndef message_handler(message):\n    print(message)\n\nmy_client = UMFuturesWebsocketClient(on_message=message_handler)\n\n# Subscribe to a single symbol stream\nmy_client.agg_trade(symbol=\"bnbusdt\")\ntime.sleep(5)\nprint(\"closing ws connection\")\nmy_client.stop()\n\n```\n\n### Heartbeat\n\nOnce connected, the websocket server sends a ping frame every 3 minutes and requires a response pong frame back within\na 10 minutes period. This package handles the pong responses automatically.\n\n## License\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinance%2Fbinance-futures-connector-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinance%2Fbinance-futures-connector-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinance%2Fbinance-futures-connector-python/lists"}