trd-utils 0.0.13__py3-none-any.whl → 0.0.15__py3-none-any.whl

trd_utils/__init__.py

@@ -1,3 +1,3 @@
 
-__version__ = "0.0.13"
+__version__ = "0.0.15"
 

trd_utils/exchanges/README.md

@@ -0,0 +1,201 @@
+# trd_utils.exchanges
+
+All exchange clients are stored inside of their own directory.
+Some of these are not really _exchange_, but a tracker for a specific exchange/blockchain. We will still put them in this section as long as they are for a _specific_ one.
+
+If they are for a very general platform, such as tradingview, they should be put in a separate directory entirely.
+
+## Writing code for a new exchange
+
+Here is a boilerplate code that we can use for creating a new exchange/tracker class:
+
+```py
+import asyncio
+from decimal import Decimal
+import json
+import logging
+from typing import Type
+import httpx
+
+import time
+from pathlib import Path
+
+# from trd_utils.exchanges.my_exchange.my_exchange_types import (
+    # SomeAPIType
+# )
+from trd_utils.cipher import AESCipher
+from trd_utils.exchanges.exchange_base import ExchangeBase
+
+logger = logging.getLogger(__name__)
+
+
+class MyExchangeClient(ExchangeBase):
+    ###########################################################
+    # region client parameters
+    my_exchange_api_base_host: str = "https://exchange.com"
+    my_exchange_api_base_url: str = "https://exchange.com/api/v1"
+    origin_header: str = "https://exchange.com/"
+
+    timezone: str = "Etc/UTC"
+
+    # endregion
+    ###########################################################
+    # region client constructor
+    def __init__(
+        self,
+        account_name: str = "default",
+        http_verify: bool = True,
+        fav_letter: str = "^",
+        read_session_file: bool = True,
+        sessions_dir: str = "sessions",
+    ):
+        self.httpx_client = httpx.AsyncClient(
+            verify=http_verify,
+            http2=True,
+            http1=False,
+        )
+        self.account_name = account_name
+        self._fav_letter = fav_letter
+        self.sessions_dir = sessions_dir
+
+        if read_session_file:
+            self.read_from_session_file(f"{sessions_dir}/{self.account_name}.bf")
+
+    # endregion
+    ###########################################################
+    # region something
+    # async def get_something_info(self) -> SomethingInfoResponse:
+    #     headers = self.get_headers()
+    #     return await self.invoke_get(
+    #         f"{self.my_exchange_api_base_url}/something/info",
+    #         headers=headers,
+    #         model=SomethingInfoResponse,
+    #     )
+    # endregion
+    ###########################################################
+    # region another-thing
+    # async def get_another_thing_info(self, uid: int) -> AnotherThingInfoResponse:
+    #     payload = {
+    #         "uid": uid,
+    #     }
+    #     headers = self.get_headers()
+    #     return await self.invoke_post(
+    #         f"{self.my_exchange_api_base_url}/another-thing/info",
+    #         headers=headers,
+    #         content=payload,
+    #         model=CopyTraderInfoResponse,
+    #     )
+
+    # endregion
+    ###########################################################
+    # region client helper methods
+    def get_headers(self, payload=None, needs_auth: bool = False) -> dict:
+        the_timestamp = int(time.time() * 1000)
+        the_headers = {
+            # "Host": self.my_exchange_api_base_host,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Origin": self.origin_header,
+            "X-Tz": self.timezone,
+            "Fp-Request-Id": f"{the_timestamp}.n1fDrN",
+            "Accept-Encoding": "gzip, deflate, br, zstd",
+            "User-Agent": self.user_agent,
+            "Connection": "close",
+            "appsiteid": "0",
+        }
+
+        if self.x_requested_with:
+            the_headers["X-Requested-With"] = self.x_requested_with
+
+        if needs_auth:
+            the_headers["Authorization"] = f"Bearer {self.authorization_token}"
+        return the_headers
+
+    async def invoke_get(
+        self,
+        url: str,
+        headers: dict | None = None,
+        params: dict | None = None,
+        model: Type[MyExchangeApiResponse] | None = None,
+        parse_float=Decimal,
+    ) -> "MyExchangeApiResponse":
+        """
+        Invokes the specific request to the specific url with the specific params and headers.
+        """
+        response = await self.httpx_client.get(
+            url=url,
+            headers=headers,
+            params=params,
+        )
+        return model.deserialize(response.json(parse_float=parse_float))
+
+    async def invoke_post(
+        self,
+        url: str,
+        headers: dict | None = None,
+        params: dict | None = None,
+        content: dict | str | bytes = "",
+        model: Type[MyExchangeApiResponse] | None = None,
+        parse_float=Decimal,
+    ) -> "MyExchangeApiResponse":
+        """
+        Invokes the specific request to the specific url with the specific params and headers.
+        """
+
+        if isinstance(content, dict):
+            content = json.dumps(content, separators=(",", ":"), sort_keys=True)
+
+        response = await self.httpx_client.post(
+            url=url,
+            headers=headers,
+            params=params,
+            content=content,
+        )
+        if not model:
+            return response.json()
+
+        return model.deserialize(response.json(parse_float=parse_float))
+
+    async def aclose(self) -> None:
+        await self.httpx_client.aclose()
+        logger.info("MyExchangeClient closed")
+        return True
+
+    def read_from_session_file(self, file_path: str) -> None:
+        """
+        Reads from session file; if it doesn't exist, creates it.
+        """
+        # check if path exists
+        target_path = Path(file_path)
+        if not target_path.exists():
+            return self._save_session_file(file_path=file_path)
+
+        aes = AESCipher(key=f"bf_{self.account_name}_bf", fav_letter=self._fav_letter)
+        content = aes.decrypt(target_path.read_text()).decode("utf-8")
+        json_data: dict = json.loads(content)
+
+        self.authorization_token = json_data.get(
+            "authorization_token",
+            self.authorization_token,
+        )
+        self.timezone = json_data.get("timezone", self.timezone)
+        self.user_agent = json_data.get("user_agent", self.user_agent)
+
+    def _save_session_file(self, file_path: str) -> None:
+        """
+        Saves current information to the session file.
+        """
+
+        json_data = {
+            "authorization_token": self.authorization_token,
+            "timezone": self.timezone,
+            "user_agent": self.user_agent,
+        }
+        aes = AESCipher(key=f"bf_{self.account_name}_bf", fav_letter=self._fav_letter)
+        target_path = Path(file_path)
+        target_path.write_text(aes.encrypt(json.dumps(json_data)))
+
+    # endregion
+    ###########################################################
+
+```

trd_utils/exchanges/__init__.py

@@ -1,11 +1,21 @@
 
 from .exchange_base import ExchangeBase
+from .base_types import (
+    UnifiedTraderInfo,
+    UnifiedTraderPositions,
+    UnifiedPositionInfo,
+)
 from .blofin import BlofinClient
 from .bx_ultra import BXUltraClient
+from .hyperliquid import HyperLiquidClient
 
 
 __all__ = [
     ExchangeBase,
+    UnifiedTraderInfo,
+    UnifiedTraderPositions,
+    UnifiedPositionInfo,
     BXUltraClient,
     BlofinClient,
+    HyperLiquidClient,
 ]

trd_utils/exchanges/base_types.py

@@ -0,0 +1,53 @@
+
+
+from datetime import datetime
+from decimal import Decimal
+
+class UnifiedPositionInfo:
+    # The id of the position.
+    position_id: str = None
+
+    # The pnl (profit) of the position.
+    position_pnl: Decimal = None
+
+    # The position side, either "LONG" or "SHORT".
+    position_side: str = None
+
+    # The formatted pair string of this position.
+    # e.g. BTC/USDT.
+    position_pair: str = None
+
+    # Side but with a proper emoji alongside of it.
+    side_with_emoji: str = None
+
+    # The open time of this position.
+    # Note that not all public APIs might provide this field.
+    open_time: datetime = None
+
+    # The relative open time of this position.
+    relative_open_time: str = None
+
+    # Open price of the position.
+    open_price: Decimal = None
+
+    # The string (and formatted) version of the open_price.
+    # Optionally base unit also included (e.g. USDT or USD).
+    open_price_str: str = None
+
+
+class UnifiedTraderPositions:
+    positions: list[UnifiedPositionInfo] = None
+
+class UnifiedTraderInfo:
+    # Name of the trader
+    trader_name: str = None
+
+    # The URL in which we can see the trader's profile
+    trader_url: str = None
+
+    # Trader's id. Either int or str. In DEXes (such as HyperLiquid),
+    # this might be wallet address of the trader.
+    trader_id: int | str = None
+
+    # Trader's win-rate. Not all exchanges might support this field.
+    win_rate: Decimal = None

trd_utils/exchanges/blofin/blofin_client.py

@@ -8,6 +8,7 @@ import httpx
 import time
 from pathlib import Path
 
+from trd_utils.exchanges.base_types import UnifiedTraderInfo, UnifiedTraderPositions
 from trd_utils.exchanges.blofin.blofin_types import (
     BlofinApiResponse,
     CmsColorResponse,
@@ -108,7 +109,7 @@ class BlofinClient(ExchangeBase):
             content=payload,
             model=CopyTraderOrderListResponse,
         )
-    
+
     async def get_copy_trader_all_order_list(
         self,
         uid: int,
@@ -132,10 +133,13 @@ class BlofinClient(ExchangeBase):
                 from_param=current_id_from,
                 limit_param=chunk_limit,
             )
-            if not current_result or not isinstance(current_result, CopyTraderOrderListResponse) or \
-                not current_result.data:
+            if (
+                not current_result
+                or not isinstance(current_result, CopyTraderOrderListResponse)
+                or not current_result.data
+            ):
                 return result
-            
+
             if current_result.data[0].id == current_id_from:
                 if len(current_result.data) < 2:
                     return result
@@ -146,7 +150,7 @@ class BlofinClient(ExchangeBase):
                     "Expected first array to have the same value as from_param: "
                     f"current_id_from: {current_id_from}; but was: {current_result.data[0].id}"
                 )
-            
+
             current_id_from = current_result.data[-1].id
             result.data.extend(current_result.data)
             result.total_count += len(current_result.data)
@@ -157,7 +161,6 @@ class BlofinClient(ExchangeBase):
                 # we don't want to sleep after 1 request only
                 await asyncio.sleep(sleep_delay)
 
-
     async def get_copy_trader_order_history(
         self,
         uid: int,
@@ -200,10 +203,13 @@ class BlofinClient(ExchangeBase):
                 from_param=current_id_from,
                 limit_param=chunk_limit,
             )
-            if not current_result or not isinstance(current_result, CopyTraderOrderHistoryResponse) or \
-                not current_result.data:
+            if (
+                not current_result
+                or not isinstance(current_result, CopyTraderOrderHistoryResponse)
+                or not current_result.data
+            ):
                 return result
-            
+
             if current_result.data[0].id == current_id_from:
                 if len(current_result.data) < 2:
                     return result
@@ -214,7 +220,7 @@ class BlofinClient(ExchangeBase):
                     "Expected first array to have the same value as from_param: "
                     f"current_id_from: {current_id_from}; but was: {current_result.data[0].id}"
                 )
-            
+
             current_id_from = current_result.data[-1].id
             result.data.extend(current_result.data)
             result.total_count += len(current_result.data)
@@ -336,3 +342,18 @@ class BlofinClient(ExchangeBase):
 
     # endregion
     ###########################################################
+    # region unified methods
+    async def get_unified_trader_positions(
+        self,
+        uid: int | str,
+    ) -> UnifiedTraderPositions:
+        pass
+
+    async def get_unified_trader_info(
+        self,
+        uid: int | str,
+    ) -> UnifiedTraderInfo:
+        pass
+
+    # endregion
+    ###########################################################

trd_utils/exchanges/blofin/blofin_types.py

@@ -64,7 +64,7 @@ class CopyTraderInfoResult(BaseModel):
     joined_date: int = None
     max_draw_down: Decimal = None
     nick_name: str = None
-    order_amount_limit: None
+    order_amount_limit: Any = None
     profile: str = None
     profit_sharing_ratio: Decimal = None
     real_pnl: Decimal = None
@@ -89,7 +89,7 @@ class CopyTraderSingleOrderInfo(BaseModel):
     order_side: str = None
     avg_open_price: str = None
     quantity: str = None
-    quantity_cont: None
+    quantity_cont: Any = None
     open_time: int = None
     close_time: Any = None
     avg_close_price: Decimal = None
@@ -100,41 +100,41 @@ class CopyTraderSingleOrderInfo(BaseModel):
     followers: Any = None
     order_id: Any = None
     sharing: Any = None
-    order_state: None
-    trader_name: None
-    mark_price: None
-    tp_trigger_price: None
-    tp_order_type: None
-    sl_trigger_price: None
-    sl_order_type: None
+    order_state: Any = None
+    trader_name: Any = None
+    mark_price: Any = None
+    tp_trigger_price: Any = None
+    tp_order_type: Any = None
+    sl_trigger_price: Any = None
+    sl_order_type: Any = None
     margin_mode: str = None
-    time_in_force: None
+    time_in_force: Any = None
     position_side: str = None
-    order_category: None
-    price: None
-    fill_quantity: None
-    fill_quantity_cont: None
-    pnl: None
-    cancel_source: None
-    order_type: None
-    order_open_state: None
-    amount: None
-    filled_amount: None
-    create_time: None
-    update_time: None
-    open_fee: None
-    close_fee: None
-    id_md5: None
-    tp_sl: None
-    trader_uid: None
-    available_quantity: None
-    available_quantity_cont: None
-    show_in_kline: None
-    unrealized_pnl: None
-    unrealized_pnl_ratio: None
-    broker_id: None
-    position_change_history: None
-    user_id: None
+    order_category: Any = None
+    price: Any = None
+    fill_quantity: Any = None
+    fill_quantity_cont: Any = None
+    pnl: Any = None
+    cancel_source: Any = None
+    order_type: Any = None
+    order_open_state: Any = None
+    amount: Any = None
+    filled_amount: Any = None
+    create_time: Any = None
+    update_time: Any = None
+    open_fee: Any = None
+    close_fee: Any = None
+    id_md5: Any = None
+    tp_sl: Any = None
+    trader_uid: Any = None
+    available_quantity: Any = None
+    available_quantity_cont: Any = None
+    show_in_kline: Any = None
+    unrealized_pnl: Any = None
+    unrealized_pnl_ratio: Any = None
+    broker_id: Any = None
+    position_change_history: Any = None
+    user_id: Any = None
 
 class CopyTraderOrderListResponse(BlofinApiResponse):
     data: list[CopyTraderSingleOrderInfo] = None