feat: add demo trading support (#1610)

* update gitignore

* bump version

* feat: add demo trading support

* update url

* add futures helper methods

* update conf test

* fix missing url

* 8911

* rm proxy none

* update ws_futures_demo_url

* skip failing test and update options symbol

* remove 3.7

* temporarly only test 3.12

* add several fixes including parallel testing

* fix failing tests

* run all tox versions

* update proxy on github action

* add timeout

* fix ws proxy

* add proxy fix for async ws client

* add fix for for options tests

* fix failing tests

* fix lint

* run all tox versions

* add max parallel to 1

* skip ws proxy for py37

* comment options test for py37

* remove 3.7

* increase max parallel to 2

---------

Co-authored-by: Pablo <[email protected]>

Author: carlosmiei

.github/workflows/python-app.yml

@@ -18,9 +18,9 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.9'
     - name: Install Ruff
@@ -31,49 +31,49 @@ jobs:
       run: ruff format --check .
       continue-on-error: true
 
-  build:
+  test:
     needs: lint
     runs-on: ubuntu-22.04
     timeout-minutes: 40
+    strategy:
+      max-parallel: 2
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
     env:
-      PROXY: "http://51.83.140.52:16301"
+      PROXY: "http://188.245.226.105:8911"
       TEST_TESTNET: "true"
       TEST_API_KEY: "u4L8MG2DbshTfTzkx2Xm7NfsHHigvafxeC29HrExEmah1P8JhxXkoOu6KntLICUc"
       TEST_API_SECRET: "hBZEqhZUUS6YZkk7AIckjJ3iLjrgEFr5CRtFPp5gjzkrHKKC9DAv4OH25PlT6yq5"
       TEST_FUTURES_API_KEY: "227719da8d8499e8d3461587d19f259c0b39c2b462a77c9b748a6119abd74401"
       TEST_FUTURES_API_SECRET: "b14b935f9cfacc5dec829008733c40da0588051f29a44625c34967b45c11d73c"
-    strategy:
-      max-parallel: 1
-      matrix:
-        python: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Checking env
       run: |
         echo "PROXY: $PROXY"
-        env
-    - name: Set up Python ${{ matrix.python }}
-      uses: actions/setup-python@v5
+        echo "Python version: ${{ matrix.python-version }}"
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
       with:
-        python-version: ${{ matrix.python }}
+        python-version: ${{ matrix.python-version }}
         cache: 'pip'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install pytest pytest-cov pyright tox
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         if [ -f test-requirements.txt ]; then pip install -r test-requirements.txt; fi
-    - name: Type check with pyright
+    - name: Type check with pyright (Python 3.12 only)
+      if: matrix.python-version == '3.12'
       run: pyright
     - name: Test with tox
       run: tox -e py
     - name: Coveralls Parallel
       uses: coverallsapp/github-action@v2
       with:
-        flag-name: run-${{ join(matrix.*, '-') }}
         parallel: true
   finish:
-    needs: build
+    needs: test
     if: ${{ always() }}
     runs-on: ubuntu-latest
     timeout-minutes: 5

README.rst

@@ -63,7 +63,8 @@ Features
 
 - Implementation of all General, Market Data and Account endpoints.
 - Asyncio implementation
-- Testnet support for Spot, Futures and Vanilla Options
+- Demo trading support (by providing demo=True)
+- Testnet support for Spot, Futures and Vanilla Options (deprecated)
 - Simple handling of authentication include RSA and EDDSA keys
 - No need to generate timestamps yourself, the wrapper does it for you
 - RecvWindow sent by default

binance/async_client.py

@@ -31,6 +31,7 @@ def __init__(
         tld: str = "com",
         base_endpoint: str = BaseClient.BASE_ENDPOINT_DEFAULT,
         testnet: bool = False,
+        demo: bool = False,
         loop=None,
         session_params: Optional[Dict[str, Any]] = None,
         private_key: Optional[Union[str, Path]] = None,
@@ -41,13 +42,23 @@ def __init__(
         self.https_proxy = https_proxy
         self.loop = loop or get_loop()
         self._session_params: Dict[str, Any] = session_params or {}
+        
+        # Convert https_proxy to requests_params format for BaseClient
+        if https_proxy and requests_params is None:
+            requests_params = {'proxies': {'http': https_proxy, 'https': https_proxy}}
+        elif https_proxy and requests_params is not None:
+            if 'proxies' not in requests_params:
+                requests_params['proxies'] = {}
+            requests_params['proxies'].update({'http': https_proxy, 'https': https_proxy})
+        
         super().__init__(
             api_key,
             api_secret,
             requests_params,
             tld,
             base_endpoint,
             testnet,
+            demo,
             private_key,
             private_key_pass,
             time_unit=time_unit,
@@ -62,6 +73,7 @@ async def create(
         tld: str = "com",
         base_endpoint: str = BaseClient.BASE_ENDPOINT_DEFAULT,
         testnet: bool = False,
+        demo: bool = False,
         loop=None,
         session_params: Optional[Dict[str, Any]] = None,
         private_key: Optional[Union[str, Path]] = None,
@@ -76,6 +88,7 @@ async def create(
             tld,
             base_endpoint,
             testnet,
+            demo,
             loop,
             session_params,
             private_key,
@@ -151,6 +164,9 @@ async def _request(
             url_encoded_data = urlencode(dict_data)
             data = f"{url_encoded_data}&signature={signature}"
 
+        # Remove proxies from kwargs since aiohttp uses 'proxy' parameter instead
+        kwargs.pop('proxies', None)
+        
         async with getattr(self.session, method)(
             yarl.URL(uri, encoded=True),
             proxy=self.https_proxy,
@@ -1876,6 +1892,77 @@ async def futures_create_order(self, **params):
             params["newClientOrderId"] = self.CONTRACT_ORDER_PREFIX + self.uuid22()
         return await self._request_futures_api("post", "order", True, data=params)
 
+    async def futures_limit_order(self, **params):
+        """Send in a new futures limit order.
+
+        https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api
+
+        """
+        if "newClientOrderId" not in params:
+            params["newClientOrderId"] = self.CONTRACT_ORDER_PREFIX + self.uuid22()
+        params["type"] = "LIMIT"
+        return await self._request_futures_api("post", "order", True, data=params)
+
+    async def futures_market_order(self, **params):
+        """Send in a new futures market order.
+
+        https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api
+
+        """
+        if "newClientOrderId" not in params:
+            params["newClientOrderId"] = self.CONTRACT_ORDER_PREFIX + self.uuid22()
+        params["type"] = "MARKET"
+        return await self._request_futures_api("post", "order", True, data=params)
+
+
+    async def futures_limit_buy_order(self, **params):
+        """Send in a new futures limit buy order.
+
+        https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api
+
+        """
+        if "newClientOrderId" not in params:
+            params["newClientOrderId"] = self.CONTRACT_ORDER_PREFIX + self.uuid22()
+        params["side"] = "BUY"
+        params["type"] = "LIMIT"
+        return await self._request_futures_api("post", "order", True, data=params)
+
+    async def futures_limit_sell_order(self, **params):
+        """Send in a new futures limit sell order.
+
+        https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api
+
+        """
+        if "newClientOrderId" not in params:
+            params["newClientOrderId"] = self.CONTRACT_ORDER_PREFIX + self.uuid22()
+        params["side"] = "SELL"
+        params["type"] = "LIMIT"
+        return await self._request_futures_api("post", "order", True, data=params)
+
+    async def futures_market_buy_order(self, **params):
+        """Send in a new futures market buy order.
+
+        https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api
+
+        """
+        if "newClientOrderId" not in params:
+            params["newClientOrderId"] = self.CONTRACT_ORDER_PREFIX + self.uuid22()
+        params["side"] = "BUY"
+        params["type"] = "MARKET"
+        return await self._request_futures_api("post", "order", True, data=params)
+
+    async def futures_market_sell_order(self, **params):
+        """Send in a new futures market sell order.
+
+        https://developers.binance.com/docs/derivatives/usds-margined-futures/trade/rest-api
+
+        """
+        if "newClientOrderId" not in params:
+            params["newClientOrderId"] = self.CONTRACT_ORDER_PREFIX + self.uuid22()
+        params["side"] = "SELL"
+        params["type"] = "MARKET"
+        return await self._request_futures_api("post", "order", True, data=params)
+
     async def futures_modify_order(self, **params):
         """Modify an existing order. Currently only LIMIT order modification is supported.
 

binance/base_client.py

@@ -22,23 +22,28 @@
 class BaseClient:
     API_URL = "https://api{}.binance.{}/api"
     API_TESTNET_URL = "https://testnet.binance.vision/api"
+    API_DEMO_URL = "https://demo-api.binance.com/api"
     MARGIN_API_URL = "https://api{}.binance.{}/sapi"
     WEBSITE_URL = "https://www.binance.{}"
     FUTURES_URL = "https://fapi.binance.{}/fapi"
     FUTURES_TESTNET_URL = "https://testnet.binancefuture.com/fapi"
+    FUTURES_DEMO_URL = "https://demo-fapi.binance.com/fapi"
     FUTURES_DATA_URL = "https://fapi.binance.{}/futures/data"
     FUTURES_DATA_TESTNET_URL = "https://testnet.binancefuture.com/futures/data"
     FUTURES_COIN_URL = "https://dapi.binance.{}/dapi"
     FUTURES_COIN_TESTNET_URL = "https://testnet.binancefuture.com/dapi"
+    FUTURES_COIN_DEMO_URL = "https://demo-dapi.binance.com/dapi"
     FUTURES_COIN_DATA_URL = "https://dapi.binance.{}/futures/data"
     FUTURES_COIN_DATA_TESTNET_URL = "https://testnet.binancefuture.com/futures/data"
     OPTIONS_URL = "https://eapi.binance.{}/eapi"
     OPTIONS_TESTNET_URL = "https://testnet.binanceops.{}/eapi"
     PAPI_URL = "https://papi.binance.{}/papi"
     WS_API_URL = "wss://ws-api.binance.{}/ws-api/v3"
     WS_API_TESTNET_URL = "wss://ws-api.testnet.binance.vision/ws-api/v3"
+    WS_API_DEMO_URL = "wss://demo-ws-api.binance.com/ws-api/v3"
     WS_FUTURES_URL = "wss://ws-fapi.binance.{}/ws-fapi/v1"
     WS_FUTURES_TESTNET_URL = "wss://testnet.binancefuture.com/ws-fapi/v1"
+    WS_FUTURES_DEMO_URL = "wss://testnet.binancefuture.com/ws-fapi/v1"
     PUBLIC_API_VERSION = "v3"
     PRIVATE_API_VERSION = "v3"
     MARGIN_API_VERSION = "v1"
@@ -157,6 +162,7 @@ def __init__(
         tld: str = "com",
         base_endpoint: str = BASE_ENDPOINT_DEFAULT,
         testnet: bool = False,
+        demo: bool = False,
         private_key: Optional[Union[str, Path]] = None,
         private_key_pass: Optional[str] = None,
         loop: Optional[asyncio.AbstractEventLoop] = None,
@@ -201,15 +207,27 @@ def __init__(
         self._requests_params = requests_params
         self.response = None
         self.testnet = testnet
+        self.demo = demo
         self.timestamp_offset = 0
-        ws_api_url = self.WS_API_TESTNET_URL if testnet else self.WS_API_URL.format(tld)
+        ws_api_url = self.WS_API_URL.format(tld)
+        if testnet:
+            ws_api_url = self.WS_API_TESTNET_URL
+        elif demo:
+            ws_api_url = self.WS_API_DEMO_URL
         if self.TIME_UNIT:
             ws_api_url += f"?timeUnit={self.TIME_UNIT}"
-        self.ws_api = WebsocketAPI(url=ws_api_url, tld=tld)
-        ws_future_url = (
-            self.WS_FUTURES_TESTNET_URL if testnet else self.WS_FUTURES_URL.format(tld)
-        )
-        self.ws_future = WebsocketAPI(url=ws_future_url, tld=tld)
+        # Extract proxy from requests_params for WebSocket connections
+        https_proxy = None
+        if requests_params and 'proxies' in requests_params:
+            https_proxy = requests_params['proxies'].get('https') or requests_params['proxies'].get('http')
+        
+        self.ws_api = WebsocketAPI(url=ws_api_url, tld=tld, https_proxy=https_proxy)
+        ws_future_url = self.WS_FUTURES_URL.format(tld)
+        if testnet:
+            ws_future_url = self.WS_FUTURES_TESTNET_URL
+        elif demo:
+            ws_future_url = self.WS_FUTURES_DEMO_URL
+        self.ws_future = WebsocketAPI(url=ws_future_url, tld=tld, https_proxy=https_proxy)
         self.loop = loop or get_loop()
 
     def _get_headers(self) -> Dict:
@@ -250,6 +268,8 @@ def _create_api_uri(
         url = self.API_URL
         if self.testnet:
             url = self.API_TESTNET_URL
+        elif self.demo:
+            url = self.API_DEMO_URL
         v = self.PRIVATE_API_VERSION if signed else version
         return url + "/" + v + "/" + path
 
@@ -273,6 +293,8 @@ def _create_futures_api_uri(self, path: str, version: int = 1) -> str:
         url = self.FUTURES_URL
         if self.testnet:
             url = self.FUTURES_TESTNET_URL
+        elif self.demo:
+            url = self.FUTURES_DEMO_URL
         options = {
             1: self.FUTURES_API_VERSION,
             2: self.FUTURES_API_VERSION2,
@@ -290,6 +312,8 @@ def _create_futures_coin_api_url(self, path: str, version: int = 1) -> str:
         url = self.FUTURES_COIN_URL
         if self.testnet:
             url = self.FUTURES_COIN_TESTNET_URL
+        elif self.demo:
+            url = self.FUTURES_COIN_DEMO_URL
         options = {
             1: self.FUTURES_API_VERSION,
             2: self.FUTURES_API_VERSION2,