trd-utils 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

trd_utils/__init__.py

@@ -1,3 +1,3 @@
 
-__version__ = "0.0.14"
+__version__ = "0.0.16"
 

trd_utils/date_utils/__init__.py

@@ -0,0 +1,8 @@
+
+from .datetime_helpers import dt_from_ts
+
+
+__all__ = [
+    "dt_from_ts",
+]
+

trd_utils/date_utils/datetime_helpers.py

@@ -0,0 +1,16 @@
+
+
+
+
+from datetime import datetime, timezone
+
+
+def dt_from_ts(timestamp: float) -> datetime:
+    """
+    Return a datetime from a timestamp.
+    :param timestamp: timestamp in seconds or milliseconds
+    """
+    if timestamp > 1e10:
+        # Timezone in ms - convert to seconds
+        timestamp /= 1000
+    return datetime.fromtimestamp(timestamp, tz=timezone.utc)

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,
-    BXUltraClient,
-    BlofinClient,
+    "ExchangeBase",
+    "UnifiedTraderInfo",
+    "UnifiedTraderPositions",
+    "UnifiedPositionInfo",
+    "BXUltraClient",
+    "BlofinClient",
+    "HyperLiquidClient",
 ]

trd_utils/exchanges/base_types.py

@@ -0,0 +1,106 @@
+
+
+from datetime import datetime
+from decimal import Decimal
+
+from trd_utils.types_helper.base_model import BaseModel
+
+class UnifiedPositionInfo(BaseModel):
+    # 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 position's leverage.
+    position_leverage: Decimal = None
+
+    # The margin mode; e.g. cross or isolated. Please note that
+    # different exchanges might provide different kinds of margin modes,
+    # depending on what they support, that's why we can't support a unified
+    # enum type for this as of yet.
+    margin_mode: str = None
+
+    # The formatted pair string of this position.
+    # e.g. BTC/USDT.
+    position_pair: str = None
+
+    # The open time of this position.
+    # Note that not all public APIs might provide this field.
+    open_time: datetime = None
+
+    # Open price of the position.
+    open_price: Decimal = None
+
+    # The base unit that the open-price is based on (e.g. USD, USDT, USDC)
+    open_price_unit: str | None = None
+
+    def __str__(self):
+        parts = []
+        
+        # Add position pair and ID
+        parts.append(f"Position: {self.position_pair or 'Unknown'} (ID: {self.position_id or 'N/A'})")
+        
+        # Add side and leverage
+        side_str = f"Side: {self.position_side or 'Unknown'}"
+        if self.position_leverage is not None:
+            side_str += f", {self.position_leverage}x"
+        parts.append(side_str)
+        
+        # Add margin mode if available
+        if self.margin_mode:
+            parts.append(f"Margin: {self.margin_mode}")
+        
+        # Add open price if available
+        price_str = "Open price: "
+        if self.open_price is not None:
+            price_str += f"{self.open_price}"
+            if self.open_price_unit:
+                price_str += f" {self.open_price_unit}"
+        else:
+            price_str += "N/A"
+        parts.append(price_str)
+        
+        # Add open time if available
+        if self.open_time:
+            parts.append(f"Opened: {self.open_time.strftime('%Y-%m-%d %H:%M:%S')}")
+        
+        # Add PNL if available
+        if self.position_pnl is not None:
+            parts.append(f"PNL: {self.position_pnl}")
+        
+        return " | ".join(parts)
+
+    def __repr__(self):
+        return self.__str__()
+
+class UnifiedTraderPositions(BaseModel):
+    positions: list[UnifiedPositionInfo] = None
+
+class UnifiedTraderInfo(BaseModel):
+    # 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
+
+    # 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 win-rate. Not all exchanges might support this field.
+    win_rate: Decimal = None
+
+    def __str__(self):
+        return (
+            f"Trader: {self.trader_name} (ID: {self.trader_id})"
+            f"{' | Win Rate: ' + str(round(self.win_rate, 2))}"
+            f"{' | Profile: ' + self.trader_url}"
+        )
+    
+    def __repr__(self):
+        return self.__str__()
+    

trd_utils/exchanges/blofin/__init__.py

@@ -2,5 +2,5 @@
 from .blofin_client import BlofinClient
 
 __all__ = [
-    BlofinClient,
+    "BlofinClient",
 ]

trd_utils/exchanges/blofin/blofin_client.py

@@ -2,14 +2,18 @@ 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.date_utils.datetime_helpers import dt_from_ts
+from trd_utils.exchanges.base_types import (
+    UnifiedPositionInfo,
+    UnifiedTraderInfo,
+    UnifiedTraderPositions,
+)
 from trd_utils.exchanges.blofin.blofin_types import (
-    BlofinApiResponse,
     CmsColorResponse,
     CopyTraderAllOrderHistory,
     CopyTraderAllOrderList,
@@ -21,6 +25,9 @@ from trd_utils.exchanges.blofin.blofin_types import (
 from trd_utils.cipher import AESCipher
 from trd_utils.exchanges.exchange_base import ExchangeBase
 
+
+BASE_PROFILE_URL = "https://blofin.com/copy-trade/details/"
+
 logger = logging.getLogger(__name__)
 
 
@@ -64,7 +71,7 @@ class BlofinClient(ExchangeBase):
         return await self.invoke_get(
             f"{self.blofin_api_base_url}/cms/share_config",
             headers=headers,
-            model=ShareConfigResponse,
+            model_type=ShareConfigResponse,
         )
 
     async def get_cms_color(self) -> CmsColorResponse:
@@ -72,7 +79,7 @@ class BlofinClient(ExchangeBase):
         return await self.invoke_get(
             f"{self.blofin_api_base_url}/cms/color",
             headers=headers,
-            model=CmsColorResponse,
+            model_type=CmsColorResponse,
         )
 
     # endregion
@@ -87,28 +94,28 @@ class BlofinClient(ExchangeBase):
             f"{self.blofin_api_base_url}/copy/trader/info",
             headers=headers,
             content=payload,
-            model=CopyTraderInfoResponse,
+            model_type=CopyTraderInfoResponse,
         )
 
     async def get_copy_trader_order_list(
         self,
-        uid: int,
+        uid: int | str,
         from_param: int = 0,
         limit_param: int = 20,
     ) -> CopyTraderOrderListResponse:
         payload = {
             "from": from_param,
             "limit": limit_param,
-            "uid": uid,
+            "uid": int(uid),
         }
         headers = self.get_headers()
         return await self.invoke_post(
             f"{self.blofin_api_base_url}/copy/trader/order/list",
             headers=headers,
             content=payload,
-            model=CopyTraderOrderListResponse,
+            model_type=CopyTraderOrderListResponse,
         )
-    
+
     async def get_copy_trader_all_order_list(
         self,
         uid: int,
@@ -132,10 +139,15 @@ 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 isinstance(current_result, CopyTraderOrderListResponse):
+                raise ValueError(
+                    "get_copy_trader_order_list returned invalid value of "
+                    f"{type(current_result)}",
+                )
+            if not current_result.data:
+                # we no longer have anything else here
                 return result
-            
+
             if current_result.data[0].id == current_id_from:
                 if len(current_result.data) < 2:
                     return result
@@ -146,7 +158,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 +169,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,
@@ -174,7 +185,7 @@ class BlofinClient(ExchangeBase):
             f"{self.blofin_api_base_url}/copy/trader/order/history",
             headers=headers,
             content=payload,
-            model=CopyTraderOrderHistoryResponse,
+            model_type=CopyTraderOrderHistoryResponse,
         )
 
     async def get_copy_trader_all_order_history(
@@ -200,10 +211,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 +228,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)
@@ -250,56 +264,6 @@ class BlofinClient(ExchangeBase):
             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[BlofinApiResponse] | None = None,
-        parse_float=Decimal,
-    ) -> "BlofinApiResponse":
-        """
-        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[BlofinApiResponse] | None = None,
-        parse_float=Decimal,
-    ) -> "BlofinApiResponse":
-        """
-        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("BlofinClient closed")
-        return True
-
     def read_from_session_file(self, file_path: str) -> None:
         """
         Reads from session file; if it doesn't exist, creates it.
@@ -336,3 +300,48 @@ class BlofinClient(ExchangeBase):
 
     # endregion
     ###########################################################
+    # region unified methods
+    async def get_unified_trader_positions(
+        self,
+        uid: int | str,
+    ) -> UnifiedTraderPositions:
+        result = await self.get_copy_trader_all_order_list(
+            uid=uid,
+        )
+        unified_result = UnifiedTraderPositions()
+        unified_result.positions = []
+        for position in result.data:
+            unified_pos = UnifiedPositionInfo()
+            unified_pos.position_id = position.id or position.order_id
+            unified_pos.position_pnl = position.real_pnl or position.pnl
+            unified_pos.position_side = (
+                "LONG" if position.order_side in ("LONG", "BUY") else "SHORT"
+            )
+            unified_pos.margin_mode = position.margin_mode
+            unified_pos.position_leverage = Decimal(position.leverage)
+            unified_pos.position_pair = position.symbol.replace("-", "/")
+            unified_pos.open_time = dt_from_ts(position.open_time)
+            unified_pos.open_price = position.avg_open_price
+            unified_pos.open_price_unit = position.symbol.split("-")[-1]
+            unified_result.positions.append(unified_pos)
+
+        return unified_result
+
+    async def get_unified_trader_info(
+        self,
+        uid: int | str,
+    ) -> UnifiedTraderInfo:
+        info_resp = await self.get_copy_trader_info(
+            uid=uid,
+        )
+        info = info_resp.data
+        unified_info = UnifiedTraderInfo()
+        unified_info.trader_id = info.uid
+        unified_info.trader_name = info.nick_name
+        unified_info.trader_url = f"{BASE_PROFILE_URL}{info.uid}"
+        unified_info.win_rate = info.win_rate
+
+        return unified_info
+
+    # endregion
+    ###########################################################