cryptovol 0.1.0__py3-none-any.whl

cryptovol/__init__.py

@@ -0,0 +1,60 @@
+"""CryptoVol — Python SDK for the CryptoVol crypto implied volatility API.
+
+Quick start
+-----------
+
+    from cryptovol import CryptoVol
+
+    cv = CryptoVol(api_key="YOUR_RAPIDAPI_KEY")
+    idx = cv.vol_index(ccy="BTC", tenor="30D")
+    print(idx.data[-1].vol)
+
+See https://github.com/YOUR_GH_USERNAME/cryptovol-python for full docs.
+"""
+from .client import CryptoVol
+from .exceptions import (
+    AuthenticationError,
+    CryptoVolError,
+    NotFoundError,
+    PlanLimitError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from .models import (
+    Analytics,
+    BulkResultItem,
+    BulkVolResponse,
+    Greeks,
+    VolHistoryPoint,
+    VolHistoryResponse,
+    VolIndexPoint,
+    VolIndexResponse,
+    VolSurfacePoint,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CryptoVol",
+    # Exceptions
+    "CryptoVolError",
+    "AuthenticationError",
+    "PlanLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "TimeoutError",
+    # Models
+    "Analytics",
+    "Greeks",
+    "VolIndexResponse",
+    "VolIndexPoint",
+    "VolSurfacePoint",
+    "BulkVolResponse",
+    "BulkResultItem",
+    "VolHistoryResponse",
+    "VolHistoryPoint",
+]

cryptovol/client.py

@@ -0,0 +1,443 @@
+"""Synchronous client for the CryptoVol API.
+
+Quick start
+-----------
+
+    from cryptovol import CryptoVol
+
+    cv = CryptoVol(api_key="YOUR_RAPIDAPI_KEY")
+
+    # Daily 30-day BTC vol index
+    idx = cv.vol_index(ccy="BTC", tenor="30D")
+    print(idx.data[-1].vol)
+
+    # ATM vol for a specific expiry
+    pt = cv.vol_surface(
+        ccy="BTC", expiry="2026-12-26",
+        strike_type="moneyness", strike_value=1.0,
+        include_analytics=True,
+    )
+    print(pt.vol, pt.analytics.greeks.delta)
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Literal, Optional, Union
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    CryptoVolError,
+    NotFoundError,
+    PlanLimitError,
+    RateLimitError,
+    ServerError,
+    TimeoutError as CryptoVolTimeoutError,
+    ValidationError,
+)
+from .models import (
+    BulkVolResponse,
+    VolHistoryResponse,
+    VolIndexResponse,
+    VolSurfacePoint,
+)
+
+DEFAULT_BASE_URL = "https://cryptovol.p.rapidapi.com"
+DEFAULT_HOST = "cryptovol.p.rapidapi.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_USER_AGENT = "cryptovol-python/0.1.0"
+
+StrikeType = Literal["strike", "moneyness", "delta"]
+OptionType = Literal["C", "P"]
+Session = Literal["asia", "london", "us"]
+Tenor = Literal[
+    "1D", "1W", "2W", "3W", "1M", "2M", "3M", "6M", "9M", "1Y",
+    "7D", "14D", "21D", "30D", "60D", "90D", "180D", "270D", "365D",
+]
+
+
+class CryptoVol:
+    """Synchronous client for the CryptoVol REST API.
+
+    Parameters
+    ----------
+    api_key:
+        Your RapidAPI key. Get one at https://www.cryptovol.io/api.
+        Sent as ``X-RapidAPI-Key`` on every request.
+    base_url:
+        Override the API base URL. Defaults to the RapidAPI gateway.
+    host:
+        Value for the ``X-RapidAPI-Host`` header. You won't need to change
+        this unless you're routing through a different gateway.
+    timeout:
+        Per-request timeout in seconds. Defaults to 30s.
+    max_retries:
+        How many times to retry transient failures (network errors and 5xx
+        responses) with exponential backoff. Set to 0 to disable.
+    user_agent:
+        Custom User-Agent header. Useful if you're embedding the SDK in your
+        own product and want clean attribution in server logs.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        host: str = DEFAULT_HOST,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "api_key is required. Get a key at https://www.cryptovol.io/api"
+            )
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.host = host
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "X-RapidAPI-Key": api_key,
+                "X-RapidAPI-Host": host,
+                "User-Agent": user_agent,
+                "Accept": "application/json",
+            },
+        )
+
+    # ── Context manager support ──────────────────────────────────────────────
+
+    def __enter__(self) -> "CryptoVol":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client. Safe to call multiple times."""
+        self._client.close()
+
+    # ── Endpoints ────────────────────────────────────────────────────────────
+
+    def vol_index(
+        self,
+        ccy: str = "BTC",
+        tenor: str = "30D",
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        *,
+        raw: bool = False,
+    ) -> Union[VolIndexResponse, Dict[str, Any]]:
+        """Daily implied volatility index (CryptoVIX-style time series).
+
+        Parameters
+        ----------
+        ccy:
+            Asset symbol — one of ``BTC``, ``ETH``, ``SOL``, ``XRP``, ``AVAX``,
+            ``TRX``. Subject to your plan tier.
+        tenor:
+            Constant-maturity tenor (e.g. ``7D``, ``30D``, ``1M``, ``3M``).
+        start_date / end_date:
+            Optional ``YYYY-MM-DD`` bounds. If omitted, defaults to roughly
+            the last year (or the most that your plan allows).
+        raw:
+            If True, return the parsed JSON dict instead of a typed model.
+        """
+        params = _drop_none({
+            "ccy": ccy,
+            "tenor": tenor,
+            "start_date": start_date,
+            "end_date": end_date,
+        })
+        data = self._request("GET", "/v1/vol-index", params=params)
+        return data if raw else VolIndexResponse.model_validate(data)
+
+    def vol_surface(
+        self,
+        ccy: str,
+        expiry: str,
+        strike_type: StrikeType,
+        strike_value: float,
+        *,
+        option_type: OptionType = "C",
+        session: Session = "us",
+        date: Optional[str] = None,
+        include_analytics: bool = False,
+        raw: bool = False,
+    ) -> Union[VolSurfacePoint, Dict[str, Any]]:
+        """Single-point SABR-interpolated implied vol query.
+
+        Parameters
+        ----------
+        ccy:
+            Asset symbol.
+        expiry:
+            Option expiry date, ``YYYY-MM-DD``. Must be in the future
+            relative to the snapshot date.
+        strike_type:
+            How ``strike_value`` is interpreted:
+
+            * ``"strike"`` — absolute strike price (e.g. ``100_000``)
+            * ``"moneyness"`` — K/S ratio (e.g. ``1.0`` for ATM, ``0.9`` for 10% OTM put)
+            * ``"delta"`` — signed/unsigned BS delta magnitude (e.g. ``0.25``)
+        strike_value:
+            The numeric strike, moneyness, or delta — see ``strike_type``.
+        option_type:
+            ``"C"`` (call, default) or ``"P"`` (put). Required when
+            ``strike_type="delta"``; ignored otherwise.
+        session:
+            ``"asia"``, ``"london"``, or ``"us"``. Subject to your plan tier.
+        date:
+            Optional snapshot date (``YYYY-MM-DD``). Defaults to the latest
+            available snapshot.
+        include_analytics:
+            If True, also return spot, forward, yield rate, BS price, and Greeks.
+            Requires a PRO or ULTRA plan.
+        raw:
+            If True, return the parsed JSON dict instead of a typed model.
+        """
+        params = _drop_none({
+            "ccy": ccy,
+            "expiry": expiry,
+            "strike_type": strike_type,
+            "strike_value": strike_value,
+            "option_type": option_type,
+            "session": session,
+            "date": date,
+            "include_analytics": str(include_analytics).lower() if include_analytics else None,
+        })
+        data = self._request("GET", "/v1/vol-surface", params=params)
+        return data if raw else VolSurfacePoint.model_validate(data)
+
+    def vol_surface_bulk(
+        self,
+        ccy: str,
+        queries: List[Dict[str, Any]],
+        *,
+        session: Session = "us",
+        date: Optional[str] = None,
+        raw: bool = False,
+    ) -> Union[BulkVolResponse, Dict[str, Any]]:
+        """Resolve many (expiry, strike) points in a single request.
+
+        Far more efficient than looping over :meth:`vol_surface` — one
+        snapshot is loaded once and reused for every query.
+
+        Parameters
+        ----------
+        ccy:
+            Asset symbol.
+        queries:
+            List of dicts, each with keys:
+
+            * ``expiry`` (str, required) — ``YYYY-MM-DD``
+            * ``strike_type`` (str, required) — ``"strike"``, ``"moneyness"``, or ``"delta"``
+            * ``strike_value`` (float, required)
+            * ``option_type`` (str, optional) — ``"C"`` or ``"P"`` (default ``"C"``)
+            * ``include_analytics`` (bool, optional) — default False
+        session:
+            ``"asia"``, ``"london"``, or ``"us"``.
+        date:
+            Optional snapshot date.
+        raw:
+            If True, return the parsed JSON dict instead of a typed model.
+
+        Example
+        -------
+
+            response = cv.vol_surface_bulk(
+                ccy="BTC",
+                queries=[
+                    {"expiry": "2026-09-26", "strike_type": "moneyness", "strike_value": 0.9},
+                    {"expiry": "2026-09-26", "strike_type": "moneyness", "strike_value": 1.0},
+                    {"expiry": "2026-09-26", "strike_type": "moneyness", "strike_value": 1.1},
+                    {"expiry": "2026-09-26", "strike_type": "delta",
+                     "strike_value": 0.25, "option_type": "C", "include_analytics": True},
+                ],
+            )
+            for item in response.successful:
+                print(item.expiry, item.strike, item.vol)
+        """
+        body = _drop_none({
+            "ccy": ccy,
+            "session": session,
+            "date": date,
+            "queries": queries,
+        })
+        data = self._request("POST", "/v1/vol-surface/bulk", json=body)
+        return data if raw else BulkVolResponse.model_validate(data)
+
+    def vol_history(
+        self,
+        ccy: str = "BTC",
+        tenor: str = "1M",
+        strike_type: Literal["moneyness", "delta"] = "moneyness",
+        strike_value: float = 1.0,
+        *,
+        option_type: OptionType = "C",
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        raw: bool = False,
+    ) -> Union[VolHistoryResponse, Dict[str, Any]]:
+        """Historical time series at a constant maturity and constant strike.
+
+        Ideal for backtesting, regression analysis, and vol regime monitoring.
+
+        Requires a PRO or ULTRA plan (BASIC plans get 403 on this endpoint).
+
+        Parameters
+        ----------
+        ccy:
+            Asset symbol.
+        tenor:
+            Constant-maturity tenor: ``1D``, ``1W``, ``2W``, ``3W``, ``1M``,
+            ``2M``, ``3M``, ``6M``, ``9M``, or ``1Y``.
+        strike_type:
+            ``"moneyness"`` (K/S) or ``"delta"``. Absolute strikes are not
+            supported for history queries.
+        strike_value:
+            Must be a value on the published grid — see the API docs for the
+            full list. Common moneyness points: 0.9, 0.95, 1.0, 1.05, 1.1.
+            Common deltas: 0.10, 0.25.
+        option_type:
+            ``"C"`` or ``"P"``. Required when ``strike_type="delta"``.
+        start_date / end_date:
+            ``YYYY-MM-DD`` bounds. PRO plans are limited to the last year.
+        raw:
+            If True, return the parsed JSON dict instead of a typed model.
+        """
+        params = _drop_none({
+            "ccy": ccy,
+            "tenor": tenor,
+            "strike_type": strike_type,
+            "strike_value": strike_value,
+            "option_type": option_type,
+            "start_date": start_date,
+            "end_date": end_date,
+        })
+        data = self._request("GET", "/v1/vol-history", params=params)
+        return data if raw else VolHistoryResponse.model_validate(data)
+
+    # ── HTTP plumbing ────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Send a request with retries and convert HTTP errors to typed exceptions."""
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, path, params=params, json=json
+                )
+            except httpx.TimeoutException as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise CryptoVolTimeoutError(
+                    f"Request to {path} timed out after {self.timeout}s"
+                ) from e
+            except httpx.HTTPError as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise CryptoVolError(f"Network error calling {path}: {e}") from e
+
+            # Retry 5xx
+            if 500 <= response.status_code < 600 and attempt < self.max_retries:
+                time.sleep(_backoff(attempt))
+                continue
+
+            # Retry 429 with backoff
+            if response.status_code == 429 and attempt < self.max_retries:
+                retry_after = response.headers.get("Retry-After")
+                delay = float(retry_after) if retry_after else _backoff(attempt)
+                time.sleep(delay)
+                continue
+
+            return _handle_response(response)
+
+        # Should be unreachable, but just in case
+        raise CryptoVolError(  # pragma: no cover
+            f"Exhausted retries for {path}: {last_error}"
+        )
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _drop_none(d: Dict[str, Any]) -> Dict[str, Any]:
+    """Strip keys whose value is None so we don't send them as query params."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff: 0.5s, 1s, 2s, 4s..."""
+    return 0.5 * (2 ** attempt)
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    """Raise typed exceptions for error responses; return parsed JSON otherwise."""
+    if response.is_success:
+        try:
+            return response.json()
+        except ValueError as e:
+            raise CryptoVolError(
+                f"Server returned non-JSON response (status {response.status_code})",
+                status_code=response.status_code,
+                response_body=response.text,
+            ) from e
+
+    # Pull a human-readable message out of the body
+    try:
+        body = response.json()
+        message = (
+            body.get("detail")
+            or body.get("error")
+            or body.get("message")
+            or str(body)
+        )
+    except ValueError:
+        body = response.text
+        message = body or response.reason_phrase
+
+    status = response.status_code
+    kwargs = {"status_code": status, "response_body": body}
+
+    if status in (401,):
+        raise AuthenticationError(message, **kwargs)
+    if status == 403:
+        # The API uses 403 for two distinct cases:
+        #   1. Missing/invalid RapidAPI proxy secret  -> AuthenticationError
+        #   2. Plan tier limit violation              -> PlanLimitError
+        # The plan-limit messages all mention "plan" or "Upgrade"; auth ones don't.
+        text = str(message).lower()
+        if "plan" in text or "upgrade" in text or "tier" in text:
+            raise PlanLimitError(message, **kwargs)
+        raise AuthenticationError(message, **kwargs)
+    if status == 404:
+        raise NotFoundError(message, **kwargs)
+    if status in (400, 422):
+        raise ValidationError(message, **kwargs)
+    if status == 429:
+        raise RateLimitError(message, **kwargs)
+    if 500 <= status < 600:
+        raise ServerError(message, **kwargs)
+
+    raise CryptoVolError(message, **kwargs)

cryptovol/exceptions.py

@@ -0,0 +1,64 @@
+"""Exception hierarchy for the CryptoVol SDK.
+
+Catch `CryptoVolError` to handle any API-related failure. Catch a more specific
+subclass when you want to react to a particular condition (e.g. retry on
+rate limits, prompt the user to upgrade on plan-limit errors).
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class CryptoVolError(Exception):
+    """Base exception for all errors raised by the CryptoVol SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        response_body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+
+    def __str__(self) -> str:  # pragma: no cover — trivial
+        if self.status_code is not None:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(CryptoVolError):
+    """Raised on 401 / 403 — invalid or missing API key, or non-allowed origin."""
+
+
+class PlanLimitError(CryptoVolError):
+    """Raised on 403 when the request hits a plan-tier limit.
+
+    Examples: querying ETH on a BASIC plan, requesting Greeks without PRO,
+    querying dates older than your plan's history window.
+
+    The server's error message typically tells you which tier unlocks the feature.
+    """
+
+
+class NotFoundError(CryptoVolError):
+    """Raised on 404 — no data available for the requested asset/date/session."""
+
+
+class ValidationError(CryptoVolError):
+    """Raised on 400 / 422 — malformed parameters (bad ccy, bad date format, etc.)."""
+
+
+class RateLimitError(CryptoVolError):
+    """Raised on 429 — daily/monthly quota exceeded."""
+
+
+class ServerError(CryptoVolError):
+    """Raised on 5xx — transient server-side failure."""
+
+
+class TimeoutError(CryptoVolError):
+    """Raised when a request exceeds the configured timeout."""

cryptovol/models.py

@@ -0,0 +1,194 @@
+"""Typed response models for the CryptoVol API.
+
+All models are Pydantic v2 ``BaseModel`` subclasses, so they give you:
+
+* IDE autocomplete on response fields
+* Runtime validation of types
+* ``.model_dump()`` to round-trip back to plain dicts
+
+If you'd rather work with raw dicts, every client method accepts
+``raw=True`` to skip parsing.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# ── Shared building blocks ────────────────────────────────────────────────────
+
+
+class Greeks(BaseModel):
+    """Black-Scholes Greeks computed at the resolved (K, T, vol) point."""
+
+    model_config = ConfigDict(extra="allow")
+
+    delta: Optional[float] = None
+    gamma: Optional[float] = None
+    vega: Optional[float] = None
+    theta: Optional[float] = None
+
+
+class Analytics(BaseModel):
+    """Spot, forward, rate, BS price, and Greeks (PRO and ULTRA only)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    spot: Optional[float] = None
+    forward: Optional[float] = None
+    yield_rate: Optional[float] = None
+    price: Optional[float] = None
+    greeks: Optional[Greeks] = None
+
+
+# ── /v1/vol-index ─────────────────────────────────────────────────────────────
+
+
+class VolIndexPoint(BaseModel):
+    """One day of the constant-maturity vol index."""
+
+    model_config = ConfigDict(extra="allow")
+
+    date: str
+    vol: float
+
+
+class VolIndexResponse(BaseModel):
+    """Response from ``GET /v1/vol-index``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    ccy: str
+    tenor: str
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+    count: int
+    data: List[VolIndexPoint] = Field(default_factory=list)
+
+    def to_dataframe(self):  # pragma: no cover — optional dep
+        """Convert ``.data`` to a pandas DataFrame indexed by date.
+
+        Requires pandas to be installed (``pip install cryptovol[pandas]``).
+        """
+        try:
+            import pandas as pd
+        except ImportError as e:
+            raise ImportError(
+                "pandas is required for .to_dataframe(). "
+                "Install with: pip install cryptovol[pandas]"
+            ) from e
+        df = pd.DataFrame([p.model_dump() for p in self.data])
+        if not df.empty:
+            df["date"] = pd.to_datetime(df["date"])
+            df = df.set_index("date").sort_index()
+        return df
+
+
+# ── /v1/vol-surface (single point) ────────────────────────────────────────────
+
+
+class VolSurfacePoint(BaseModel):
+    """A single SABR-interpolated vol point on the surface."""
+
+    model_config = ConfigDict(extra="allow")
+
+    ccy: str
+    session: str
+    date: str
+    expiry: str
+    strike_type: str
+    strike_value: float
+    strike: float
+    option_type: Optional[str] = None
+    vol: float
+    analytics: Optional[Analytics] = None
+
+
+# ── /v1/vol-surface/bulk ──────────────────────────────────────────────────────
+
+
+class BulkResultItem(BaseModel):
+    """One item in a bulk response — either a resolved point or an error."""
+
+    model_config = ConfigDict(extra="allow")
+
+    expiry: str
+    strike_type: Optional[str] = None
+    strike_value: Optional[float] = None
+    strike: Optional[float] = None
+    option_type: Optional[str] = None
+    vol: Optional[float] = None
+    analytics: Optional[Analytics] = None
+    error: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        """True if this query resolved successfully (no error field)."""
+        return self.error is None
+
+
+class BulkVolResponse(BaseModel):
+    """Response from ``POST /v1/vol-surface/bulk``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    ccy: str
+    session: str
+    date: str
+    spot: Optional[float] = None
+    count: int
+    results: List[BulkResultItem] = Field(default_factory=list)
+
+    @property
+    def successful(self) -> List[BulkResultItem]:
+        """All bulk results that resolved without error."""
+        return [r for r in self.results if r.ok]
+
+    @property
+    def failed(self) -> List[BulkResultItem]:
+        """All bulk results that came back with an error field."""
+        return [r for r in self.results if not r.ok]
+
+
+# ── /v1/vol-history ───────────────────────────────────────────────────────────
+
+
+class VolHistoryPoint(BaseModel):
+    """One day of constant-maturity, constant-strike historical vol."""
+
+    model_config = ConfigDict(extra="allow")
+
+    date: str
+    vol: float
+
+
+class VolHistoryResponse(BaseModel):
+    """Response from ``GET /v1/vol-history``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    ccy: str
+    tenor: str
+    strike_type: str
+    strike_value: float
+    option_type: Optional[str] = None
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+    count: int
+    data: List[VolHistoryPoint] = Field(default_factory=list)
+
+    def to_dataframe(self):  # pragma: no cover — optional dep
+        """Convert ``.data`` to a pandas DataFrame indexed by date."""
+        try:
+            import pandas as pd
+        except ImportError as e:
+            raise ImportError(
+                "pandas is required for .to_dataframe(). "
+                "Install with: pip install cryptovol[pandas]"
+            ) from e
+        df = pd.DataFrame([p.model_dump() for p in self.data])
+        if not df.empty:
+            df["date"] = pd.to_datetime(df["date"])
+            df = df.set_index("date").sort_index()
+        return df

cryptovol-0.1.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: cryptovol
+Version: 0.1.0
+Summary: Python SDK for the CryptoVol API — institutional-grade crypto implied volatility data.
+Project-URL: Homepage, https://www.cryptovol.io
+Project-URL: Documentation, https://www.cryptovol.io/docs
+Project-URL: Repository, https://github.com/FlyCapital/cryptovol-python
+Project-URL: Issues, https://github.com/FlyCapital/cryptovol-python/issues
+Project-URL: Get an API key, https://www.cryptovol.io/api
+Author-email: CryptoVol <support@cryptovol.io>
+License: MIT
+License-File: LICENSE
+Keywords: bitcoin,crypto,cryptovol,ethereum,implied-volatility,options,quant,sabr,trading,volatility
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.24
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.26; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# cryptovol-python
+
+[![PyPI version](https://img.shields.io/pypi/v/cryptovol.svg)](https://pypi.org/project/cryptovol/)
+[![Python versions](https://img.shields.io/pypi/pyversions/cryptovol.svg)](https://pypi.org/project/cryptovol/)
+[![CI](https://github.com/FlyCapital/cryptovol-python/actions/workflows/ci.yml/badge.svg)](https://github.com/FlyCapital/cryptovol-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-cryptovol.io-blue)](https://www.cryptovol.io/docs)
+
+The official Python SDK for the **[CryptoVol API](https://www.cryptovol.io)** — institutional-grade implied volatility data for crypto options.
+
+> SABR-calibrated surfaces · 3 sessions/day (Asia, London, US) · BTC, ETH, SOL, XRP, AVAX, TRX · Constant-maturity history for backtesting
+
+---
+
+## Install
+
+```bash
+pip install cryptovol
+```
+
+Optional pandas integration (for `.to_dataframe()`):
+
+```bash
+pip install "cryptovol[pandas]"
+```
+
+## Get an API key
+
+Sign up at **[cryptovol.io/api](https://www.cryptovol.io/api)** — BASIC, PRO, and ULTRA tiers are available.
+
+## Quick start
+
+```python
+from cryptovol import CryptoVol
+
+cv = CryptoVol(api_key="YOUR_RAPIDAPI_KEY")
+
+# Daily BTC 30-day implied vol index
+idx = cv.vol_index(ccy="BTC", tenor="30D")
+print(f"Latest BTC 30D IV: {idx.data[-1].vol}%")
+
+# ATM vol for a specific expiry, with Greeks
+pt = cv.vol_surface(
+    ccy="BTC",
+    expiry="2026-12-26",
+    strike_type="moneyness",
+    strike_value=1.0,
+    include_analytics=True,
+)
+print(f"BTC ATM Dec 26: {pt.vol}%  delta={pt.analytics.greeks.delta:.3f}")
+```
+
+That's it. The client is typed end-to-end, so your IDE autocompletes every field.
+
+---
+
+## What you can query
+
+| Method | Endpoint | What it returns |
+|---|---|---|
+| `cv.vol_index(...)` | `GET /v1/vol-index` | Daily IV index time series (CryptoVIX-style) |
+| `cv.vol_surface(...)` | `GET /v1/vol-surface` | One SABR-interpolated vol point |
+| `cv.vol_surface_bulk(...)` | `POST /v1/vol-surface/bulk` | Many points in one round-trip — efficient |
+| `cv.vol_history(...)` | `GET /v1/vol-history` | Constant-maturity historical IV for backtests |
+
+### Strike conventions
+
+`vol_surface` and `vol_surface_bulk` accept three strike types:
+
+- **`"moneyness"`** — `strike_value` is the K/S ratio. `1.0` = ATM, `0.9` = 10% OTM put strike.
+- **`"delta"`** — `strike_value` is the BS delta magnitude. `0.25` with `option_type="C"` gives the 25-delta call strike.
+- **`"strike"`** — `strike_value` is the absolute strike (e.g. `100_000`).
+
+For `"delta"`, the SDK solves K via SABR-interpolated Newton iteration on the surface — same calibration the API serves.
+
+---
+
+## Common recipes
+
+### Plot the BTC 30-day vol index
+
+```python
+import matplotlib.pyplot as plt
+from cryptovol import CryptoVol
+
+cv = CryptoVol(api_key="...")
+df = cv.vol_index(ccy="BTC", tenor="30D",
+                  start_date="2025-01-01", end_date="2026-05-01").to_dataframe()
+
+df["vol"].plot(title="BTC 30D Implied Vol")
+plt.ylabel("IV (%)"); plt.show()
+```
+
+### Reconstruct a vol smile for one expiry
+
+```python
+expiry = "2026-09-26"
+moneyness_grid = [0.7, 0.8, 0.9, 0.95, 1.0, 1.05, 1.1, 1.2, 1.3]
+
+resp = cv.vol_surface_bulk(
+    ccy="BTC",
+    queries=[
+        {"expiry": expiry, "strike_type": "moneyness", "strike_value": m}
+        for m in moneyness_grid
+    ],
+)
+
+for pt in resp.successful:
+    print(f"{pt.strike_value:.2f}x  K={pt.strike:>10,.0f}  vol={pt.vol:.2f}%")
+```
+
+### Build a 25-delta risk-reversal time series
+
+```python
+import pandas as pd
+
+call = cv.vol_history(ccy="BTC", tenor="1M",
+                      strike_type="delta", strike_value=0.25, option_type="C").to_dataframe()
+put  = cv.vol_history(ccy="BTC", tenor="1M",
+                      strike_type="delta", strike_value=0.25, option_type="P").to_dataframe()
+
+rr = call["vol"] - put["vol"]
+rr.plot(title="BTC 1M 25Δ Risk-Reversal")
+```
+
+### Greeks on a 25-delta call
+
+```python
+pt = cv.vol_surface(
+    ccy="BTC", expiry="2026-12-26",
+    strike_type="delta", strike_value=0.25, option_type="C",
+    include_analytics=True,
+)
+g = pt.analytics.greeks
+print(f"K={pt.strike:.0f}  vol={pt.vol:.2f}%  Δ={g.delta:.3f}  Γ={g.gamma:.6f}  V={g.vega:.2f}  Θ={g.theta:.2f}")
+```
+
+---
+
+## Error handling
+
+Every API error becomes a typed exception you can catch precisely:
+
+```python
+from cryptovol import CryptoVol, PlanLimitError, ValidationError, RateLimitError
+
+cv = CryptoVol(api_key="...")
+
+try:
+    cv.vol_history(ccy="ETH", tenor="1M",
+                   strike_type="moneyness", strike_value=1.0)
+except PlanLimitError as e:
+    print(f"Plan limit hit — upgrade needed: {e}")
+except ValidationError as e:
+    print(f"Bad params: {e}")
+except RateLimitError as e:
+    print(f"Slow down: {e}")
+```
+
+Hierarchy:
+
+```
+CryptoVolError                 # base — catch this to handle anything
+├── AuthenticationError        # 401, or 403 without "plan" in the body
+├── PlanLimitError             # 403 — tier blocks asset/session/history/Greeks
+├── NotFoundError              # 404 — no data for that date/session
+├── ValidationError            # 400 / 422 — malformed params
+├── RateLimitError             # 429 — quota exceeded
+├── ServerError                # 5xx
+└── TimeoutError               # request exceeded `timeout`
+```
+
+---
+
+## Configuration
+
+```python
+from cryptovol import CryptoVol
+
+cv = CryptoVol(
+    api_key="...",
+    timeout=30.0,          # per-request timeout (seconds)
+    max_retries=3,         # retries 5xx and 429 with exponential backoff
+    user_agent="my-app/1.2.3",
+)
+
+# Or as a context manager — closes the HTTP client on exit
+with CryptoVol(api_key="...") as cv:
+    idx = cv.vol_index()
+```
+
+### Raw JSON
+
+Every method accepts `raw=True` if you'd rather skip the typed models and work with plain dicts:
+
+```python
+data = cv.vol_index(ccy="BTC", tenor="30D", raw=True)
+# data is just the parsed JSON
+```
+
+---
+
+## Plan tiers (at a glance)
+
+| | BASIC | PRO | ULTRA |
+|---|---|---|---|
+| Assets | BTC | + ETH, SOL | + XRP, AVAX, TRX |
+| Sessions | US | US | Asia, London, US |
+| History window | 30 days | 1 year | Full archive |
+| `vol_history` endpoint | — | ✓ | ✓ |
+| Greeks / analytics | — | ✓ | ✓ |
+| Quota | 500/month | 70k/day | 100k/day |
+
+Hitting a limit raises `PlanLimitError` — the message tells you which tier unlocks it. Full details at **[cryptovol.io/api](https://www.cryptovol.io/api)**.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/FlyCapital/cryptovol-python.git
+cd cryptovol-python
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## Links
+
+- **API docs:** https://www.cryptovol.io/docs
+- **Methodology:** https://www.cryptovol.io/methodology
+- **Research / blog:** https://www.cryptovol.io/blog
+- **Get an API key:** https://www.cryptovol.io/api
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

cryptovol-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cryptovol/__init__.py,sha256=LqRvvmaf3bZFSLqorZJmPp00Vx0pB4AJjmfik3FeOcM,1211
+cryptovol/client.py,sha256=P7br4NcRQeJTFRosGe861A5wWI4oXcslFAAx-iJzsag,15803
+cryptovol/exceptions.py,sha256=y9yZOyHtj6rKFgTqxJargNWzxIiVYNflKD72S__vM8k,1953
+cryptovol/models.py,sha256=a7oJJA9PiSw8SM6lRe3LhusJ_bynRgHOaJDgKY9PJEM,5978
+cryptovol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cryptovol-0.1.0.dist-info/METADATA,sha256=f4gwlQ1sKNy4H9oI9tv1QMNeXY-17YcuJCs_ad4UvlA,8845
+cryptovol-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cryptovol-0.1.0.dist-info/licenses/LICENSE,sha256=FMzcu41qarAz1usGqXROQXOillPMTqyoIOcECW94RMg,1066
+cryptovol-0.1.0.dist-info/RECORD,,

cryptovol-0.1.0.dist-info/WHEEL

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

cryptovol-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CryptoVol
+
+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.