src/fetchers/coindesk_client/derivatives.py

"""
derivatives.py – Derivatives endpoints for CoinDesk API client.

- list_markets(): List all available derivatives markets.
- get_latest_futures(symbol=None): Fetch the latest futures data, optionally for a symbol.
- get_futures_historical(days, limit=None): Retrieve futures historical data over N days.
- list_options(symbol=None): List available options or option chain for a given asset.
- get_options_historical(symbol, start, end=None, limit=None): Fetch options historical data over a timeframe.
"""

from client import BaseClient

class DerivativesClient(BaseClient):
    def list_markets(self):
        """
        List all available derivatives markets.
        """
        return self._get("derivatives/markets")

    def get_latest_futures(self, symbol=None):
        """
        Get the most recent futures data. If `symbol` is provided, returns data for that symbol.

        :param symbol: Futures symbol, e.g., "BTC-USD" (optional).
        """
        path = "derivatives/futures"
        if symbol:
            path += f"/{symbol}"
        return self._get(path)

    def get_futures_historical(self, days, limit=None):
        """
        Fetch historical futures data for the past `days` days.

        :param days: Number of days of history to retrieve.
        :param limit: Maximum number of records to return (optional).
        """
        params = {"days": days}
        if limit is not None:
            params["limit"] = limit
        return self._get("derivatives/futures/historical", params=params)

    def list_options(self, symbol=None):
        """
        List all available options or get the option chain for a symbol.

        :param symbol: Asset symbol for option chain, e.g., "BTC-USD" (optional).
        """
        path = "derivatives/options"
        if symbol:
            path += f"/{symbol}"
        return self._get(path)

    def get_options_historical(self, symbol, start, end=None, limit=None):
        """
        Fetch historical options data for a symbol over a timeframe.

        :param symbol: Asset symbol, e.g., "BTC-USD".
        :param start: ISO8601 start datetime string.
        :param end: ISO8601 end datetime string (optional).
        :param limit: Maximum number of records to return (optional).
        """
        params = {"start": start}
        if end:
            params["end"] = end
        if limit is not None:
            params["limit"] = limit
        return self._get(f"derivatives/options/{symbol}/historical", params=params)