Add vol_surface_raw() for GET /v1/vol-surface/raw (v0.4.0)

New client method + RawVolSurface/RawSurfaceExpiry models for the public
raw market-quoted surface endpoint (strikes[] + mkt_vol[] per listed expiry,
no SABR params). README method table + version bumped to 0.4.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FlyCapital

README.md

@@ -61,6 +61,7 @@ That's it. The client is typed end-to-end, so your IDE autocompletes every field
 | `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_surface_raw(...)` | `GET /v1/vol-surface/raw` | Raw market-quoted surface (strike ladders, pre-fit) — PRO and ULTRA |
 | `cv.vol_history(...)` | `GET /v1/vol-history` | Constant-maturity historical IV for backtests |
 | `cv.spot_history(...)` | `GET /v1/spot-history` | Daily spot price time series per session |
 | `cv.realized_vol(...)` | `GET /v1/realized-vol` | Rolling annualized RV (√365) from spot log-returns |

cryptovol/__init__.py

@@ -27,6 +27,8 @@
     BulkResultItem,
     BulkVolResponse,
     Greeks,
+    RawSurfaceExpiry,
+    RawVolSurface,
     RealizedVolPoint,
     RealizedVolResponse,
     SpotHistoryPoint,
@@ -38,7 +40,7 @@
     VolSurfacePoint,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "CryptoVol",
@@ -59,6 +61,8 @@
     "VolSurfacePoint",
     "BulkVolResponse",
     "BulkResultItem",
+    "RawVolSurface",
+    "RawSurfaceExpiry",
     "VolHistoryResponse",
     "VolHistoryPoint",
     "SpotHistoryResponse",

cryptovol/client.py

@@ -38,6 +38,7 @@
 )
 from .models import (
     BulkVolResponse,
+    RawVolSurface,
     RealizedVolResponse,
     SpotHistoryResponse,
     VolHistoryResponse,
@@ -48,7 +49,7 @@
 DEFAULT_BASE_URL = "https://cryptovol-api-nbakzshi6q-uc.a.run.app"
 DEFAULT_TIMEOUT = 30.0
 DEFAULT_MAX_RETRIES = 3
-DEFAULT_USER_AGENT = "cryptovol-python/0.3.0"
+DEFAULT_USER_AGENT = "cryptovol-python/0.4.0"
 
 StrikeType = Literal["strike", "moneyness", "delta"]
 OptionType = Literal["C", "P"]
@@ -272,6 +273,50 @@ def vol_surface_bulk(
         data = self._request("POST", "/v1/vol-surface/bulk", json=body)
         return data if raw else BulkVolResponse.model_validate(data)
 
+    def vol_surface_raw(
+        self,
+        ccy: str,
+        *,
+        session: Session = "us",
+        date: Optional[str] = None,
+        raw: bool = False,
+    ) -> Union[RawVolSurface, Dict[str, Any]]:
+        """Raw market-quoted vol surface for one snapshot (PRO and ULTRA).
+
+        Returns every listed expiry with its quoted strike ladder
+        (``strikes``) and the market implied vol at each strike
+        (``mkt_vol``, index-aligned), plus ``forward``, ``atm_strike``, and
+        ``spot``. This is the discrete market data *before* model fitting —
+        for a smooth interpolated vol at an arbitrary strike/moneyness/delta
+        use :meth:`vol_surface` or :meth:`vol_surface_bulk`.
+
+        Parameters
+        ----------
+        ccy:
+            Asset symbol.
+        session:
+            ``"asia"``, ``"london"``, or ``"us"``. Subject to your plan tier.
+        date:
+            Optional snapshot date (``YYYY-MM-DD``). Defaults to the latest
+            available snapshot.
+        raw:
+            If True, return the parsed JSON dict instead of a typed model.
+
+        Example
+        -------
+
+            surf = cv.vol_surface_raw(ccy="BTC", session="us")
+            for exp in surf.expiries:
+                print(exp.expiry, exp.forward, len(exp.strikes), "strikes")
+        """
+        params = _drop_none({
+            "ccy": ccy,
+            "session": session,
+            "date": date,
+        })
+        data = self._request("GET", "/v1/vol-surface/raw", params=params)
+        return data if raw else RawVolSurface.model_validate(data)
+
     def vol_history(
         self,
         ccy: str = "BTC",

cryptovol/models.py

@@ -151,6 +151,37 @@ def failed(self) -> List[BulkResultItem]:
         return [r for r in self.results if not r.ok]
 
 
+# ── /v1/vol-surface/raw ───────────────────────────────────────────────────────
+
+
+class RawSurfaceExpiry(BaseModel):
+    """Market-quoted vols for one listed expiry: index-aligned ``strikes``/``mkt_vol``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    expiry: str
+    tenor_days: Optional[int] = None
+    forward: Optional[float] = None
+    atm_strike: Optional[float] = None
+    strikes: List[float] = Field(default_factory=list)
+    mkt_vol: List[float] = Field(default_factory=list)
+
+
+class RawVolSurface(BaseModel):
+    """Response from ``GET /v1/vol-surface/raw`` — raw market-quoted surface
+    (discrete strike ladders, before model fitting)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    ccy: str
+    session: str
+    datetime: Optional[str] = None
+    vol_date: str
+    spot: Optional[float] = None
+    count: int
+    expiries: List[RawSurfaceExpiry] = Field(default_factory=list)
+
+
 # ── /v1/vol-history ───────────────────────────────────────────────────────────
 
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cryptovol"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python SDK for the CryptoVol API — institutional-grade crypto implied volatility data."
 readme = "README.md"
 requires-python = ">=3.9"