ddx-python 1.0.5__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

ddx/rest_client/clients/trade_client.py

@@ -0,0 +1,335 @@
+from typing import Optional, AsyncIterator
+
+from ddx.rest_client.clients.base_client import BaseClient
+from ddx.rest_client.constants.endpoints import Trade
+from ddx.rest_client.models.trade import (
+    FeesHistoryResponse,
+    Fee,
+    PositionsResponse,
+    Position,
+    StrategyResponse,
+    StrategyMetricsResponse,
+    TraderResponse,
+)
+
+
+class TradeClient(BaseClient):
+    """
+    Trade-related operations and data access.
+
+    Provides access to strategy fees, positions, metrics, and trader information
+    through the API endpoints.
+    """
+
+    async def get_strategy_fees_history_page(
+        self,
+        trader: str,
+        strategy_id: str,
+        limit: Optional[int] = None,
+        epoch: Optional[int] = None,
+        tx_ordinal: Optional[int] = None,
+        ordinal: Optional[int] = None,
+        symbol: Optional[str] = None,
+        order: Optional[str] = None,
+    ) -> FeesHistoryResponse:
+        """
+        Get a single page of maker/taker fee aggregates for a strategy.
+
+        Parameters
+        ----------
+        trader : str
+            The trader address
+        strategy_id : str
+            The strategy ID
+        limit : Optional[int]
+            The number of rows to return
+        epoch : Optional[int]
+            The epoch boundary used when fetching the next timeseries page
+        tx_ordinal : Optional[int]
+            The txOrdinal boundary used when fetching the next timeseries page.
+            Must be passed along with epoch
+        ordinal : Optional[int]
+            The ordinal boundary used when fetching the next timeseries page.
+            Must be passed along with epoch and txOrdinal
+        symbol : Optional[str]
+            The symbol
+        order : Optional[str]
+            The ordering of the results. Values: "asc", "desc"
+
+        Returns
+        -------
+        FeesHistoryResponse
+            Single page of strategy fees history data
+        """
+
+        params = {
+            "trader": trader,
+            "strategyId": strategy_id,
+            "limit": limit,
+            "epoch": epoch,
+            "txOrdinal": tx_ordinal,
+            "ordinal": ordinal,
+            "symbol": symbol,
+            "order": order,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        response = await self._http.get(
+            self._build_url(Trade.GET_STRATEGY_FEES_HISTORY), params=params
+        )
+
+        return FeesHistoryResponse.model_validate(response)
+
+    async def get_strategy_fees_history(
+        self,
+        trader: str,
+        strategy_id: str,
+        symbol: Optional[str] = None,
+        order: Optional[str] = None,
+        limit: Optional[int] = 100,
+    ) -> AsyncIterator[Fee]:
+        """
+        Get all maker/taker fee aggregates for a strategy.
+
+        Automatically handles pagination using epoch, tx_ordinal, and ordinal.
+
+        Parameters
+        ----------
+        trader : str
+            The trader address
+        strategy_id : str
+            The strategy ID
+        symbol : Optional[str]
+            The symbol
+        order : Optional[str]
+            The ordering of the results. Values: "asc", "desc"
+        limit : Optional[int]
+            The number of rows to return per page
+
+        Yields
+        ------
+        Fee
+            Strategy fee entries
+        """
+
+        epoch = None
+        tx_ordinal = None
+        ordinal = None
+
+        while True:
+            response = await self.get_strategy_fees_history_page(
+                trader=trader,
+                strategy_id=strategy_id,
+                limit=limit,
+                epoch=epoch,
+                tx_ordinal=tx_ordinal,
+                ordinal=ordinal,
+                symbol=symbol,
+                order=order,
+            )
+
+            if not response.value:
+                break
+
+            for item in response.value:
+                yield item
+
+            if response.next_epoch is None:
+                break
+
+            epoch = response.next_epoch
+            tx_ordinal = response.next_tx_ordinal
+            ordinal = response.next_ordinal
+
+    async def get_strategy_positions_page(
+        self,
+        trader: str,
+        strategy_id: str,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        symbol: Optional[str] = None,
+    ) -> PositionsResponse:
+        """
+        Get a single page of current positions for a strategy.
+
+        Parameters
+        ----------
+        trader : str
+            The trader address
+        strategy_id : str
+            The strategy ID
+        limit : Optional[int]
+            The number of rows to return
+        offset : Optional[int]
+            The offset of returned rows
+        symbol : Optional[str]
+            The symbol
+
+        Returns
+        -------
+        PositionsResponse
+            Single page of strategy positions data
+        """
+
+        params = {
+            "trader": trader,
+            "strategyId": strategy_id,
+            "limit": limit,
+            "offset": offset,
+            "symbol": symbol,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+
+        response = await self._http.get(
+            self._build_url(Trade.GET_STRATEGY_POSITIONS), params=params
+        )
+
+        return PositionsResponse.model_validate(response)
+
+    async def get_strategy_positions(
+        self,
+        trader: str,
+        strategy_id: str,
+        symbol: Optional[str] = None,
+        limit: Optional[int] = 100,
+    ) -> AsyncIterator[Position]:
+        """
+        Get all current positions for a strategy.
+
+        Automatically handles pagination using offset.
+
+        Parameters
+        ----------
+        trader : str
+            The trader address
+        strategy_id : str
+            The strategy ID
+        symbol : Optional[str]
+            The symbol
+        limit : Optional[int]
+            The number of rows to return per page
+
+        Yields
+        ------
+        Position
+            Strategy position entries
+        """
+
+        offset = 0
+
+        while True:
+            response = await self.get_strategy_positions_page(
+                trader=trader,
+                strategy_id=strategy_id,
+                limit=limit,
+                offset=offset,
+                symbol=symbol,
+            )
+
+            if not response.value:
+                break
+
+            for item in response.value:
+                yield item
+
+            if len(response.value) < limit:
+                break
+
+            offset += len(response.value)
+
+    async def get_strategy(
+        self,
+        trader: str,
+        strategy_id: str,
+    ) -> StrategyResponse:
+        """
+        Get current state of trader's strategy.
+
+        Parameters
+        ----------
+        trader : str
+            The trader address
+        strategy_id : str
+            The strategy ID
+
+        Returns
+        -------
+        StrategyResponse
+            Strategy information including trader address, strategy ID hash,
+            max leverage, available collateral, locked collateral, and frozen status
+        """
+
+        params = {
+            "trader": trader,
+            "strategyId": strategy_id,
+        }
+
+        response = await self._http.get(
+            self._build_url(Trade.GET_STRATEGY), params=params
+        )
+
+        return StrategyResponse.model_validate(response)
+
+    async def get_strategy_metrics(
+        self,
+        trader: str,
+        strategy_id: str,
+    ) -> StrategyMetricsResponse:
+        """
+        Get KPIs and risk metrics for a strategy.
+
+        Includes margin fraction, maintenance margin ratio, leverage,
+        strategy available collateral and strategy value.
+
+        Parameters
+        ----------
+        trader : str
+            The trader address
+        strategy_id : str
+            The strategy ID
+
+        Returns
+        -------
+        StrategyMetricsResponse
+            Strategy metrics including margin fraction, MMR, leverage,
+            strategy margin, and strategy value
+        """
+
+        params = {
+            "trader": trader,
+            "strategyId": strategy_id,
+        }
+
+        response = await self._http.get(
+            self._build_url(Trade.GET_STRATEGY_METRICS), params=params
+        )
+
+        return StrategyMetricsResponse.model_validate(response)
+
+    async def get_trader(
+        self,
+        trader: str,
+    ) -> TraderResponse:
+        """
+        Get current trader DDX balance and profile.
+
+        Parameters
+        ----------
+        trader : str
+            The trader address
+
+        Returns
+        -------
+        TraderResponse
+            Trader information including DDX balances and fee payment preferences
+        """
+
+        params = {
+            "trader": trader,
+        }
+
+        response = await self._http.get(
+            self._build_url(Trade.GET_TRADER), params=params
+        )
+
+        return TraderResponse.model_validate(response)

ddx/rest_client/constants/endpoints.py

@@ -0,0 +1,67 @@
+from enum import Enum
+
+
+class System(str, Enum):
+    """Enum containing all system-related endpoint paths."""
+
+    GET_EXCHANGE_INFO = "/exchange/api/v1/exchange_info"
+    GET_CONNECTION_INFO = "/exchange/api/v1/ping"
+    GET_SYMBOLS = "/exchange/api/v1/symbols"
+    GET_SERVER_TIME = "/exchange/api/v1/time"
+    GET_COLLATERAL_AGGREGATION = "/stats/api/v1/aggregations/collateral"
+    GET_DDX_AGGREGATION = "/stats/api/v1/aggregations/ddx"
+    GET_INSURANCE_FUND_AGGREGATION = "/stats/api/v1/aggregations/insurance_fund"
+    GET_EPOCH_HISTORY = "/stats/api/v1/epochs"
+    GET_INSURANCE_FUND_HISTORY = "/stats/api/v1/insurance_fund"
+    GET_SPECS = "/stats/api/v1/specs"
+    GET_EXCHANGE_STATUS = "/stats/api/v1/status"
+    GET_DDX_SUPPLY = "/stats/api/v1/supply"
+    GET_TRADABLE_PRODUCTS = "/stats/api/v1/tradable_products"
+
+    GET_DEPLOYMENT_INFO = "/contract-server/addresses"
+
+
+class Trade(str, Enum):
+    """Enum containing all trade-related endpoint paths."""
+
+    GET_STRATEGY_FEES_HISTORY = "/stats/api/v1/fees"
+    GET_STRATEGY_POSITIONS = "/stats/api/v1/positions"
+    GET_STRATEGY = "/stats/api/v1/strategy"
+    GET_STRATEGY_METRICS = "/stats/api/v1/strategy_metrics"
+    GET_TRADER = "/stats/api/v1/trader"
+
+
+class Market(str, Enum):
+    """Enum containing all market-related endpoint paths."""
+
+    GET_MARK_PRICE_HISTORY = "/exchange/api/v1/mark_prices"
+    GET_ORDER_BOOK_L3 = "/exchange/api/v1/order_book"
+    GET_ORDER_UPDATE_HISTORY = "/exchange/api/v1/order_updates"
+    GET_STRATEGY_UPDATE_HISTORY = "/exchange/api/v1/strategy_updates"
+    GET_TICKERS = "/exchange/api/v1/tickers"
+    GET_TRADER_UPDATE_HISTORY = "/exchange/api/v1/trader_updates"
+    GET_BALANCE_AGGREGATION = "/stats/api/v1/aggregations/balance"
+    GET_FEES_AGGREGATION = "/stats/api/v1/aggregations/fees"
+    GET_FUNDING_RATE_COMPARISON_AGGREGATION = (
+        "/stats/api/v1/aggregations/funding_rate_comparison"
+    )
+    GET_TOP_TRADERS_AGGREGATION = "/stats/api/v1/aggregations/traders"
+    GET_VOLUME_AGGREGATION = "/stats/api/v1/aggregations/volume"
+    GET_FUNDING_RATE_HISTORY = "/stats/api/v1/funding_rate_history"
+    GET_OPEN_INTEREST_HISTORY = "/stats/api/v1/open_interest_history"
+    GET_ORDER_BOOK_L2 = "/stats/api/v1/order_book_l2"
+    GET_PRICE_CHECKPOINT_HISTORY = "/stats/api/v1/price_checkpoints"
+
+
+class Signed(str, Enum):
+    """Enum containing all signed endpoint paths."""
+
+    ENCRYPTION_KEY = "/v2/encryption-key"
+    SUBMIT_REQUEST = "/v2/request"
+
+
+class OnChain(str, Enum):
+    """Enum containing all on-chain-related endpoint paths."""
+
+    KYC_AUTH = "/kyc/v1/kyc-auth"
+    PROOF = "/v2/proof"