Release v3.11.0

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 3.11.0 - 2024-12-19
+### Added
+- A new optional parameter `time_unit` can be used to select the time unit.
+
 ## 3.10.0 - 2024-11-29
 ### Added
 - Margin

README.md

@@ -165,6 +165,22 @@ from binance.spot import Spot as Client
 client= Client(timeout=1)
 ```
 
+### Time Unit
+
+The `time_unit` parameter is optional and allows you to retrieve data with timestamps in `microsecond` or `millisecond`. Users can set it with the following values:
+- `microsecond`
+- `millisecond`
+- `MICROSECOND`
+- `MILLISECOND`
+
+By default, `time_unit` is set to `None` and will return a timestamp values in milliseconds.
+
+```python
+from binance.spot import Spot as Client
+
+client = Client(time_unit="microsecond")
+```
+
 ### Proxy
 
 Proxy is supported.
@@ -270,6 +286,39 @@ logging.info("closing ws connection")
 my_client.stop()
 ```
 
+### Time Unit
+
+The `time_unit` parameter is optional and allows you to retrieve data with timestamps in `microsecond` or `millisecond`. Users can set it with the following values:
+- `microsecond`
+- `millisecond`
+- `MICROSECOND`
+- `MILLISECOND`
+
+By default, `time_unit` is set to `None` and will return a timestamp values in milliseconds.
+
+```python
+# WebSocket API Client
+import logging
+from binance.websocket.spot.websocket_api import SpotWebsocketAPIClient
+
+def message_handler(_, message):
+    logging.info(message)
+
+
+my_client = SpotWebsocketAPIClient(on_message=message_handler, time_unit='microsecond')
+```
+
+```python
+# WebSocket Stream Client
+import logging
+from binance.websocket.spot.websocket_stream import SpotWebsocketStreamClient
+
+def message_handler(_, message):
+    logging.info(message)
+
+my_client = SpotWebsocketStreamClient(on_message=message_handler, time_unit="microsecond")
+```
+
 #### Proxy
 
 Proxy is supported for both WebSocket API and WebSocket Stream.

binance/__version__.py

@@ -1 +1 @@
-__version__ = "3.10.0"
+__version__ = "3.11.0"

binance/api.py

@@ -20,6 +20,7 @@ class API(object):
         proxies (obj, optional): Dictionary mapping protocol to the URL of the proxy. e.g. {'https': 'http://1.2.3.4:8080'}
         show_limit_usage (bool, optional): whether return limit usage(requests and/or orders). By default, it's False
         show_header (bool, optional): whether return the whole response header. By default, it's False
+        time_unit (str, optional): select a time unit. By default, it's None.
         private_key (str, optional): RSA private key for RSA authentication
         private_key_pass(str, optional): Password for PSA private key
     """
@@ -33,6 +34,7 @@ def __init__(
         proxies=None,
         show_limit_usage=False,
         show_header=False,
+        time_unit=None,
         private_key=None,
         private_key_pass=None,
     ):
@@ -54,6 +56,14 @@ def __init__(
             }
         )
 
+        if (
+            time_unit == "microsecond"
+            or time_unit == "millisecond"
+            or time_unit == "MILLISECOND"
+            or time_unit == "MICROSECOND"
+        ):
+            self.session.headers.update({"X-MBX-TIME-UNIT": time_unit})
+
         if show_limit_usage is True:
             self.show_limit_usage = True
 

binance/websocket/binance_socket_manager.py

@@ -24,13 +24,21 @@ def __init__(
         on_pong=None,
         logger=None,
         timeout=None,
+        time_unit=None,
         proxies: Optional[dict] = None,
     ):
         threading.Thread.__init__(self)
         if not logger:
             logger = logging.getLogger(__name__)
         self.logger = logger
-        self.stream_url = stream_url
+        self.stream_url = (
+            stream_url + f"?timeUnit={time_unit}"
+            if time_unit == "microsecond"
+            or time_unit == "millisecond"
+            or time_unit == "MILLISECOND"
+            or time_unit == "MICROSECOND"
+            else stream_url
+        )
         self.on_message = on_message
         self.on_open = on_open
         self.on_close = on_close

binance/websocket/spot/websocket_api/__init__.py

@@ -16,6 +16,7 @@ def __init__(
         on_ping=None,
         on_pong=None,
         timeout=None,
+        time_unit=None,
         logger=None,
         proxies: Optional[dict] = None,
     ):
@@ -32,6 +33,7 @@ def __init__(
             on_pong=on_pong,
             logger=logger,
             timeout=timeout,
+            time_unit=time_unit,
             proxies=proxies,
         )
 

binance/websocket/spot/websocket_stream.py

@@ -15,6 +15,7 @@ def __init__(
         on_pong=None,
         is_combined=False,
         timeout=None,
+        time_unit=None,
         logger=None,
         proxies: Optional[dict] = None,
     ):
@@ -31,6 +32,7 @@ def __init__(
             on_ping=on_ping,
             on_pong=on_pong,
             timeout=timeout,
+            time_unit=time_unit,
             logger=logger,
             proxies=proxies,
         )

binance/websocket/websocket_client.py

@@ -21,6 +21,7 @@ def __init__(
         on_pong=None,
         logger=None,
         timeout=None,
+        time_unit=None,
         proxies: Optional[dict] = None,
     ):
         if not logger:
@@ -36,6 +37,7 @@ def __init__(
             on_pong,
             logger,
             timeout,
+            time_unit,
             proxies,
         )
 
@@ -54,6 +56,7 @@ def _initialize_socket(
         on_pong,
         logger,
         timeout,
+        time_unit,
         proxies,
     ):
         return BinanceSocketManager(
@@ -66,6 +69,7 @@ def _initialize_socket(
             on_pong=on_pong,
             logger=logger,
             timeout=timeout,
+            time_unit=time_unit,
             proxies=proxies,
         )
 

docs/source/CHANGELOG.rst

@@ -2,6 +2,14 @@
 Changelog
 =========
 
+3.11.0 - 2024-12-19
+-------------------
+
+Added
+^^^^^
+
+* A new optional parameter `time_unit` can be used to select the time unit.
+
 3.10.0 - 2024-11-29
 -------------------
 

docs/source/getting_started.rst

@@ -258,6 +258,23 @@ Proxy is supported.
 
    client= Client(proxies=proxies)
 
+Time Unit
+---------
+
+The `time_unit` parameter is optional and allows you to retrieve data with timestamps in `microsecond` or `millisecond`. Users can set it with the following values:
+  * `microsecond`
+  * `millisecond`
+  * `MICROSECOND`
+  * `MILLISECOND`
+
+By default, `time_unit` is set to `None` and will return a timestamp values in milliseconds.
+
+.. code-block:: python
+
+   from binance.spot import Spot as Client
+
+   client = Client(time_unit="microsecond")
+
 Timeout
 -------
 

examples/spot/market/trades.py

@@ -6,7 +6,7 @@
 
 config_logging(logging, logging.DEBUG)
 
-spot_client = Client(base_url="https://testnet.binance.vision")
+spot_client = Client(base_url="https://testnet.binance.vision", time_unit="microsecond")
 
 logging.info(spot_client.trades("BTCUSDT"))
 logging.info(spot_client.trades("BTCUSDT", limit=10))

examples/websocket/spot/websocket_api/market/historical_trades.py

@@ -16,7 +16,9 @@ def message_handler(_, message):
     logging.info(message)
 
 
-my_client = SpotWebsocketAPIClient(on_message=message_handler, on_close=on_close)
+my_client = SpotWebsocketAPIClient(
+    on_message=message_handler, on_close=on_close, time_unit="microsecond"
+)
 
 
 my_client.historical_trades(symbol="BNBBUSD", apiKey="", limit=1)

examples/websocket/spot/websocket_stream/agg_trade.py

@@ -12,7 +12,9 @@ def message_handler(_, message):
     logging.info(message)
 
 
-my_client = SpotWebsocketStreamClient(on_message=message_handler, is_combined=True)
+my_client = SpotWebsocketStreamClient(
+    on_message=message_handler, is_combined=True, time_unit="microsecond"
+)
 
 # Subscribe to a single symbol stream
 my_client.agg_trade(symbol="bnbusdt")