diff --git a/CHANGELOG.md b/CHANGELOG.md index c6fcbbc9..5e30420e 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 96ef4e20..e5312c03 100644 --- a/README.md +++ b/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. diff --git a/binance/api.py b/binance/api.py index 09cf491c..3549b2a8 100644 --- a/binance/api.py +++ b/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 diff --git a/binance/websocket/binance_socket_manager.py b/binance/websocket/binance_socket_manager.py index c2c280cc..9b6aa3f9 100644 --- a/binance/websocket/binance_socket_manager.py +++ b/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 diff --git a/binance/websocket/spot/websocket_api/__init__.py b/binance/websocket/spot/websocket_api/__init__.py index 06a1e7e1..ffc05179 100644 --- a/binance/websocket/spot/websocket_api/__init__.py +++ b/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, ) diff --git a/binance/websocket/spot/websocket_stream.py b/binance/websocket/spot/websocket_stream.py index 6b7bf7e2..83449f03 100644 --- a/binance/websocket/spot/websocket_stream.py +++ b/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, ) diff --git a/binance/websocket/websocket_client.py b/binance/websocket/websocket_client.py index 230d4ba7..59c7b96a 100644 --- a/binance/websocket/websocket_client.py +++ b/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, ) diff --git a/docs/source/CHANGELOG.rst b/docs/source/CHANGELOG.rst index 6ca5ed9f..ac3b49ab 100644 --- a/docs/source/CHANGELOG.rst +++ b/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 ------------------- diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 9d66f0b1..40f065c2 100644 --- a/docs/source/getting_started.rst +++ b/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 ------- diff --git a/examples/spot/market/trades.py b/examples/spot/market/trades.py index 9093b77d..6bf0df0f 100644 --- a/examples/spot/market/trades.py +++ b/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)) diff --git a/examples/websocket/spot/websocket_api/market/historical_trades.py b/examples/websocket/spot/websocket_api/market/historical_trades.py index fde4f298..d75ea961 100644 --- a/examples/websocket/spot/websocket_api/market/historical_trades.py +++ b/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) diff --git a/examples/websocket/spot/websocket_stream/agg_trade.py b/examples/websocket/spot/websocket_stream/agg_trade.py index 51b6636c..e486c146 100644 --- a/examples/websocket/spot/websocket_stream/agg_trade.py +++ b/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")