cryptovol 0.1.0__tar.gz

cryptovol-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report unexpected SDK behavior
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal repro
+      description: A short code snippet we can run. **Do not include your API key.**
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: error
+    attributes:
+      label: Full traceback / error
+      render: shell
+
+  - type: input
+    id: version
+    attributes:
+      label: cryptovol version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.1"
+    validations:
+      required: true

cryptovol-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Suggest a new feature or improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you like the SDK to behave? Example code snippets are great.
+      render: python
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

cryptovol-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+# Summary
+
+<!-- What does this PR change and why? -->
+
+# Checklist
+
+- [ ] Tests added or updated
+- [ ] `ruff check cryptovol tests` passes
+- [ ] `pytest` passes
+- [ ] CHANGELOG.md updated under `## [Unreleased]`

cryptovol-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: ruff check cryptovol tests
+
+      - name: Test
+        run: pytest --cov=cryptovol --cov-report=term-missing

cryptovol-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write   # mkdocs gh-deploy pushes to gh-pages branch
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: pip install -e ".[docs]"
+      - name: Build & deploy
+        run: mkdocs gh-deploy --force

cryptovol-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: python -m pip install --upgrade build
+      - name: Build sdist + wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    # PyPI Trusted Publishing — configure at https://pypi.org/manage/account/publishing/
+    # See https://docs.pypi.org/trusted-publishers/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cryptovol-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# MkDocs
+site/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Secrets — never commit
+.env
+.envrc
+*.key

cryptovol-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-16
+
+### Added
+- Initial release.
+- `CryptoVol` synchronous client with `vol_index`, `vol_surface`, `vol_surface_bulk`, `vol_history`.
+- Typed Pydantic v2 response models with `.to_dataframe()` helpers (optional `[pandas]` extra).
+- Exception hierarchy: `AuthenticationError`, `PlanLimitError`, `NotFoundError`, `ValidationError`, `RateLimitError`, `ServerError`, `TimeoutError`.
+- Automatic retries with exponential backoff for 5xx and 429.
+- Examples in `examples/` covering smile reconstruction, vol-index plotting, risk-reversals, and Greeks.

cryptovol-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thanks for your interest in improving `cryptovol-python`! Bug reports, docs fixes, and feature PRs are all welcome.
+
+## Set up
+
+```bash
+git clone https://github.com/FlyCapital/cryptovol-python.git
+cd cryptovol-python
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,docs]"
+```
+
+## Run the test suite
+
+```bash
+pytest                # all tests
+pytest --cov          # with coverage
+ruff check cryptovol  # lint
+```
+
+The default test suite uses `pytest-httpx` and runs entirely offline — no API key required.
+
+## Build the docs locally
+
+```bash
+mkdocs serve
+# open http://127.0.0.1:8000
+```
+
+## Submitting a PR
+
+1. Open an issue first for non-trivial changes so we can align on scope.
+2. Add or update tests covering your change.
+3. Run `ruff check cryptovol` and `pytest` before pushing.
+4. Update `CHANGELOG.md` under an `## [Unreleased]` heading.
+
+## Reporting bugs
+
+Please include:
+
+- A minimal repro snippet (omit your API key).
+- The full traceback / error message.
+- `python --version`, `cryptovol.__version__`.

cryptovol-0.1.0/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.

cryptovol-0.1.0/PKG-INFO

@@ -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).