unicex 0.13.17__py3-none-any.whl → 0.16.5__py3-none-any.whl

unicex/kucoin/adapter.py

@@ -0,0 +1,181 @@
+__all__ = ["Adapter"]
+
+from typing import Any
+
+from unicex.types import (
+    KlineDict,
+    OpenInterestDict,
+    OpenInterestItem,
+    TickerDailyDict,
+    TickerDailyItem,
+)
+from unicex.utils import catch_adapter_errors, decorate_all_methods
+
+from .exchange_info import ExchangeInfo
+
+
+@decorate_all_methods(catch_adapter_errors)
+class Adapter:
+    """Адаптер для унификации данных с Kucoin API."""
+
+    @staticmethod
+    def tickers(raw_data: dict, only_usdt: bool) -> list[str]:
+        """Преобразует сырой ответ, в котором содержатся данные о тикерах в список тикеров.
+
+        Параметры:
+            raw_data (dict): Сырой ответ с биржи.
+            only_usdt (bool): Флаг, указывающий, нужно ли включать только тикеры в паре к USDT.
+
+        Возвращает:
+            list[str]: Список тикеров.
+        """
+        return [
+            item["symbol"]
+            for item in raw_data["data"]["list"]
+            if item["symbol"].endswith("USDT") or not only_usdt
+        ]
+
+    @staticmethod
+    def futures_tickers(raw_data: dict, only_usdt: bool) -> list[str]:
+        """Преобразует сырой ответ, в котором содержатся данные о тикерах в список тикеров.
+
+        Параметры:
+            raw_data (dict): Сырой ответ с биржи.
+            only_usdt (bool): Флаг, указывающий, нужно ли включать только тикеры в паре к USDT.
+
+        Возвращает:
+            list[str]: Список тикеров.
+        """
+        return [
+            item["symbol"]
+            for item in raw_data["data"]["list"]
+            if item["symbol"].endswith("USDTM") or not only_usdt
+        ]
+
+    @staticmethod
+    def ticker_24hr(raw_data: dict) -> TickerDailyDict:
+        """Преобразует сырой ответ, в котором содержатся данные о тикере за последние 24 часа в унифицированный формат.
+
+        Параметры:
+            raw_data (dict): Сырой ответ с биржи.
+
+        Возвращает:
+            TickerDailyDict: Словарь, где ключ - тикер, а значение - статистика за последние 24 часа.
+        """
+
+        def safe_float(value: object, default: float = 0.0) -> float:
+            try:
+                if value is None:
+                    return default
+                return float(value)  # type: ignore
+            except (TypeError, ValueError):
+                return default
+
+        result: dict[str, TickerDailyItem] = {}
+
+        for item in raw_data["data"]["list"]:
+            symbol = item.get("symbol")
+            if not symbol:
+                continue
+
+            last_price = safe_float(item.get("lastPrice"))
+            open_price = safe_float(item.get("open"))
+            base_volume = safe_float(item.get("baseVolume"))
+            quote_volume = safe_float(item.get("quoteVolume"))
+
+            if open_price > 0:
+                p = round((last_price / open_price - 1) * 100, 2)
+            else:
+                p = 0.0
+
+            result[symbol] = TickerDailyItem(
+                p=p,
+                v=base_volume,
+                q=quote_volume,
+            )
+
+        return result
+
+    @staticmethod
+    def last_price(raw_data: dict) -> dict[str, float]:
+        """Преобразует сырой ответ, в котором содержатся данные о последней цене, в унифицированный формат.
+
+        Параметры:
+            raw_data (dict): Сырой ответ с биржи.
+
+        Возвращает:
+            dict[str, float]: Словарь, где ключ - тикер, а значение - последняя цена.
+        """
+        return {
+            item["symbol"]: float(item["lastPrice"])
+            for item in raw_data["data"]["list"]
+            if item["lastPrice"]
+        }
+
+    @staticmethod
+    def open_interest(raw_data: dict[str, Any]) -> OpenInterestDict:
+        """Преобразует сырой ответ, в котором содержатся данные об открытом интересе, в унифицированный формат.
+
+        Параметры:
+            raw_data (dict): Сырой ответ с биржи.
+
+        Возвращает:
+            OpenInterestDict: Словарь, где ключ - тикер, а значение - агрегированные данные открытого интереса.
+        """
+        return {
+            item["symbol"]: OpenInterestItem(
+                t=item["ts"],
+                v=float(item["openInterest"]) * Adapter._get_contract_size(item["symbol"]),
+                u="coins",
+            )
+            for item in raw_data["data"]
+        }
+
+    @staticmethod
+    def funding_rate(raw_data: dict) -> float:
+        """Преобразует историю ставок финансирования в унифицированный формат.
+
+        Параметры:
+            raw_data (dict): Сырой ответ с биржи.
+
+        Возвращает:
+            float: Актуальная ставка финансирования.
+        """
+        return round(raw_data["data"]["nextFundingRate"] * 100, 6)
+
+    @staticmethod
+    def _get_contract_size(symbol: str) -> float:
+        """Возвращает размер контракта для указанного символа тикера."""
+        try:
+            return ExchangeInfo.get_futures_ticker_info(symbol)["contract_size"] or 1
+        except:  # noqa
+            return 1
+
+    @staticmethod
+    def klines(raw_data: dict, symbol: str) -> list[KlineDict]:
+        """Преобразует данные о свечах в унифицированный формат.
+
+        Параметры:
+            raw_data (dict): Сырой ответ с биржи.
+            symbol (str): Символ тикера.
+
+        Возвращает:
+            list[KlineDict]: Список свечей.
+        """
+        klines: list[KlineDict] = []
+        for item in sorted(raw_data["data"]["list"], key=lambda x: int(float(x[0]))):
+            klines.append(  # noqa: PERF401
+                KlineDict(
+                    s=symbol,
+                    t=item[0],
+                    o=float(item[1]),
+                    h=float(item[3]),
+                    l=float(item[4]),
+                    c=float(item[2]),
+                    v=float(item[5]),
+                    q=float(item[6]),
+                    T=None,
+                    x=None,
+                )
+            )
+        return klines

unicex/kucoin/client.py

@@ -0,0 +1,135 @@
+__all__ = ["Client"]
+
+
+from typing import Any, Literal
+
+from unicex._base import BaseClient
+from unicex.types import RequestMethod
+from unicex.utils import filter_params
+
+
+class Client(BaseClient):
+    """Клиент для работы с Kucoin API."""
+
+    _BASE_URL: str = "https://api.kucoin.com"
+    """Базовый URL для запросов."""
+
+    async def _make_request(
+        self,
+        method: RequestMethod,
+        endpoint: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Выполняет HTTP-запрос к эндпоинтам Kucoin API.
+
+        Параметры:
+            method (str): HTTP метод запроса ("GET", "POST", "DELETE" и т.д.).
+            endpoint (str): URL эндпоинта Kucoin API.
+            params (dict | None): Параметры запроса.
+
+        Возвращает:
+            dict: Ответ в формате JSON.
+        """
+        # Составляем URL для запроса
+        url = self._BASE_URL + endpoint
+
+        # Фильтруем параметры от None значений
+        params = filter_params(params) if params else {}
+
+        # Выполняем запрос
+        return await super()._make_request(
+            method=method,
+            url=url,
+            params=params,
+        )
+
+    async def symbol(
+        self,
+        trade_type: Literal["SPOT", "FUTURES", "ISOLATED", "CROSS"],
+        symbol: str | None = None,
+    ) -> dict[str, Any]:
+        """Получение символов и информации о них.
+
+        https://www.kucoin.com/docs-new/rest/ua/get-symbol
+        """
+        params = {"tradeType": trade_type, "symbol": symbol}
+
+        return await self._make_request("GET", "/api/ua/v1/market/instrument", params=params)
+
+    async def ticker(
+        self,
+        trade_type: Literal["SPOT", "FUTURES"],
+        symbol: str | None = None,
+    ) -> dict[str, Any]:
+        """Получение тикеров и информации о них.
+
+        https://www.kucoin.com/docs-new/rest/ua/get-ticker
+        """
+        params = {"tradeType": trade_type, "symbol": symbol}
+
+        return await self._make_request("GET", "/api/ua/v1/market/ticker", params=params)
+
+    async def open_interest(self) -> dict[str, Any]:
+        """Получение открытого интереса.
+
+        https://www.kucoin.com/docs-new/3476287e0
+        """
+        return await self._make_request("GET", "/api/ua/v1/market/open-interest")
+
+    async def kline(
+        self,
+        trade_type: Literal["SPOT", "FUTURES"],
+        symbol: str,
+        interval: str,
+        start_at: int | None = None,
+        end_at: int | None = None,
+    ) -> dict[str, Any]:
+        """Получение списка свечей.
+
+        https://www.kucoin.com/docs-new/rest/ua/get-klines
+        """
+        params = {
+            "tradeType": trade_type,
+            "symbol": symbol,
+            "interval": interval,
+            "startAt": start_at,
+            "endAt": end_at,
+        }
+
+        return await self._make_request("GET", "/api/ua/v1/market/kline", params=params)
+
+    async def funding_rate_history(
+        self,
+        symbol: str,
+        start_at: int,
+        end_at: int,
+    ) -> dict[str, Any]:
+        """Получение истории ставок финансирования.
+
+        https://www.kucoin.com/docs-new/rest/ua/get-history-funding-rate
+        """
+        params = {
+            "symbol": symbol,
+            "startAt": start_at,
+            "endAt": end_at,
+        }
+
+        return await self._make_request(
+            "GET",
+            "/api/ua/v1/market/funding-rate-history",
+            params=params,
+        )
+
+    async def funding_rate(self, symbol: str) -> dict[str, Any]:
+        """Получение текущей ставки финансирования.
+
+        https://www.kucoin.com/docs-new/rest/ua/get-current-funding-rate
+        """
+        params = {"symbol": symbol}
+
+        return await self._make_request(
+            "GET",
+            "/api/ua/v1/market/funding-rate",
+            params=params,
+        )

unicex/kucoin/exchange_info.py

@@ -0,0 +1,50 @@
+__all__ = ["ExchangeInfo"]
+
+import aiohttp
+
+from unicex._abc import IExchangeInfo
+from unicex.types import TickerInfoItem
+
+from .client import Client
+
+
+class ExchangeInfo(IExchangeInfo):
+    """Предзагружает информацию о тикерах для биржи Kucoin."""
+
+    exchange_name = "Kucoin"
+    """Название биржи, на которой работает класс."""
+
+    @classmethod
+    async def _load_spot_exchange_info(cls, session: aiohttp.ClientSession) -> None:
+        """Загружает информацию о бирже для спотового рынка."""
+        tickers_info = {}
+        exchange_info = await Client(session).symbol("SPOT")
+        for el in exchange_info["data"]["list"]:
+            tickers_info[el["symbol"]] = TickerInfoItem(
+                tick_precision=None,
+                tick_step=float(el["tickSize"]),
+                size_precision=None,
+                size_step=float(el["baseOrderStep"]),
+                contract_size=1,
+            )
+
+        cls._tickers_info = tickers_info
+
+    @classmethod
+    async def _load_futures_exchange_info(cls, session: aiohttp.ClientSession) -> None:
+        """Загружает информацию о бирже для фьючерсного рынка."""
+        tickers_info = {}
+        exchange_info = await Client(session).symbol("FUTURES")
+        for el in exchange_info["data"]["list"]:
+            try:
+                tickers_info[el["symbol"]] = TickerInfoItem(
+                    tick_precision=None,
+                    tick_step=float(el["tickSize"]),
+                    size_precision=None,
+                    size_step=float(el["lotSize"]),
+                    contract_size=float(el["unitSize"]),
+                )
+            except Exception as e:
+                cls._logger.error(f"Error loading ticker info for {el}: {e}")
+
+        cls._futures_tickers_info = tickers_info

unicex/kucoin/uni_client.py

@@ -0,0 +1,208 @@
+__all__ = ["UniClient"]
+
+
+from typing import overload
+
+from unicex._abc import IUniClient
+from unicex.enums import Exchange, Timeframe
+from unicex.types import KlineDict, OpenInterestDict, OpenInterestItem, TickerDailyDict
+
+from .adapter import Adapter
+from .client import Client
+
+
+class UniClient(IUniClient[Client]):
+    """Унифицированный клиент для работы с Kucoin API."""
+
+    @property
+    def _client_cls(self) -> type[Client]:
+        """Возвращает класс клиента для Kucoin.
+
+        Возвращает:
+            type[Client]: Класс клиента для Kucoin.
+        """
+        return Client
+
+    async def tickers(self, only_usdt: bool = True) -> list[str]:
+        """Возвращает список тикеров.
+
+        Параметры:
+            only_usdt (bool): Если True, возвращает только тикеры в паре к USDT.
+
+        Возвращает:
+            list[str]: Список тикеров.
+        """
+        raw_data = await self._client.ticker("SPOT")
+        return Adapter.tickers(raw_data, only_usdt)
+
+    async def futures_tickers(self, only_usdt: bool = True) -> list[str]:
+        """Возвращает список тикеров.
+
+        Параметры:
+            only_usdt (bool): Если True, возвращает только тикеры в паре к USDT.
+
+        Возвращает:
+            list[str]: Список тикеров.
+        """
+        raw_data = await self._client.ticker("FUTURES")
+        return Adapter.futures_tickers(raw_data, only_usdt)
+
+    async def last_price(self) -> dict[str, float]:
+        """Возвращает последнюю цену для каждого тикера.
+
+        Возвращает:
+            dict[str, float]: Словарь с последними ценами для каждого тикера.
+        """
+        raw_data = await self._client.ticker("SPOT")
+        return Adapter.last_price(raw_data)
+
+    async def futures_last_price(self) -> dict[str, float]:
+        """Возвращает последнюю цену для каждого тикера.
+
+        Возвращает:
+            dict[str, float]: Словарь с последними ценами для каждого тикера.
+        """
+        raw_data = await self._client.ticker("FUTURES")
+        return Adapter.last_price(raw_data)
+
+    async def ticker_24hr(self) -> TickerDailyDict:
+        """Возвращает статистику за последние 24 часа для каждого тикера.
+
+        Возвращает:
+            TickerDailyDict: Словарь с статистикой за последние 24 часа для каждого тикера.
+        """
+        raw_data = await self._client.ticker("SPOT")
+        return Adapter.ticker_24hr(raw_data)
+
+    async def futures_ticker_24hr(self) -> TickerDailyDict:
+        """Возвращает статистику за последние 24 часа для каждого тикера.
+
+        Возвращает:
+            TickerDailyDict: Словарь с статистикой за последние 24 часа для каждого тикера.
+        """
+        raw_data = await self._client.ticker("FUTURES")
+        return Adapter.ticker_24hr(raw_data)
+
+    async def klines(
+        self,
+        symbol: str,
+        interval: Timeframe | str,
+        limit: int | None = None,
+        start_time: int | None = None,
+        end_time: int | None = None,
+    ) -> list[KlineDict]:
+        """Возвращает список свечей для тикера.
+
+        Параметры:
+            symbol (str): Название тикера.
+            limit (int | None): Количество свечей.
+            interval (Timeframe | str): Таймфрейм свечей.
+            start_time (int | None): Время начала периода в миллисекундах.
+            end_time (int | None): Время окончания периода в миллисекундах.
+
+        Возвращает:
+            list[KlineDict]: Список свечей для тикера.
+        """
+        if not limit and not all([start_time, end_time]):
+            raise ValueError("limit or (start_time and end_time) must be provided")
+
+        if limit:  # Перезаписываем start_time и end_time если указан limit, т.к. по умолчанию HyperLiquid не принимают этот параметр
+            if not isinstance(interval, Timeframe):
+                raise ValueError("interval must be a Timeframe if limit param provided")
+            start_time, end_time = self.limit_to_start_and_end_time(
+                interval, limit, use_milliseconds=False
+            )
+        interval = (
+            interval.to_exchange_format(Exchange.KUCOIN)
+            if isinstance(interval, Timeframe)
+            else interval
+        )
+        raw_data = await self._client.kline(
+            trade_type="SPOT",
+            symbol=symbol,
+            interval=interval,
+            start_at=self.to_seconds(start_time),
+            end_at=self.to_seconds(end_time),
+        )
+        return Adapter.klines(raw_data=raw_data, symbol=symbol)
+
+    async def futures_klines(
+        self,
+        symbol: str,
+        interval: Timeframe | str,
+        limit: int | None = None,
+        start_time: int | None = None,
+        end_time: int | None = None,
+    ) -> list[KlineDict]:
+        """Возвращает список свечей для тикера.
+
+        Параметры:
+            symbol (str): Название тикера.
+            limit (int | None): Количество свечей.
+            interval (Timeframe | str): Таймфрейм свечей.
+            start_time (int | None): Время начала периода в миллисекундах.
+            end_time (int | None): Время окончания периода в миллисекундах.
+
+        Возвращает:
+            list[KlineDict]: Список свечей для тикера.
+        """
+        if not limit and not all([start_time, end_time]):
+            raise ValueError("limit or (start_time and end_time) must be provided")
+
+        if limit:  # Перезаписываем start_time и end_time если указан limit, т.к. по умолчанию HyperLiquid не принимают этот параметр
+            if not isinstance(interval, Timeframe):
+                raise ValueError("interval must be a Timeframe if limit param provided")
+            start_time, end_time = self.limit_to_start_and_end_time(
+                interval, limit, use_milliseconds=False
+            )
+        interval = (
+            interval.to_exchange_format(Exchange.KUCOIN)
+            if isinstance(interval, Timeframe)
+            else interval
+        )
+        raw_data = await self._client.kline(
+            trade_type="FUTURES",
+            symbol=symbol,
+            interval=interval,
+            start_at=self.to_seconds(start_time),
+            end_at=self.to_seconds(end_time),
+        )
+        return Adapter.klines(raw_data=raw_data, symbol=symbol)
+
+    async def funding_rate(self, symbol: str | None = None) -> dict[str, float] | float:
+        """Возвращает ставку финансирования для тикера.
+
+        Параметры:
+            symbol (`str | None`): Название тикера. На Kucoin параметр обязателен.
+
+        Возвращает:
+            `dict[str, float] | float`: Ставка финансирования в процентах.
+        """
+        if not symbol:
+            raise ValueError("Symbol is required to fetch Kucoin funding rate")
+        raw_data = await self._client.funding_rate(symbol=symbol)
+        return Adapter.funding_rate(raw_data)
+
+    @overload
+    async def open_interest(self, symbol: str) -> OpenInterestItem: ...
+
+    @overload
+    async def open_interest(self, symbol: None) -> OpenInterestDict: ...
+
+    @overload
+    async def open_interest(self) -> OpenInterestDict: ...
+
+    async def open_interest(self, symbol: str | None = None) -> OpenInterestItem | OpenInterestDict:
+        """Возвращает объем открытого интереса для тикера или всех тикеров, если тикер не указан.
+
+        Параметры:
+            symbol (`str | None`): Название тикера. (Опционально, но обязателен для следующих бирж: BINANCE).
+
+        Возвращает:
+            `OpenInterestItem | OpenInterestDict`: Если тикер передан - словарь со временем и объемом
+                открытого интереса в монетах. Если нет передан - то словарь, в котором ключ - тикер,
+                а значение - словарь с временем и объемом открытого интереса в монетах.
+        """
+        raw_data = await self._client.open_interest()
+        adapted_data = Adapter.open_interest(raw_data)
+        return adapted_data[symbol] if symbol else adapted_data