cryptoetf 1.0.0__tar.gz

cryptoetf-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+dist/
+.venv/

cryptoetf-1.0.0/LICENSE

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

cryptoetf-1.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: cryptoetf
+Version: 1.0.0
+Summary: Official Python client for the CryptoETF API: daily net flows of US spot crypto ETFs for 16 assets (BTC, ETH, SOL, XRP, HYPE, DOGE, LINK, AVAX, HBAR, LTC, BNB, DOT, SUI, NEAR, TRX, ZEC), fund by fund, plus fund AUM, the CEFI sentiment index and coin prices. Zero dependencies.
+Project-URL: Homepage, https://cryptoetf.today/en/api
+Project-URL: Documentation, https://docs.cryptoetf.today
+Project-URL: Source, https://github.com/zerosix-studio/cryptoetf-sdk
+Project-URL: Issues, https://github.com/zerosix-studio/cryptoetf-sdk/issues
+Author: cryptoetf.today
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bitcoin-etf,crypto,etf,etf-flows,ethereum-etf,ibit,sdk,spot-etf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# CryptoETF — Python SDK for spot crypto ETF flows
+
+[![PyPI](https://img.shields.io/pypi/v/cryptoetf?color=3775a9&logo=pypi&logoColor=white)](https://pypi.org/project/cryptoetf/)
+
+The official client for the [CryptoETF API](https://docs.cryptoetf.today): daily net
+flows of every US-listed spot crypto ETF, fund by fund, plus fund AUM, the CEFI
+sentiment index and coin prices. Data by [cryptoetf.today](https://cryptoetf.today).
+
+Sixteen assets: **BTC, ETH, SOL, XRP, HYPE, DOGE, LINK, AVAX, HBAR, LTC, BNB,
+DOT, SUI, NEAR, TRX, ZEC**. Zero dependencies (standard library only), typed,
+Python 3.9+.
+
+## Install
+
+```bash
+pip install cryptoetf
+```
+
+## Get an API key
+
+Sign in at [cryptoetf.today](https://cryptoetf.today/en/profile) and create a key
+in **Profile → For developers**. It is free.
+
+## Quick start
+
+```python
+from cryptoetf import CryptoETF
+
+etf = CryptoETF(api_key="...")  # or set CRYPTOETF_API_KEY
+
+# Latest daily net flow for every asset, US$ millions
+for a in etf.flows.summary()["assets"]:
+    print(a["symbol"], a["date"], a["netFlowUsdM"])
+
+# Bitcoin ETFs fund by fund
+btc = etf.flows.funds("btc")
+last_day = btc["days"][-1]
+print([(f["ticker"], f["netFlowUsdM"]) for f in last_day["funds"]])
+```
+
+Responses are plain dicts with the same field names as the API, so they drop
+straight into pandas:
+
+```python
+import pandas as pd
+
+df = pd.DataFrame(etf.flows.asset("eth")["days"])
+```
+
+## Methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `flows.summary()` | `GET /v1/flows/summary` | Latest net flow per asset |
+| `flows.asset(asset)` | `GET /v1/flows/{asset}` | Daily net flows of one asset |
+| `flows.funds(asset)` | `GET /v1/flows/{asset}/funds` | Daily net flows of one asset, per fund |
+| `funds(asset=None)` | `GET /v1/funds` | Fund directory with AUM, fees, coins held |
+| `cefi()` | `GET /v1/index/cefi` | CEFI sentiment index (0–100) and its history |
+| `tickers()` | `GET /v1/tickers` | Tracked assets |
+| `prices()` | `GET /v1/prices` | Spot prices of the 16 coins |
+| `weekly()` | `GET /v1/analytics/weekly` | Seven-day totals per asset |
+
+`asset` is a code such as `btc`, `eth`, `sol`, `hype` or a full name such as
+`bitcoin`. All values are net US$ millions: positive = inflow, negative = outflow.
+Full field reference: [docs.cryptoetf.today](https://docs.cryptoetf.today).
+
+## Errors and limits
+
+Every failed call raises `CryptoETFError` with `status`, an optional `code` and,
+on HTTP 429, `retry_after` in seconds:
+
+```python
+from cryptoetf import CryptoETFError
+
+try:
+    etf.prices()
+except CryptoETFError as e:
+    if e.status == 429:
+        print(f"rate limited, retry in {e.retry_after}s")
+```
+
+- **Rate limit:** 120 requests per minute per key. The latest limit headers are
+  available as `etf.rate_limit`.
+- **History:** the free tier covers the **last 30 days**. Full history will be
+  available on a paid plan.
+- **Freshness:** a trading day appears the next morning (UTC), before the US
+  open. The newest day can be revised once later that day. SUI funds arrive a
+  day later.
+
+## Options
+
+```python
+CryptoETF(
+    api_key="...",          # default: CRYPTOETF_API_KEY
+    timeout=15.0,           # seconds per request
+    base_url="https://api.cryptoetf.today/api/v1",
+)
+```
+
+## Related
+
+- **TypeScript SDK:** [@zerosix-studio/cryptoetf](https://www.npmjs.com/package/@zerosix-studio/cryptoetf)
+- **No-code access for AI agents:** the hosted MCP server at
+  `https://mcp.cryptoetf.today/api/mcp`
+- **Embeddable widgets:** [cryptoetf.today/en/crypto-etf-widgets](https://cryptoetf.today/en/crypto-etf-widgets)
+
+Not investment advice. MIT licensed.

cryptoetf-1.0.0/README.md

@@ -0,0 +1,107 @@
+# CryptoETF — Python SDK for spot crypto ETF flows
+
+[![PyPI](https://img.shields.io/pypi/v/cryptoetf?color=3775a9&logo=pypi&logoColor=white)](https://pypi.org/project/cryptoetf/)
+
+The official client for the [CryptoETF API](https://docs.cryptoetf.today): daily net
+flows of every US-listed spot crypto ETF, fund by fund, plus fund AUM, the CEFI
+sentiment index and coin prices. Data by [cryptoetf.today](https://cryptoetf.today).
+
+Sixteen assets: **BTC, ETH, SOL, XRP, HYPE, DOGE, LINK, AVAX, HBAR, LTC, BNB,
+DOT, SUI, NEAR, TRX, ZEC**. Zero dependencies (standard library only), typed,
+Python 3.9+.
+
+## Install
+
+```bash
+pip install cryptoetf
+```
+
+## Get an API key
+
+Sign in at [cryptoetf.today](https://cryptoetf.today/en/profile) and create a key
+in **Profile → For developers**. It is free.
+
+## Quick start
+
+```python
+from cryptoetf import CryptoETF
+
+etf = CryptoETF(api_key="...")  # or set CRYPTOETF_API_KEY
+
+# Latest daily net flow for every asset, US$ millions
+for a in etf.flows.summary()["assets"]:
+    print(a["symbol"], a["date"], a["netFlowUsdM"])
+
+# Bitcoin ETFs fund by fund
+btc = etf.flows.funds("btc")
+last_day = btc["days"][-1]
+print([(f["ticker"], f["netFlowUsdM"]) for f in last_day["funds"]])
+```
+
+Responses are plain dicts with the same field names as the API, so they drop
+straight into pandas:
+
+```python
+import pandas as pd
+
+df = pd.DataFrame(etf.flows.asset("eth")["days"])
+```
+
+## Methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `flows.summary()` | `GET /v1/flows/summary` | Latest net flow per asset |
+| `flows.asset(asset)` | `GET /v1/flows/{asset}` | Daily net flows of one asset |
+| `flows.funds(asset)` | `GET /v1/flows/{asset}/funds` | Daily net flows of one asset, per fund |
+| `funds(asset=None)` | `GET /v1/funds` | Fund directory with AUM, fees, coins held |
+| `cefi()` | `GET /v1/index/cefi` | CEFI sentiment index (0–100) and its history |
+| `tickers()` | `GET /v1/tickers` | Tracked assets |
+| `prices()` | `GET /v1/prices` | Spot prices of the 16 coins |
+| `weekly()` | `GET /v1/analytics/weekly` | Seven-day totals per asset |
+
+`asset` is a code such as `btc`, `eth`, `sol`, `hype` or a full name such as
+`bitcoin`. All values are net US$ millions: positive = inflow, negative = outflow.
+Full field reference: [docs.cryptoetf.today](https://docs.cryptoetf.today).
+
+## Errors and limits
+
+Every failed call raises `CryptoETFError` with `status`, an optional `code` and,
+on HTTP 429, `retry_after` in seconds:
+
+```python
+from cryptoetf import CryptoETFError
+
+try:
+    etf.prices()
+except CryptoETFError as e:
+    if e.status == 429:
+        print(f"rate limited, retry in {e.retry_after}s")
+```
+
+- **Rate limit:** 120 requests per minute per key. The latest limit headers are
+  available as `etf.rate_limit`.
+- **History:** the free tier covers the **last 30 days**. Full history will be
+  available on a paid plan.
+- **Freshness:** a trading day appears the next morning (UTC), before the US
+  open. The newest day can be revised once later that day. SUI funds arrive a
+  day later.
+
+## Options
+
+```python
+CryptoETF(
+    api_key="...",          # default: CRYPTOETF_API_KEY
+    timeout=15.0,           # seconds per request
+    base_url="https://api.cryptoetf.today/api/v1",
+)
+```
+
+## Related
+
+- **TypeScript SDK:** [@zerosix-studio/cryptoetf](https://www.npmjs.com/package/@zerosix-studio/cryptoetf)
+- **No-code access for AI agents:** the hosted MCP server at
+  `https://mcp.cryptoetf.today/api/mcp`
+- **Embeddable widgets:** [cryptoetf.today/en/crypto-etf-widgets](https://cryptoetf.today/en/crypto-etf-widgets)
+
+Not investment advice. MIT licensed.

cryptoetf-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cryptoetf"
+dynamic = ["version"]
+description = "Official Python client for the CryptoETF API: daily net flows of US spot crypto ETFs for 16 assets (BTC, ETH, SOL, XRP, HYPE, DOGE, LINK, AVAX, HBAR, LTC, BNB, DOT, SUI, NEAR, TRX, ZEC), fund by fund, plus fund AUM, the CEFI sentiment index and coin prices. Zero dependencies."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "cryptoetf.today" }]
+requires-python = ">=3.9"
+keywords = ["crypto", "etf", "bitcoin-etf", "ethereum-etf", "etf-flows", "spot-etf", "ibit", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://cryptoetf.today/en/api"
+Documentation = "https://docs.cryptoetf.today"
+Source = "https://github.com/zerosix-studio/cryptoetf-sdk"
+Issues = "https://github.com/zerosix-studio/cryptoetf-sdk/issues"
+
+[tool.hatch.version]
+path = "src/cryptoetf/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cryptoetf"]

cryptoetf-1.0.0/src/cryptoetf/__init__.py

@@ -0,0 +1,7 @@
+"""Official Python client for the CryptoETF API — daily net flows of US spot crypto ETFs."""
+
+__version__ = "1.0.0"
+
+from .client import DEFAULT_BASE_URL, CryptoETF, CryptoETFError  # noqa: E402
+
+__all__ = ["CryptoETF", "CryptoETFError", "DEFAULT_BASE_URL", "__version__"]

cryptoetf-1.0.0/src/cryptoetf/client.py

@@ -0,0 +1,170 @@
+"""Client for the CryptoETF public API v1."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional, cast
+
+from . import __version__
+from .types import (
+    AssetFlows,
+    AssetFundFlows,
+    CefiIndex,
+    FlowsSummary,
+    Funds,
+    Prices,
+    RateLimit,
+    Ticker,
+    WeeklyAnalytics,
+)
+
+DEFAULT_BASE_URL = "https://api.cryptoetf.today/api/v1"
+KEY_HELP = (
+    "API key required. Get a free key at https://cryptoetf.today/en/profile "
+    "and pass CryptoETF(api_key=...) or set CRYPTOETF_API_KEY."
+)
+
+# (url, headers, timeout) -> (status, headers, body). Swappable for tests and proxies.
+Transport = Callable[[str, Dict[str, str], float], "tuple[int, Dict[str, str], bytes]"]
+
+
+class CryptoETFError(Exception):
+    """Error returned by the API (4xx/5xx) or raised by the client (timeout, network).
+
+    ``status`` is 0 for network errors and timeouts. ``code`` is a machine-readable
+    code when the API sends one (e.g. ``api_key_suspended``). ``retry_after`` is the
+    number of seconds to wait on HTTP 429.
+    """
+
+    def __init__(self, message: str, status: int, code: Optional[str] = None, retry_after: Optional[int] = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+
+
+def _urllib_transport(url: str, headers: Dict[str, str], timeout: float) -> "tuple[int, Dict[str, str], bytes]":
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return res.status, {k.lower(): v for k, v in res.headers.items()}, res.read()
+    except urllib.error.HTTPError as err:
+        with err:
+            return err.code, {k.lower(): v for k, v in err.headers.items()}, err.read()
+    except (socket.timeout, TimeoutError):
+        raise CryptoETFError(f"Request timed out after {timeout} s", 0) from None
+    except urllib.error.URLError as err:
+        raise CryptoETFError(f"Network error: {err.reason}", 0) from None
+
+
+class _Flows:
+    def __init__(self, client: "CryptoETF"):
+        self._c = client
+
+    def summary(self) -> FlowsSummary:
+        """Latest daily net flow for every asset."""
+        return cast(FlowsSummary, self._c._get("/flows/summary"))
+
+    def asset(self, asset: str) -> AssetFlows:
+        """Daily net flows of one asset over the history window (30 days on the free tier)."""
+        return cast(AssetFlows, self._c._get(f"/flows/{urllib.parse.quote(asset, safe='')}"))
+
+    def funds(self, asset: str) -> AssetFundFlows:
+        """Daily net flows of one asset, fund by fund."""
+        return cast(AssetFundFlows, self._c._get(f"/flows/{urllib.parse.quote(asset, safe='')}/funds"))
+
+
+class CryptoETF:
+    """Daily net flows of US spot crypto ETFs for 16 assets, fund by fund, plus
+    fund AUM, the CEFI sentiment index and coin prices.
+
+    >>> etf = CryptoETF(api_key="...")
+    >>> etf.flows.summary()["assets"][0]["symbol"]
+    'BTC'
+
+    ``asset`` arguments take a code (``btc``, ``eth``, ``sol``, ``hype``…) or a full
+    name (``bitcoin``). Values are net US$ millions: positive = inflow.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+        transport: Optional[Transport] = None,
+    ):
+        key = api_key or os.environ.get("CRYPTOETF_API_KEY")
+        if not key:
+            raise CryptoETFError(KEY_HELP, 401)
+        self._key = key
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+        self._transport = transport or _urllib_transport
+        #: Rate-limit headers of the most recent response, or None before the first call.
+        self.rate_limit: Optional[RateLimit] = None
+        #: Daily net flows: ``summary()``, ``asset(asset)``, ``funds(asset)``.
+        self.flows = _Flows(self)
+
+    def funds(self, asset: Optional[str] = None) -> Funds:
+        """Fund directory with assets under management; all 16 assets unless ``asset`` is given."""
+        return cast(Funds, self._get("/funds", {"asset": asset} if asset else None))
+
+    def cefi(self) -> CefiIndex:
+        """CEFI — Crypto ETF Flow Index, a 0–100 sentiment gauge, with its recent history."""
+        return cast(CefiIndex, self._get("/index/cefi"))
+
+    def tickers(self) -> List[Ticker]:
+        """Assets the API tracks."""
+        return cast(List[Ticker], self._get("/tickers"))
+
+    def prices(self) -> Prices:
+        """Spot prices of the 16 coins."""
+        return cast(Prices, self._get("/prices"))
+
+    def weekly(self) -> WeeklyAnalytics:
+        """Seven-day flow totals per asset."""
+        return cast(WeeklyAnalytics, self._get("/analytics/weekly"))
+
+    def _get(self, path: str, query: Optional[Dict[str, str]] = None) -> Any:
+        url = self._base + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        headers = {
+            "Authorization": f"Bearer {self._key}",
+            "Accept": "application/json",
+            "User-Agent": f"cryptoetf-python/{__version__}",
+        }
+        status, res_headers, raw = self._transport(url, headers, self._timeout)
+
+        if res_headers.get("x-ratelimit-limit"):
+            self.rate_limit = {
+                "limit": int(res_headers["x-ratelimit-limit"]),
+                "remaining": int(res_headers.get("x-ratelimit-remaining", 0)),
+                "reset": int(res_headers.get("x-ratelimit-reset", 0)),
+            }
+
+        try:
+            body = json.loads(raw) if raw else None
+        except ValueError:
+            body = None
+
+        if status >= 400:
+            b = body if isinstance(body, dict) else {}
+            msg = b.get("message")
+            if isinstance(msg, list):
+                msg = "; ".join(str(m) for m in msg)
+            retry = res_headers.get("retry-after")
+            raise CryptoETFError(
+                msg if isinstance(msg, str) else f"HTTP {status}",
+                status,
+                b.get("code") if isinstance(b.get("code"), str) else None,
+                int(retry) if retry and retry.isdigit() else None,
+            )
+        return body

cryptoetf-1.0.0/src/cryptoetf/types.py

@@ -0,0 +1,143 @@
+"""Response shapes of the CryptoETF public API v1 (https://docs.cryptoetf.today).
+
+Flow values are net US$ millions, rounded to one decimal: positive = inflow,
+negative = outflow. Dates are ``YYYY-MM-DD`` (UTC trading days), timestamps ISO 8601.
+Responses are plain dicts; these TypedDicts only describe them for type checkers.
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal, Optional, TypedDict
+
+
+class FlowsSummaryItem(TypedDict):
+    symbol: str
+    asset: str
+    date: Optional[str]
+    netFlowUsdM: float
+
+
+class FlowsSummary(TypedDict):
+    assets: List[FlowsSummaryItem]
+    updatedAt: str
+
+
+class FlowPoint(TypedDict):
+    date: str
+    netFlowUsdM: float
+
+
+class AssetFlows(TypedDict):
+    symbol: str
+    asset: str
+    windowDays: int
+    days: List[FlowPoint]
+    updatedAt: str
+
+
+class FundFlow(TypedDict):
+    ticker: str
+    issuer: str
+    netFlowUsdM: Optional[float]
+
+
+class FundDay(TypedDict):
+    date: str
+    totalUsdM: float
+    funds: List[FundFlow]
+
+
+class AssetFundFlows(TypedDict):
+    symbol: str
+    asset: str
+    windowDays: int
+    days: List[FundDay]
+    updatedAt: str
+
+
+class AssetNetAssets(TypedDict):
+    symbol: str
+    asset: str
+    totalNetAssetsUsdM: Optional[float]
+    date: Optional[str]
+
+
+class Fund(TypedDict):
+    ticker: str
+    name: str
+    issuer: str
+    symbol: str
+    asset: str
+    exchange: str
+    listedAt: str
+    sponsorFeePct: Optional[float]
+    netAssetsUsdM: Optional[float]
+    coinsHeld: Optional[float]
+    coinsHeldDate: Optional[str]
+    netAssetsDate: Optional[str]
+    netAssetsBasis: Optional[Literal["reported", "repriced", "estimated"]]
+
+
+class Funds(TypedDict):
+    assets: List[AssetNetAssets]
+    funds: List[Fund]
+    updatedAt: str
+
+
+class CefiComponents(TypedDict):
+    flow: float
+    trend: float
+    breadth: float
+
+
+class IndexPoint(TypedDict):
+    date: str
+    value: float
+
+
+class CefiIndex(TypedDict):
+    index: str
+    current: float
+    components: Optional[CefiComponents]
+    date: str
+    windowDays: int
+    history: List[IndexPoint]
+
+
+class Ticker(TypedDict):
+    symbol: str
+    asset: str
+    name: str
+
+
+class Price(TypedDict):
+    symbol: str
+    priceUsd: float
+    change24hPct: float
+
+
+class Prices(TypedDict):
+    prices: List[Price]
+    updatedAt: str
+
+
+class WeeklyAsset(TypedDict):
+    symbol: str
+    asset: str
+    netFlowUsdM: float
+    avgDailyUsdM: float
+    positiveDays: int
+    negativeDays: int
+
+
+# "from" is a Python keyword, so this one needs the functional TypedDict form.
+WeeklyAnalytics = TypedDict(
+    "WeeklyAnalytics",
+    {"from": str, "to": str, "assets": List[WeeklyAsset]},
+)
+
+
+class RateLimit(TypedDict):
+    limit: int
+    remaining: int
+    reset: int

cryptoetf-1.0.0/tests/test_client.py

@@ -0,0 +1,69 @@
+import json
+import os
+import unittest
+
+from cryptoetf import CryptoETF, CryptoETFError
+
+
+def fake(status, body, headers=None):
+    calls = []
+
+    def transport(url, hdrs, timeout):
+        calls.append((url, hdrs))
+        return status, {k.lower(): v for k, v in (headers or {}).items()}, json.dumps(body).encode()
+
+    transport.calls = calls
+    return transport
+
+
+class ClientTest(unittest.TestCase):
+    def test_requires_key(self):
+        saved = os.environ.pop("CRYPTOETF_API_KEY", None)
+        try:
+            with self.assertRaises(CryptoETFError) as ctx:
+                CryptoETF()
+            self.assertIn("cryptoetf.today/en/profile", ctx.exception.message)
+        finally:
+            if saved:
+                os.environ["CRYPTOETF_API_KEY"] = saved
+
+    def test_paths_headers_rate_limit(self):
+        t = fake(200, {"symbol": "BTC", "days": []}, {
+            "X-RateLimit-Limit": "120", "X-RateLimit-Remaining": "119", "X-RateLimit-Reset": "1700000000",
+        })
+        etf = CryptoETF("k1", base_url="https://example.test/api/v1/", transport=t)
+        self.assertEqual(etf.flows.funds("btc")["symbol"], "BTC")
+        self.assertEqual(t.calls[0][0], "https://example.test/api/v1/flows/btc/funds")
+        self.assertEqual(t.calls[0][1]["Authorization"], "Bearer k1")
+        self.assertEqual(etf.rate_limit, {"limit": 120, "remaining": 119, "reset": 1700000000})
+        etf.funds("sol")
+        self.assertEqual(t.calls[1][0], "https://example.test/api/v1/funds?asset=sol")
+        etf.funds()
+        self.assertEqual(t.calls[2][0], "https://example.test/api/v1/funds")
+
+    def test_errors(self):
+        etf = CryptoETF("k", transport=fake(429, {"statusCode": 429, "message": "Slow down"}, {"Retry-After": "12"}))
+        with self.assertRaises(CryptoETFError) as ctx:
+            etf.prices()
+        self.assertEqual((ctx.exception.status, ctx.exception.retry_after, ctx.exception.message), (429, 12, "Slow down"))
+
+        etf2 = CryptoETF("k", transport=fake(403, {"statusCode": 403, "code": "api_key_suspended", "message": "Suspended"}))
+        with self.assertRaises(CryptoETFError) as ctx:
+            etf2.cefi()
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (403, "api_key_suspended"))
+
+    @unittest.skipIf(os.environ.get("CRYPTOETF_OFFLINE") == "1", "offline")
+    def test_live_bad_key(self):
+        with self.assertRaises(CryptoETFError) as ctx:
+            CryptoETF("invalid-key-for-sdk-test").flows.summary()
+        self.assertEqual(ctx.exception.status, 401)
+
+    @unittest.skipUnless(os.environ.get("CRYPTOETF_API_KEY"), "no CRYPTOETF_API_KEY")
+    def test_live_real_key(self):
+        etf = CryptoETF()
+        self.assertGreaterEqual(len(etf.flows.summary()["assets"]), 16)
+        self.assertTrue(any(t["symbol"] == "BTC" for t in etf.tickers()))
+
+
+if __name__ == "__main__":
+    unittest.main()