candlefeed 0.1.0__py3-none-any.whl

candlefeed/__init__.py

@@ -0,0 +1,27 @@
+"""CandleFeed — the official Python client for the CandleFeed crypto market-data API.
+
+    from candlefeed import CandleFeed
+
+    cf = CandleFeed(api_key="cf_live_...")
+    df = cf.get_ohlcv("BTCUSDT", interval="1h", limit=5)
+"""
+from .client import CandleFeed
+from .exceptions import (
+    AuthenticationError,
+    CandleFeedError,
+    InvalidParameterError,
+    RateLimitError,
+    TierRestrictedError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CandleFeed",
+    "CandleFeedError",
+    "AuthenticationError",
+    "TierRestrictedError",
+    "InvalidParameterError",
+    "RateLimitError",
+    "__version__",
+]

candlefeed/client.py

@@ -0,0 +1,626 @@
+"""CandleFeed API client — pandas-native access to crypto market data."""
+from __future__ import annotations
+
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+import pandas as pd
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    CandleFeedError,
+    InvalidParameterError,
+    RateLimitError,
+    TierRestrictedError,
+)
+
+__all__ = ["CandleFeed"]
+
+DEFAULT_BASE_URL = "https://candlefeed.ai/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 4
+
+TimeLike = Union[str, datetime, None]
+
+# Columns that should be coerced to float when present in a response.
+_NUMERIC_COLUMNS = {
+    "open", "high", "low", "close", "volume", "quote_volume",
+    "funding_rate", "mark_price",
+    "weighted_funding_rate", "total_oi_usd",
+    "open_interest", "open_interest_value",
+    "quantity", "price", "usd_value",
+    "long_liq_usd", "short_liq_usd", "total_liq_usd",
+    "long_short_ratio", "long_account_ratio", "short_account_ratio",
+    "buy_volume", "sell_volume", "buy_sell_ratio",
+    "open_basis", "close_basis", "open_change", "close_change",
+    "strike", "mark_iv", "delta", "gamma", "vega", "theta", "rho",
+    "bid_price", "ask_price", "underlying_price", "index_price",
+    "liquidation_count", "liquidation_volume_usd",
+}
+
+# Candidate timestamp column names, in priority order. The API uses ``time`` on
+# most endpoints and ``timestamp`` on the aggregated ones.
+_TIME_COLUMNS = ("time", "timestamp")
+
+
+def _to_iso(value: TimeLike) -> Optional[str]:
+    """Normalize a datetime/str to an ISO8601 string the API accepts."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.isoformat()
+    return str(value)
+
+
+class CandleFeed:
+    """Client for the CandleFeed crypto market-data API.
+
+    Every data method returns a tidy :class:`pandas.DataFrame` indexed by the
+    parsed timestamp. Range requests auto-paginate (follow ``next_cursor``) and
+    rate limits are retried with bounded backoff.
+
+    Args:
+        api_key: Your CandleFeed API key. Falls back to the ``CANDLEFEED_API_KEY``
+            environment variable.
+        base_url: API base URL. Defaults to production.
+        timeout: Per-request timeout in seconds.
+        max_retries: Max retry attempts on HTTP 429 / transient network errors.
+        session: Optional pre-configured :class:`requests.Session`.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        key = api_key or os.environ.get("CANDLEFEED_API_KEY")
+        if not key:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key= or set the "
+                "CANDLEFEED_API_KEY environment variable. Get a key at "
+                "https://candlefeed.ai",
+                code="unauthorized",
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = session or requests.Session()
+        self._session.headers.update(
+            {
+                "X-API-Key": self.api_key,
+                "Accept": "application/json",
+                "User-Agent": "candlefeed-python/0.1.0",
+            }
+        )
+        self.last_rate_limit: Dict[str, Optional[str]] = {}
+
+    def __repr__(self) -> str:
+        masked = f"{self.api_key[:11]}…" if len(self.api_key) > 11 else "set"
+        return f"CandleFeed(base_url={self.base_url!r}, api_key={masked!r})"
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> "CandleFeed":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------ #
+    # HTTP plumbing
+    # ------------------------------------------------------------------ #
+    def _request(self, path: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Issue a single GET, map errors, and retry on 429/transient failures."""
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        clean = {k: v for k, v in params.items() if v is not None}
+
+        attempt = 0
+        while True:
+            try:
+                resp = self._session.get(url, params=clean, timeout=self.timeout)
+            except requests.RequestException as exc:
+                if attempt < self.max_retries:
+                    time.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise CandleFeedError(f"Request to {url} failed: {exc}") from exc
+
+            self._capture_rate_limit(resp)
+
+            if resp.status_code == 429:
+                retry_after = self._retry_after_seconds(resp)
+                if attempt < self.max_retries:
+                    time.sleep(retry_after if retry_after is not None else self._backoff(attempt))
+                    attempt += 1
+                    continue
+                code, message = self._extract_error(resp)
+                raise RateLimitError(
+                    message or "Rate limit exceeded.",
+                    code=code or "rate_limit_exceeded",
+                    status_code=429,
+                    retry_after=retry_after,
+                )
+
+            if resp.status_code >= 400:
+                self._raise_for_error(resp)
+
+            try:
+                return resp.json()
+            except ValueError as exc:
+                raise CandleFeedError(
+                    f"Non-JSON response from {url} (HTTP {resp.status_code})."
+                ) from exc
+
+    def _raise_for_error(self, resp: requests.Response) -> None:
+        code, message = self._extract_error(resp)
+        status = resp.status_code
+        msg = message or f"HTTP {status} error"
+        if status == 401:
+            raise AuthenticationError(msg, code=code, status_code=status)
+        if status == 403:
+            raise TierRestrictedError(msg, code=code or "tier_restricted", status_code=status)
+        if status in (400, 422):
+            raise InvalidParameterError(msg, code=code, status_code=status)
+        raise CandleFeedError(msg, code=code, status_code=status)
+
+    @staticmethod
+    def _extract_error(resp: requests.Response) -> tuple[Optional[str], Optional[str]]:
+        try:
+            body = resp.json()
+        except ValueError:
+            return None, resp.text or None
+        # FastAPI wraps HTTPException detail under "detail"; our handlers also
+        # return the envelope at the top level. Support both.
+        detail = body.get("detail") if isinstance(body, dict) else None
+        if isinstance(detail, dict):
+            return detail.get("code"), detail.get("message")
+        if isinstance(detail, str):
+            return None, detail
+        if isinstance(body, dict):
+            return body.get("code"), body.get("message")
+        return None, None
+
+    def _capture_rate_limit(self, resp: requests.Response) -> None:
+        for header in ("X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "X-Plan"):
+            if header in resp.headers:
+                self.last_rate_limit[header] = resp.headers[header]
+
+    @staticmethod
+    def _retry_after_seconds(resp: requests.Response) -> Optional[float]:
+        ra = resp.headers.get("Retry-After")
+        if ra is not None:
+            try:
+                return float(ra)
+            except ValueError:
+                pass
+        reset = resp.headers.get("X-RateLimit-Reset")
+        if reset:
+            try:
+                reset_dt = datetime.fromisoformat(reset.replace("Z", "+00:00"))
+                if reset_dt.tzinfo is None:
+                    reset_dt = reset_dt.replace(tzinfo=timezone.utc)
+                delta = (reset_dt - datetime.now(timezone.utc)).total_seconds()
+                return max(delta, 0.0)
+            except ValueError:
+                pass
+        return None
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        # 0.5s, 1s, 2s, 4s … capped at 30s.
+        return min(0.5 * (2 ** attempt), 30.0)
+
+    # ------------------------------------------------------------------ #
+    # Pagination + DataFrame assembly
+    # ------------------------------------------------------------------ #
+    def _fetch(
+        self,
+        path: str,
+        params: Dict[str, Any],
+        paginate: bool,
+        max_rows: Optional[int],
+    ) -> List[Dict[str, Any]]:
+        """Fetch rows from a cursor-paginated endpoint."""
+        rows: List[Dict[str, Any]] = []
+        cursor: Optional[str] = params.get("cursor")
+        while True:
+            page_params = dict(params)
+            if cursor is not None:
+                page_params["cursor"] = cursor
+            body = self._request(path, page_params)
+            page = body.get("data") or []
+            rows.extend(page)
+
+            if max_rows is not None and len(rows) >= max_rows:
+                return rows[:max_rows]
+
+            next_cursor = body.get("next_cursor")
+            if not paginate or not body.get("has_more") or not next_cursor:
+                return rows
+            if next_cursor == cursor:  # guard against a stuck cursor
+                return rows
+            cursor = next_cursor
+
+    @staticmethod
+    def _to_frame(rows: List[Dict[str, Any]], index: bool = True) -> pd.DataFrame:
+        """Build a tidy DataFrame: parsed datetime index, float numerics."""
+        df = pd.DataFrame(rows)
+        if df.empty:
+            return df
+
+        time_col = next((c for c in _TIME_COLUMNS if c in df.columns), None)
+        if time_col is not None:
+            df[time_col] = pd.to_datetime(df[time_col], utc=True, errors="coerce")
+
+        for col in df.columns:
+            if col in _NUMERIC_COLUMNS:
+                df[col] = pd.to_numeric(df[col], errors="coerce")
+
+        if index and time_col is not None:
+            df = df.set_index(time_col).sort_index()
+        return df
+
+    def _query(
+        self,
+        path: str,
+        params: Dict[str, Any],
+        paginate: bool,
+        max_rows: Optional[int],
+    ) -> pd.DataFrame:
+        rows = self._fetch(path, params, paginate=paginate, max_rows=max_rows)
+        return self._to_frame(rows)
+
+    # ------------------------------------------------------------------ #
+    # OHLCV / candles
+    # ------------------------------------------------------------------ #
+    def get_ohlcv(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        interval: str = "1m",
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Historical OHLCV candles.
+
+        Intervals: ``1m, 5m, 15m, 1h, 4h, 1d``. Returns a DataFrame indexed by
+        ``time`` with ``open, high, low, close, volume, quote_volume`` columns.
+        """
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "interval": interval,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("candles", params, paginate, max_rows)
+
+    get_candles = get_ohlcv
+
+    # ------------------------------------------------------------------ #
+    # Funding rates
+    # ------------------------------------------------------------------ #
+    def get_funding_rates(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Per-exchange funding rates (``funding_rate``, ``mark_price``)."""
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("funding-rates", params, paginate, max_rows)
+
+    def get_funding_rates_aggregated(
+        self,
+        symbol: str,
+        interval: str = "1h",
+        exchanges: Optional[Union[str, List[str]]] = None,
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """OI-weighted funding rate across exchanges.
+
+        Intervals: ``1h, 4h, 1d``. Returns ``weighted_funding_rate``,
+        ``total_oi_usd``, ``exchange_count``, ``contributing_exchanges``,
+        indexed by ``timestamp``.
+        """
+        if isinstance(exchanges, (list, tuple)):
+            exchanges = ",".join(exchanges)
+        params = {
+            "symbol": symbol,
+            "interval": interval,
+            "exchanges": exchanges,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("funding-rates/aggregated", params, paginate, max_rows)
+
+    # ------------------------------------------------------------------ #
+    # Open interest
+    # ------------------------------------------------------------------ #
+    def get_open_interest(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        interval: str = "5m",
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Open interest (``open_interest``, ``open_interest_value``).
+
+        Intervals: ``5m, 15m, 1h, 4h, 1d``.
+        """
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "interval": interval,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("open-interest", params, paginate, max_rows)
+
+    # ------------------------------------------------------------------ #
+    # Liquidations
+    # ------------------------------------------------------------------ #
+    def get_liquidations(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        side: Optional[str] = None,
+        interval: Optional[str] = None,
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Liquidation events.
+
+        Omit ``interval`` for tick-level rows (``side, quantity, price,
+        usd_value``); pass an interval (``1m, 5m, 15m, 1h, 4h, 1d``) for bucketed
+        ``long_liq_usd / short_liq_usd / total_liq_usd / count``. ``side`` filters
+        to ``long`` or ``short``.
+        """
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "side": side,
+            "interval": interval,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("liquidations", params, paginate, max_rows)
+
+    def get_liquidations_aggregated(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        interval: str = "1d",
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Pre-aggregated liquidation history (CoinGlass backfill).
+
+        Intervals: ``4h, 6h, 8h, 12h, 1d``. Returns ``long_liq_usd``,
+        ``short_liq_usd`` indexed by ``timestamp``. This endpoint is not
+        cursor-paginated (it returns ``meta.total``); use ``limit`` to size the
+        single page.
+        """
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "interval": interval,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        body = self._request("liquidations/aggregated", params)
+        return self._to_frame(body.get("data") or [])
+
+    # ------------------------------------------------------------------ #
+    # Long/short ratio
+    # ------------------------------------------------------------------ #
+    def get_long_short_ratio(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        interval: str = "5m",
+        ratio_type: Optional[str] = None,
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Long/short account ratio.
+
+        Intervals: ``5m, 15m, 1h, 4h, 1d``. ``ratio_type`` is one of
+        ``top_account`` (default), ``global_account``, or ``both``.
+        """
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "interval": interval,
+            "ratio_type": ratio_type,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("long-short-ratio", params, paginate, max_rows)
+
+    # ------------------------------------------------------------------ #
+    # Taker volume
+    # ------------------------------------------------------------------ #
+    def get_taker_volume(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Taker buy/sell volume (``buy_volume, sell_volume, buy_sell_ratio``)."""
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("taker-volume", params, paginate, max_rows)
+
+    # ------------------------------------------------------------------ #
+    # Basis
+    # ------------------------------------------------------------------ #
+    def get_basis(
+        self,
+        symbol: str,
+        exchange: str = "binance",
+        interval: str = "4h",
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Futures basis / premium (``open_basis, close_basis, ...``).
+
+        Intervals: ``1h, 4h``.
+        """
+        params = {
+            "symbol": symbol,
+            "exchange": exchange,
+            "interval": interval,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("basis", params, paginate, max_rows)
+
+    # ------------------------------------------------------------------ #
+    # Combined
+    # ------------------------------------------------------------------ #
+    def get_combined(
+        self,
+        symbol: str,
+        interval: str = "1m",
+        fields: Union[str, List[str]] = "ohlcv,funding_rate",
+        exchange: str = "binance",
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Time-aligned multi-dataset frame on an OHLCV base timeline.
+
+        ``fields`` is a comma-separated string or list drawn from ``ohlcv,
+        open_interest, funding_rate, long_short, taker_volume, liquidations``;
+        supplementary datasets are forward-filled onto each candle.
+        """
+        if isinstance(fields, (list, tuple)):
+            fields = ",".join(fields)
+        params = {
+            "symbol": symbol,
+            "interval": interval,
+            "fields": fields,
+            "exchange": exchange,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("combined", params, paginate, max_rows)
+
+    # ------------------------------------------------------------------ #
+    # Options
+    # ------------------------------------------------------------------ #
+    def get_options(
+        self,
+        currency: str = "BTC",
+        instrument_name: Optional[str] = None,
+        option_type: Optional[str] = None,
+        expiry: Optional[str] = None,
+        start: TimeLike = None,
+        end: TimeLike = None,
+        limit: Optional[int] = None,
+        paginate: bool = True,
+        max_rows: Optional[int] = None,
+    ) -> pd.DataFrame:
+        """Deribit options chain snapshots with greeks and IV (Pro+).
+
+        ``currency`` is ``BTC`` or ``ETH``. Optional filters: ``instrument_name``,
+        ``option_type`` (``C``/``P``), ``expiry`` (``YYYY-MM-DD``).
+        """
+        params = {
+            "currency": currency,
+            "instrument_name": instrument_name,
+            "option_type": option_type,
+            "expiry": expiry,
+            "start": _to_iso(start),
+            "end": _to_iso(end),
+            "limit": limit,
+        }
+        return self._query("options", params, paginate, max_rows)
+
+    # ------------------------------------------------------------------ #
+    # Metadata
+    # ------------------------------------------------------------------ #
+    def symbols(self) -> pd.DataFrame:
+        """Available symbols with per-exchange date coverage."""
+        body = self._request("symbols", {})
+        df = pd.DataFrame(body.get("symbols") or [])
+        for col in ("available_from", "available_to"):
+            if col in df.columns:
+                df[col] = pd.to_datetime(df[col], utc=True, errors="coerce")
+        return df
+
+    def exchanges(self) -> pd.DataFrame:
+        """Supported exchanges with their datasets and symbol counts."""
+        body = self._request("exchanges", {})
+        return pd.DataFrame(body.get("exchanges") or [])
+
+    def datasets(self) -> pd.DataFrame:
+        """Available datasets and descriptions."""
+        body = self._request("datasets", {})
+        return pd.DataFrame(body.get("datasets") or [])
+
+    def status(self) -> Dict[str, Any]:
+        """API health and per-dataset data freshness (raw dict)."""
+        return self._request("status", {})

candlefeed/exceptions.py

@@ -0,0 +1,66 @@
+"""Exception hierarchy for the CandleFeed client."""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class CandleFeedError(Exception):
+    """Base exception for all CandleFeed client errors.
+
+    Carries the API error ``code`` and ``message`` from the response envelope
+    (``{"status": "error", "code": ..., "message": ...}``) when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+    ) -> None:
+        self.code = code
+        self.status_code = status_code
+        self.message = message
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code is not None:
+            parts.append(f"HTTP {self.status_code}")
+        if self.code:
+            parts.append(self.code)
+        prefix = f"[{' '.join(parts)}] " if parts else ""
+        return f"{prefix}{self.message}"
+
+
+class AuthenticationError(CandleFeedError):
+    """Raised on HTTP 401 — missing, invalid, or revoked API key."""
+
+
+class TierRestrictedError(CandleFeedError):
+    """Raised on HTTP 403 ``tier_restricted`` — the resource needs an upgrade.
+
+    The ``message`` echoes the API's upgrade nudge (which symbol/dataset/exchange
+    or history window is gated, and the plan required).
+    """
+
+
+class InvalidParameterError(CandleFeedError):
+    """Raised on HTTP 400/422 — a query parameter was rejected by the API."""
+
+
+class RateLimitError(CandleFeedError):
+    """Raised on HTTP 429 after the client's retries are exhausted.
+
+    ``retry_after`` is the server-advertised seconds until the limit resets
+    (from the ``Retry-After`` header), when present.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, code=code, status_code=status_code)

candlefeed-0.1.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: candlefeed
+Version: 0.1.0
+Summary: Official Python client for the CandleFeed crypto market-data API — OHLCV, funding, open interest, liquidations, basis, options. Returns pandas DataFrames.
+Project-URL: Homepage, https://candlefeed.ai
+Project-URL: Documentation, https://candlefeed.ai/docs
+Project-URL: Pricing, https://candlefeed.ai/#pricing
+Project-URL: Repository, https://github.com/candlefeed-ai/candlefeed-python
+Author-email: CandleFeed <support@candlefeed.ai>
+License: MIT
+License-File: LICENSE
+Keywords: algotrading,backtesting,crypto,crypto-derivatives,funding-rates,liquidations,market-data,open-interest,pandas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.3
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# candlefeed
+
+**The official Python client for [CandleFeed](https://candlefeed.ai) — crypto market data that lands straight in a pandas DataFrame.**
+
+OHLCV, funding rates, open interest, liquidations, long/short ratio, taker volume, basis, and Deribit options — across Binance, Bybit, OKX, and more. Auth, cursor pagination, and rate limits are handled for you. One call, one DataFrame.
+
+```bash
+pip install candlefeed
+```
+
+## Time to first DataFrame
+
+```python
+from candlefeed import CandleFeed
+
+cf = CandleFeed(api_key="cf_live_...")          # or set CANDLEFEED_API_KEY
+df = cf.get_ohlcv("BTCUSDT", interval="1h", limit=5)
+print(df)
+```
+
+```
+                              open      high       low     close      volume   quote_volume
+time
+2026-06-06 18:00:00+00:00  69841.0   70120.5   69770.0   70011.2   1183.42   8.27e+07
+2026-06-06 19:00:00+00:00  70011.2   70250.0   69905.1   70180.9   964.18    6.77e+07
+...
+```
+
+The frame is indexed by a tz-aware `DatetimeIndex` and every numeric column is a float — ready for `.resample()`, `.rolling()`, or a backtest loop.
+
+## Authentication
+
+Pass your key directly or via the environment:
+
+```python
+cf = CandleFeed(api_key="cf_live_...")
+# or
+export CANDLEFEED_API_KEY=cf_live_...
+cf = CandleFeed()
+```
+
+Get a key at **[candlefeed.ai](https://candlefeed.ai)**. The free tier covers Binance majors and the last 30 days; Builder/Pro unlock full history, every exchange, and the derived datasets.
+
+## Endpoints
+
+| Method | Data | Key params |
+| --- | --- | --- |
+| `get_ohlcv` / `get_candles` | OHLCV candles | `symbol, exchange, interval, start, end, limit` |
+| `get_funding_rates` | Per-exchange funding | `symbol, exchange, ...` |
+| `get_funding_rates_aggregated` | OI-weighted funding across venues | `symbol, interval, exchanges` |
+| `get_open_interest` | Open interest | `symbol, exchange, interval` |
+| `get_liquidations` | Liquidation events (tick or bucketed) | `symbol, exchange, side, interval` |
+| `get_liquidations_aggregated` | Pre-aggregated liquidation history | `symbol, exchange, interval` |
+| `get_long_short_ratio` | Long/short account ratio | `symbol, exchange, interval, ratio_type` |
+| `get_taker_volume` | Taker buy/sell volume | `symbol, exchange, ...` |
+| `get_basis` | Futures basis / premium | `symbol, exchange, interval` |
+| `get_combined` | Time-aligned multi-dataset frame | `symbol, interval, fields` |
+| `get_options` | Deribit options chain + greeks | `currency, instrument_name, expiry` |
+| `symbols` / `exchanges` / `datasets` / `status` | Metadata | — |
+
+**Intervals** — OHLCV: `1m 5m 15m 1h 4h 1d` · aggregated funding: `1h 4h 1d` · open interest: `5m 15m 1h 4h 1d` · aggregated liquidations: `4h 6h 8h 12h 1d` · basis: `1h 4h`.
+
+## Date ranges auto-paginate
+
+Ask for a window and the client transparently follows the API's `next_cursor` until the range is complete, concatenating into one DataFrame:
+
+```python
+df = cf.get_funding_rates(
+    "BTCUSDT", exchange="binance",
+    start="2026-01-01", end="2026-03-01",
+)            # many pages → a single tidy frame
+```
+
+Cap the result with `max_rows=...`, control page size with `limit=...`, or disable
+auto-paging entirely with `paginate=False` to fetch a single page and inspect the cursor yourself.
+
+## Multi-exchange, time-aligned
+
+```python
+agg = cf.get_funding_rates_aggregated(
+    "BTCUSDT", interval="1h",
+    exchanges=["binance", "bybit", "okx"],
+)
+agg[["weighted_funding_rate", "total_oi_usd", "exchange_count"]].tail()
+```
+
+```python
+panel = cf.get_combined(
+    "BTCUSDT", interval="1h",
+    fields=["ohlcv", "funding_rate", "open_interest"],
+)   # OHLCV base timeline with funding + OI forward-filled onto each candle
+```
+
+## Error handling
+
+Every API error maps to a typed exception carrying the API `code` and `message`:
+
+```python
+from candlefeed import (
+    CandleFeed, AuthenticationError, TierRestrictedError,
+    InvalidParameterError, RateLimitError,
+)
+
+cf = CandleFeed(api_key="cf_live_...")
+try:
+    df = cf.get_options(currency="BTC")
+except TierRestrictedError as e:
+    print(e.message)        # "...requires Pro tier or higher... Upgrade at https://candlefeed.ai/pricing"
+except RateLimitError as e:
+    print("retry after", e.retry_after, "seconds")
+except (AuthenticationError, InvalidParameterError) as e:
+    print(e.code, e.message)
+```
+
+| Exception | HTTP | When |
+| --- | --- | --- |
+| `AuthenticationError` | 401 | missing / invalid / revoked key |
+| `TierRestrictedError` | 403 | symbol, dataset, exchange, or history window above your plan |
+| `InvalidParameterError` | 400 / 422 | bad symbol, interval, or timestamp |
+| `RateLimitError` | 429 | raised only after the client's bounded backoff retries are exhausted |
+| `CandleFeedError` | — | base class; network / unexpected errors |
+
+On HTTP 429 the client honors `Retry-After` / `X-RateLimit-Reset` and retries with exponential backoff before giving up. Remaining-quota headers are exposed on `cf.last_rate_limit`.
+
+## Requirements
+
+Python ≥ 3.9, `requests`, and `pandas`. That's the whole dependency surface.
+
+## Links
+
+- Site & API keys — **https://candlefeed.ai**
+- Pricing — **https://candlefeed.ai/#pricing**
+
+MIT licensed.

candlefeed-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+candlefeed/__init__.py,sha256=ZhbD3rVNZ-DyfsRH2NWxUuXLkQrGvhREJnEMcViqWT4,612
+candlefeed/client.py,sha256=C6p7O5GAwYy2zM119QWY64dAB5lmqC7hWLR4op3-ceE,22613
+candlefeed/exceptions.py,sha256=Gyn5Wk8Pp8MvqTOZ90IZc9M7vhW26IKAuwtu56iHHuc,2019
+candlefeed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+candlefeed-0.1.0.dist-info/METADATA,sha256=3QaeO5RSTBtnhicW_l-lxPOBs7clUGpaCQx72ujj3jc,6931
+candlefeed-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+candlefeed-0.1.0.dist-info/licenses/LICENSE,sha256=Zr-qEO5jtbsQMwhQqpQRpWBi43byLeeGPwC1rOaffn4,1067
+candlefeed-0.1.0.dist-info/RECORD,,

candlefeed-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

candlefeed-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CandleFeed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.