trd-utils 0.0.57__py3-none-any.whl

trd_utils/__init__.py

@@ -0,0 +1,3 @@
+
+__version__ = "0.0.57"
+

trd_utils/cipher/__init__.py

@@ -0,0 +1,44 @@
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import padding
+from base64 import b64encode, b64decode
+from os import urandom
+
+
+class AESCipher:
+    def __init__(self, key: str, fav_letter: str):
+        if len(key) > 32:
+            raise ValueError("Key length must be 32 bytes or less")
+        elif len(key) < 32:
+            key = key.ljust(len(key) + (32 - len(key) % 32), fav_letter)
+
+        key = key.encode('utf-8')
+        if len(key) != 32:
+            raise ValueError("Key length must be 32 bytes")
+        
+        self.key = key
+        self.backend = default_backend()
+
+    def encrypt(self, plaintext):
+        if isinstance(plaintext, str):
+            plaintext = plaintext.encode('utf-8')
+        
+        iv = urandom(16)
+        cipher = Cipher(algorithms.AES(self.key), modes.CBC(iv), backend=self.backend)
+        padder = padding.PKCS7(128).padder()
+        padded_data = padder.update(plaintext) + padder.finalize()
+        encryptor = cipher.encryptor()
+        ciphertext = encryptor.update(padded_data) + encryptor.finalize()
+        return b64encode(iv + ciphertext).decode('utf-8')
+
+    def decrypt(self, b64_encrypted_data):
+        encrypted_data = b64decode(b64_encrypted_data)
+        iv = encrypted_data[:16]
+        ciphertext = encrypted_data[16:]
+        cipher = Cipher(algorithms.AES(self.key), modes.CBC(iv), backend=self.backend)
+        unpadder = padding.PKCS7(128).unpadder()
+        decryptor = cipher.decryptor()
+        padded_plaintext = decryptor.update(ciphertext) + decryptor.finalize()
+        plaintext = unpadder.update(padded_plaintext) + unpadder.finalize()
+        return plaintext

trd_utils/common_utils/float_utils.py

@@ -0,0 +1,21 @@
+
+from decimal import Decimal
+
+
+default_quantize = Decimal("1.00")
+
+def dec_to_str(dec_value: Decimal) -> str:
+    return format(dec_value.quantize(default_quantize), "f")
+
+def dec_to_normalize(dec_value: Decimal) -> str:
+    return format(dec_value.normalize(), "f")
+
+def as_decimal(value) -> Decimal:
+    if value is None:
+        return None
+    
+    if isinstance(value, Decimal):
+        # prevent extra allocation
+        return value
+    
+    return Decimal(value)

trd_utils/common_utils/wallet_utils.py

@@ -0,0 +1,26 @@
+"""
+General usage wallet-related utils code.
+"""
+
+
+def shorten_wallet_address(
+    address: str,
+    start_chars: int = 7,
+    end_chars: int = 6,
+):
+    """
+    Shortens an Ethereum address by keeping a specific number of characters
+    from the beginning and end, separated by '...'.
+
+    Args:
+        address (str): The Ethereum address to shorten
+        start_chars (int): Number of characters to keep from the beginning (default: 7)
+        end_chars (int): Number of characters to keep from the end (default: 6)
+
+    Returns:
+        str: The shortened address
+    """
+    if not address or len(address) <= start_chars + end_chars:
+        return address
+
+    return f"{address[:start_chars]}...{address[-end_chars:]}"

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,25 @@
+
+
+
+
+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)
+
+def dt_to_ts(dt: datetime, default: int = 0) -> int:
+    """
+    Return dt in ms as a timestamp in UTC.
+    If dt is None, return the given default.
+    """
+    if dt:
+        return int(dt.timestamp() * 1000)
+    return default

trd_utils/exchanges/README.md

@@ -0,0 +1,203 @@
+# 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",
+        use_http1: bool = False,
+        use_http2: bool = True,
+    ):
+        self.httpx_client = httpx.AsyncClient(
+            verify=http_verify,
+            http1=use_http1,
+            http2=use_http2,
+        )
+        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

@@ -0,0 +1,28 @@
+from .exchange_base import ExchangeBase
+from .base_types import (
+    UnifiedTraderInfo,
+    UnifiedTraderPositions,
+    UnifiedPositionInfo,
+    UnifiedFuturesMarketInfo,
+    UnifiedSingleFutureMarketInfo,
+)
+from .binance import BinanceClient
+from .blofin import BlofinClient
+from .bx_ultra import BXUltraClient
+from .hyperliquid import HyperLiquidClient
+from .okx import OkxClient
+
+
+__all__ = [
+    "ExchangeBase",
+    "BXUltraClient",
+    "BinanceClient",
+    "BlofinClient",
+    "HyperLiquidClient",
+    "OkxClient",
+    "UnifiedTraderInfo",
+    "UnifiedTraderPositions",
+    "UnifiedPositionInfo",
+    "UnifiedFuturesMarketInfo",
+    "UnifiedSingleFutureMarketInfo",
+]

trd_utils/exchanges/base_types.py

@@ -0,0 +1,229 @@
+from datetime import datetime
+from decimal import Decimal
+import statistics
+
+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
+
+    # The total position size.
+    position_size: Decimal | None = None
+
+    # The initial amount of open_price_unit that the trader has put to open
+    # this position.
+    # Note that not all public APIs might provide this field.
+    initial_margin: Decimal | None = None
+
+    # The last price of this pair on the target exchange.
+    # not all exchanges support this yet, so use it with caution.
+    last_price: Decimal | None = None
+
+    # The last volume of this pair being traded on the target exchange.
+    # not all exchanges support this yet, so use it with caution.
+    last_volume: Decimal | None = None
+
+    def recalculate_pnl(self) -> tuple[Decimal, Decimal]:
+        """
+        Recalculates the PnL based on the available data.
+        This requires `last_price`, `open_price`, `initial_margin`,
+        and `position_leverage` to be set.
+
+        Returns:
+            The recalculated (PnL, percentage) as a Decimal, or None if calculation
+            is not possible with the current data.
+        """
+        if not self.position_leverage:
+            self.position_leverage = 1
+
+        if not all([self.last_price, self.open_price, self.initial_margin]):
+            # Not enough data to calculate PnL.
+            return None
+
+        price_change_percentage = (self.last_price - self.open_price) / self.open_price
+        if self.position_side == "SHORT":
+            # For a short position, profit is made when the price goes down.
+            price_change_percentage *= -1
+
+        pnl_percentage = self.position_leverage * price_change_percentage
+        # PnL = Initial Margin * Leverage * Price Change %
+        pnl = self.initial_margin * pnl_percentage
+        self.position_pnl = pnl
+        return (pnl, pnl_percentage)
+
+    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 get_win_rate_str(self) -> str:
+        return str(round(self.win_rate, 2)) if self.win_rate is not None else "N/A"
+
+    def __str__(self):
+        return (
+            f"{self.trader_name} ({self.trader_id})"
+            f" | Win Rate: {self.get_win_rate_str()}"
+            f" | Profile: {self.trader_url}"
+        )
+
+    def __repr__(self):
+        return self.__str__()
+
+class UnifiedMarketStatistics(BaseModel):
+    mean_change_24h: Decimal = None
+    stdev_change_24h: Decimal = None
+    median_volume_24h: Decimal = None
+
+class UnifiedSingleFutureMarketInfo(BaseModel):
+    name: str = None
+    pair: str = None
+    price: Decimal = None
+    previous_day_price: Decimal = None
+    absolute_change_24h: Decimal = None
+    percentage_change_24h: Decimal = None
+    funding_rate: Decimal = None
+    daily_volume: Decimal = None
+    open_interest: Decimal = None
+
+    def __str__(self):
+        return (
+            f"{self.name} | Price: {round(self.price, 4)} "
+            f"| 24h Change: {round(self.percentage_change_24h, 4)}% "
+            f"| 24h Volume: {round(self.daily_volume, 4)} "
+            f"| Funding Rate: {round(self.funding_rate, 6)}% "
+            f"| Preferred Side: {self.get_preferred_position_side()}"
+        )
+    
+    def __repr__(self):
+        return self.__str__()
+    
+    def get_preferred_position_side(self) -> str:
+        return "LONG" if self.funding_rate <= 0 else "SHORT"
+    
+    def get_z_score_24h(self, market_stats: UnifiedMarketStatistics) -> Decimal | None:
+        if not market_stats.stdev_change_24h:
+            return None
+        
+        z_score = (
+            self.percentage_change_24h - market_stats.mean_change_24h
+        ) / market_stats.stdev_change_24h
+        return z_score
+
+class UnifiedFuturesMarketInfo(BaseModel):
+    sorted_markets: list[UnifiedSingleFutureMarketInfo] = None
+
+    def __str__(self):
+        return f"Total Markets: {len(self.sorted_markets) if self.sorted_markets else 0}"
+    
+    def __repr__(self):
+        return self.__str__()
+    
+    def find_market_by_name(
+        self,
+        name: str,
+    ) -> UnifiedSingleFutureMarketInfo | None:
+        if not self.sorted_markets:
+            return None
+        
+        for market in self.sorted_markets:
+            if market.name.lower() == name.lower():
+                return market
+        
+        return None
+
+    def get_statistics(self) -> UnifiedMarketStatistics:
+        changes_24h = [m.percentage_change_24h for m in self.sorted_markets]
+        volumes_24h = [m.daily_volume for m in self.sorted_markets]
+
+        s_obj = UnifiedMarketStatistics()
+        s_obj.mean_change_24h = statistics.mean(changes_24h)
+        s_obj.stdev_change_24h = statistics.stdev(changes_24h)
+        s_obj.median_volume_24h = statistics.median(volumes_24h) 
+
+        return s_obj

trd_utils/exchanges/binance/__init__.py

@@ -0,0 +1,13 @@
+
+from .binance_client import BinanceClient
+from .binance_types import (
+    BinanceLeaderboardPosition,
+    BinanceTicker24h,
+)
+
+__all__ = [
+    "BinanceClient",
+    "BinanceLeaderboardPosition",
+    "BinanceTicker24h",
+]
+