deeptick 0.1.0__tar.gz

deeptick-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Data (large Parquet files — don't commit)
+data/
+*.parquet
+*.sqlite3
+*.sqlite3-*
+
+# Logs
+*.log
+
+# Environment
+.env
+.env.local
+
+# JavaScript / Next.js
+node_modules/
+.next/
+web/node_modules/
+web/.next/
+web/out/
+web/.env*.local
+*.tsbuildinfo
+
+# Rust build output
+client-rs/target/
+
+# Local visual test artifacts
+output/playwright/
+
+# Terraform local working directories
+.terraform/
+**/.terraform/
+*.tfstate
+*.tfstate.*
+
+# Operational artifacts with expiring signed URLs
+reports/sample-links-*.md
+reports/collector-symbol-status-*.json
+reports/collector-symbol-status-*.md
+reports/hyperliquid-12h-sample-*.md
+reports/options-10m-samples-*.md
+dist-sdk/
+.feature-credentials.env
+
+# Rust build output (sdk copy; client-rs/target already ignored above)
+sdk/rust/target/
+# Shadow-gate run outputs (host cron writes these; history lives in S3/logs)
+reports/shadow-gate-*

deeptick-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.5
+Name: deeptick
+Version: 0.1.0
+Summary: DeepTick Python SDK for authenticated market data downloads
+Project-URL: Homepage, https://deeptick.lacertalabs.xyz
+Project-URL: Repository, https://github.com/deeptick/deeptick
+Project-URL: Documentation, https://deeptick.lacertalabs.xyz/docs
+Author: DeepTick
+License: MIT
+Keywords: crypto,deeptick,market-data,parquet,pyarrow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: pyarrow>=17.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DeepTick Python SDK
+
+```python
+from deeptick import CachedClient
+
+client = CachedClient("dtk_your_key", "https://deeptick.dev")
+trades = client.load_trades("lighter", "BTC-USD", "2026-07-08", "2026-07-08")
+```
+
+The SDK uses the public DeepTick REST API under `/v1/*` and sends credentials
+with the `X-API-Key` header.
+
+Surface:
+
+- `DeepTickClient(api_key, base_url="https://deeptick.dev")`
+- `load_trades(exchange, symbol, start, end)` returns a `pyarrow.Table`
+- `download(exchange, data_type, symbol, date, dest)` streams one partition to disk
+- `entitlements()` and `catalog(exchange=None)` return API metadata
+- `CachedClient` adds local Parquet caching under `~/.deeptick/cache`

deeptick-0.1.0/README.md

@@ -0,0 +1,19 @@
+# DeepTick Python SDK
+
+```python
+from deeptick import CachedClient
+
+client = CachedClient("dtk_your_key", "https://deeptick.dev")
+trades = client.load_trades("lighter", "BTC-USD", "2026-07-08", "2026-07-08")
+```
+
+The SDK uses the public DeepTick REST API under `/v1/*` and sends credentials
+with the `X-API-Key` header.
+
+Surface:
+
+- `DeepTickClient(api_key, base_url="https://deeptick.dev")`
+- `load_trades(exchange, symbol, start, end)` returns a `pyarrow.Table`
+- `download(exchange, data_type, symbol, date, dest)` streams one partition to disk
+- `entitlements()` and `catalog(exchange=None)` return API metadata
+- `CachedClient` adds local Parquet caching under `~/.deeptick/cache`

deeptick-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "deeptick"
+version = "0.1.0"
+description = "DeepTick Python SDK for authenticated market data downloads"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "DeepTick"}]
+keywords = ["deeptick", "market-data", "crypto", "parquet", "pyarrow"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "requests>=2.31",
+    "pyarrow>=17.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "build>=1.2",
+]
+
+[project.urls]
+Homepage = "https://deeptick.lacertalabs.xyz"
+Repository = "https://github.com/deeptick/deeptick"
+Documentation = "https://deeptick.lacertalabs.xyz/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deeptick"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

deeptick-0.1.0/src/deeptick/__init__.py

@@ -0,0 +1,6 @@
+"""DeepTick Python SDK."""
+
+from .client import CachedClient, DeepTickAPIError, DeepTickClient
+
+__all__ = ["CachedClient", "DeepTickAPIError", "DeepTickClient"]
+

deeptick-0.1.0/src/deeptick/client.py

@@ -0,0 +1,450 @@
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import shutil
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Any, Iterable
+from urllib.parse import quote
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import requests
+
+DEFAULT_BASE_URL = "https://deeptick.dev"
+USER_AGENT = "deeptick-python/0.1.0"
+DEFAULT_CACHE_DIR = Path(os.path.expanduser("~/.deeptick/cache"))
+DateLike = str | date | datetime
+
+
+class DeepTickAPIError(RuntimeError):
+    """Raised when the DeepTick API returns an unexpected HTTP error."""
+
+
+def _normalize_base_url(base_url: str | None) -> str:
+    value = (base_url or DEFAULT_BASE_URL).rstrip("/")
+    if value.endswith("/v1"):
+        value = value[:-3]
+    return value.rstrip("/")
+
+
+def _looks_like_url(value: str | None) -> bool:
+    return bool(value and value.startswith(("http://", "https://")))
+
+
+def _resolve_cached_client_args(
+    api_key: str | None,
+    base_url: str,
+) -> tuple[str | None, str]:
+    if _looks_like_url(api_key):
+        if base_url == DEFAULT_BASE_URL:
+            return None, api_key or DEFAULT_BASE_URL
+        return base_url, api_key or DEFAULT_BASE_URL
+    return api_key, base_url
+
+
+def _coerce_date(value: DateLike) -> date:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    try:
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    except ValueError as exc:
+        raise ValueError(f"expected date as YYYY-MM-DD, got {value!r}") from exc
+
+
+def _date_range(start: DateLike, end: DateLike | None) -> list[str]:
+    first = _coerce_date(start)
+    last = _coerce_date(end or start)
+    if last < first:
+        raise ValueError("end date must be on or after start date")
+
+    out: list[str] = []
+    current = first
+    while current <= last:
+        out.append(current.isoformat())
+        current += timedelta(days=1)
+    return out
+
+
+def _columns_param(columns: Iterable[str] | None) -> str | None:
+    if columns is None:
+        return None
+    selected = [col for col in columns if col]
+    return ",".join(selected) if selected else None
+
+
+def _empty_table() -> pa.Table:
+    return pa.table({})
+
+
+def _resolve_date_args(
+    start: DateLike | None,
+    end: DateLike | None,
+    *,
+    start_date: DateLike | None = None,
+    end_date: DateLike | None = None,
+) -> tuple[DateLike, DateLike | None]:
+    if (
+        start is not None
+        and start_date is not None
+        and _coerce_date(start) != _coerce_date(start_date)
+    ):
+        raise ValueError("pass either start or start_date, not both")
+    if (
+        end is not None
+        and end_date is not None
+        and _coerce_date(end) != _coerce_date(end_date)
+    ):
+        raise ValueError("pass either end or end_date, not both")
+
+    resolved_start = start if start is not None else start_date
+    if resolved_start is None:
+        raise TypeError("missing required date: start")
+    return resolved_start, end if end is not None else end_date
+
+
+class DeepTickClient:
+    """HTTP client for the DeepTick `/v1/*` REST API.
+
+    Args:
+        api_key: API key sent in the `X-API-Key` header.
+        base_url: API origin, with or without a trailing `/v1`.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        session: requests.Session | None = None,
+        timeout: int = 120,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("DEEPTICK_API_KEY") or ""
+        self.base_url = _normalize_base_url(base_url)
+        self.session = session or requests.Session()
+        self.timeout = timeout
+
+    def catalog(self, exchange: str | None = None) -> dict[str, Any]:
+        """Return the downloadable dataset catalog."""
+        params = {"exchange": exchange} if exchange else None
+        return self._json("/v1/catalog", params=params)
+
+    def entitlements(self) -> dict[str, Any]:
+        """Return the presented API key's download entitlements."""
+        return self._json("/v1/entitlements")
+
+    def download(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        date: DateLike,
+        dest: str | os.PathLike[str],
+        *,
+        columns: Iterable[str] | None = None,
+        format: str = "parquet",
+    ) -> Path:
+        """Download one daily partition to `dest` and return the final path."""
+        target = Path(dest)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        tmp = target.with_name(f"{target.name}.part")
+
+        response = self._request(
+            "GET",
+            self._data_path(exchange, data_type, symbol, date),
+            params=self._data_params(format=format, columns=columns),
+            stream=True,
+        )
+        self._raise_for_status(response)
+        with tmp.open("wb") as fh:
+            for chunk in response.iter_content(chunk_size=256 * 1024):
+                if chunk:
+                    fh.write(chunk)
+        tmp.replace(target)
+        return target
+
+    def load_trades(
+        self,
+        exchange: str,
+        symbol: str,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        *,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table:
+        """Load trade data over an inclusive date range as a PyArrow table."""
+        return self.load(
+            "trades",
+            exchange,
+            symbol,
+            start,
+            end,
+            start_date=start_date,
+            end_date=end_date,
+            columns=columns,
+        )
+
+    def load(
+        self,
+        data_type: str,
+        exchange: str,
+        symbol: str,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        *,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table:
+        """Load any DeepTick data type over an inclusive date range."""
+        start, end = _resolve_date_args(
+            start,
+            end,
+            start_date=start_date,
+            end_date=end_date,
+        )
+        tables = [
+            table
+            for day in _date_range(start, end)
+            if (table := self._load_day(exchange, data_type, symbol, day, columns=columns))
+            is not None
+        ]
+        if not tables:
+            return _empty_table()
+        return pa.concat_tables(tables, promote_options="default")
+
+    def _load_day(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: str,
+        *,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table | None:
+        response = self._request(
+            "GET",
+            self._data_path(exchange, data_type, symbol, day),
+            params=self._data_params(format="parquet", columns=columns),
+        )
+        if response.status_code == 404:
+            return None
+        self._raise_for_status(response)
+        return pq.read_table(io.BytesIO(response.content))
+
+    def _json(self, path: str, *, params: dict[str, str] | None = None) -> dict[str, Any]:
+        response = self._request("GET", path, params=params)
+        self._raise_for_status(response)
+        data = response.json()
+        if not isinstance(data, dict):
+            raise DeepTickAPIError(f"expected object response from {path}")
+        return data
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        stream: bool = False,
+    ) -> requests.Response:
+        return self.session.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+            stream=stream,
+        )
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"User-Agent": USER_AGENT}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        return headers
+
+    @staticmethod
+    def _raise_for_status(response: requests.Response) -> None:
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            detail = response.text[:500] if response.text else response.reason
+            message = f"DeepTick API returned HTTP {response.status_code}: {detail}"
+            raise DeepTickAPIError(message) from exc
+
+    @staticmethod
+    def _data_path(
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: DateLike,
+    ) -> str:
+        return (
+            "/v1/data/"
+            f"{quote(exchange, safe='')}/"
+            f"{quote(data_type, safe='')}/"
+            f"{quote(symbol, safe='')}/"
+            f"{quote(_coerce_date(day).isoformat(), safe='')}"
+        )
+
+    @staticmethod
+    def _data_params(
+        *,
+        format: str = "parquet",
+        columns: Iterable[str] | None = None,
+    ) -> dict[str, str]:
+        params = {"format": format}
+        if selected := _columns_param(columns):
+            params["columns"] = selected
+        return params
+
+
+class CachedClient(DeepTickClient):
+    """DeepTick client with local daily parquet caching.
+
+    The preferred positional order matches `DeepTickClient(api_key, base_url)`.
+    Existing site examples that pass `base_url` first or use keywords are also
+    accepted.
+
+    ```python
+    from deeptick import CachedClient
+    client = CachedClient(api_key="dtk_your_key")
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        cache_dir: str | os.PathLike[str] = DEFAULT_CACHE_DIR,
+        max_workers: int = 8,
+        session: requests.Session | None = None,
+        timeout: int = 120,
+    ) -> None:
+        api_key, base_url = _resolve_cached_client_args(api_key, base_url)
+        super().__init__(api_key=api_key, base_url=base_url, session=session, timeout=timeout)
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.max_workers = max_workers
+        self.cache_hits = 0
+        self.cache_misses = 0
+        self.bytes_downloaded = 0
+        self.bytes_from_cache = 0
+
+    def load(
+        self,
+        data_type: str,
+        exchange: str,
+        symbol: str,
+        start: DateLike | None = None,
+        end: DateLike | None = None,
+        *,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table:
+        start, end = _resolve_date_args(start, end, start_date=start_date, end_date=end_date)
+        days = _date_range(start, end)
+        if len(days) == 1:
+            table = self._load_day_cached(exchange, data_type, symbol, days[0], columns=columns)
+            return table if table is not None else _empty_table()
+
+        tables: list[tuple[str, pa.Table]] = []
+        with ThreadPoolExecutor(max_workers=min(self.max_workers, len(days))) as pool:
+            futures = {
+                pool.submit(
+                    self._load_day_cached,
+                    exchange,
+                    data_type,
+                    symbol,
+                    day,
+                    columns=columns,
+                ): day
+                for day in days
+            }
+            for future in as_completed(futures):
+                day = futures[future]
+                table = future.result()
+                if table is not None:
+                    tables.append((day, table))
+
+        if not tables:
+            return _empty_table()
+        tables.sort(key=lambda item: item[0])
+        return pa.concat_tables([table for _, table in tables], promote_options="default")
+
+    def cache_stats(self) -> dict[str, Any]:
+        """Return cache counters and current disk footprint."""
+        files = list(self.cache_dir.rglob("*.parquet"))
+        total_bytes = sum(path.stat().st_size for path in files)
+        total_requests = self.cache_hits + self.cache_misses
+        total_bytes_seen = self.bytes_from_cache + self.bytes_downloaded
+        return {
+            "cache_dir": str(self.cache_dir),
+            "cache_hits": self.cache_hits,
+            "cache_misses": self.cache_misses,
+            "hit_rate_pct": round(self.cache_hits / max(total_requests, 1) * 100, 1),
+            "cached_files": len(files),
+            "cache_size_mb": round(total_bytes / (1024 * 1024), 2),
+            "bytes_downloaded": self.bytes_downloaded,
+            "bytes_from_cache": self.bytes_from_cache,
+            "bandwidth_saved_pct": round(
+                self.bytes_from_cache / max(total_bytes_seen, 1) * 100,
+                1,
+            ),
+        }
+
+    def clear_cache(self) -> None:
+        """Remove all locally cached parquet files."""
+        shutil.rmtree(self.cache_dir, ignore_errors=True)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _load_day_cached(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: str,
+        *,
+        columns: Iterable[str] | None = None,
+    ) -> pa.Table | None:
+        cache_path = self._cache_path(exchange, data_type, symbol, day, columns=columns)
+        if cache_path.exists() and cache_path.stat().st_size > 0:
+            self.cache_hits += 1
+            self.bytes_from_cache += cache_path.stat().st_size
+            return pq.read_table(cache_path)
+
+        self.cache_misses += 1
+        table = super()._load_day(exchange, data_type, symbol, day, columns=columns)
+        if table is None:
+            return None
+
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cache_path.with_name(f"{cache_path.name}.part")
+        pq.write_table(table, tmp, compression="zstd")
+        tmp.replace(cache_path)
+        self.bytes_downloaded += cache_path.stat().st_size
+        return table
+
+    def _cache_path(
+        self,
+        exchange: str,
+        data_type: str,
+        symbol: str,
+        day: str,
+        *,
+        columns: Iterable[str] | None = None,
+    ) -> Path:
+        safe_symbol = symbol.replace("/", "-").replace(":", "-")
+        suffix = ""
+        if selected := _columns_param(columns):
+            suffix = "_" + hashlib.md5(selected.encode("utf-8")).hexdigest()[:8]
+        return self.cache_dir / exchange / data_type / safe_symbol / f"{day}{suffix}.parquet"

deeptick-0.1.0/src/deeptick/py.typed

@@ -0,0 +1 @@
+

deeptick-0.1.0/tests/test_client.py

@@ -0,0 +1,216 @@
+import io
+import json
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import pytest
+import requests
+
+from deeptick import CachedClient, DeepTickAPIError, DeepTickClient
+
+
+class FakeResponse:
+    def __init__(self, status_code=200, content=b"", json_data=None, reason="OK"):
+        self.status_code = status_code
+        self.content = content
+        self._json_data = json_data
+        self.reason = reason
+        self.text = content.decode("utf-8", errors="replace") if content else ""
+
+    def json(self):
+        if self._json_data is not None:
+            return self._json_data
+        return json.loads(self.content)
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            error = requests.HTTPError(f"{self.status_code} {self.reason}")
+            error.response = self
+            raise error
+
+    def iter_content(self, chunk_size=1):
+        for offset in range(0, len(self.content), chunk_size):
+            yield self.content[offset : offset + chunk_size]
+
+
+class FakeSession:
+    def __init__(self, routes):
+        self.routes = routes
+        self.calls = []
+
+    def request(self, method, url, headers=None, params=None, timeout=None, stream=False):
+        self.calls.append(
+            {
+                "method": method,
+                "url": url,
+                "headers": headers or {},
+                "params": params,
+                "timeout": timeout,
+                "stream": stream,
+            }
+        )
+        key = (method, url, tuple(sorted((params or {}).items())))
+        try:
+            return self.routes[key]
+        except KeyError:
+            return FakeResponse(404, b"not found", reason="Not Found")
+
+
+def parquet_bytes(values):
+    table = pa.table(values)
+    buf = io.BytesIO()
+    pq.write_table(table, buf, compression="zstd")
+    return buf.getvalue()
+
+
+def test_metadata_requests_include_api_key():
+    session = FakeSession(
+        {
+            ("GET", "https://example.test/v1/entitlements", ()): FakeResponse(
+                json_data={"plan": "pilot"}
+            ),
+            (
+                "GET",
+                "https://example.test/v1/catalog",
+                (("exchange", "lighter"),),
+            ): FakeResponse(json_data={"datasets": []}),
+        }
+    )
+    client = DeepTickClient("dtk_test", "https://example.test", session=session)
+
+    assert client.entitlements() == {"plan": "pilot"}
+    assert client.catalog("lighter") == {"datasets": []}
+    assert all(call["headers"]["X-API-Key"] == "dtk_test" for call in session.calls)
+
+
+def test_load_trades_returns_concatenated_pyarrow_table():
+    day1 = parquet_bytes({"price": [1.0], "amount": [2.0]})
+    day2 = parquet_bytes({"price": [3.0], "amount": [4.0]})
+    session = FakeSession(
+        {
+            (
+                "GET",
+                "https://example.test/v1/data/lighter/trades/BTC-USD/2026-07-01",
+                (("format", "parquet"),),
+            ): FakeResponse(content=day1),
+            (
+                "GET",
+                "https://example.test/v1/data/lighter/trades/BTC-USD/2026-07-02",
+                (("format", "parquet"),),
+            ): FakeResponse(content=day2),
+        }
+    )
+    client = DeepTickClient("dtk_test", "https://example.test/v1", session=session)
+
+    table = client.load_trades("lighter", "BTC-USD", "2026-07-01", "2026-07-02")
+
+    assert table.num_rows == 2
+    assert table.column("price").to_pylist() == [1.0, 3.0]
+
+
+def test_load_accepts_site_date_keyword_aliases():
+    payload = parquet_bytes({"price": [5.0], "amount": [1.25]})
+    session = FakeSession(
+        {
+            (
+                "GET",
+                "https://example.test/v1/data/lighter/trades/BTC-USD/2026-07-01",
+                (("format", "parquet"),),
+            ): FakeResponse(content=payload),
+        }
+    )
+    client = DeepTickClient("dtk_test", "https://example.test", session=session)
+
+    table = client.load(
+        exchange="lighter",
+        data_type="trades",
+        symbol="BTC-USD",
+        start_date="2026-07-01",
+        end_date="2026-07-01",
+    )
+
+    assert table.num_rows == 1
+    assert table.column("amount").to_pylist() == [1.25]
+
+
+def test_conflicting_date_aliases_are_rejected():
+    client = DeepTickClient("dtk_test", "https://example.test", session=FakeSession({}))
+
+    with pytest.raises(ValueError, match="start or start_date"):
+        client.load_trades(
+            "lighter",
+            "BTC-USD",
+            "2026-07-01",
+            start_date="2026-07-02",
+        )
+
+
+def test_download_streams_to_destination(tmp_path):
+    session = FakeSession(
+        {
+            (
+                "GET",
+                "https://example.test/v1/data/lighter/trades/BTC-USD/2026-07-01",
+                (("format", "parquet"),),
+            ): FakeResponse(content=b"parquet-bytes"),
+        }
+    )
+    client = DeepTickClient("dtk_test", "https://example.test", session=session)
+    dest = tmp_path / "trades.parquet"
+
+    returned = client.download("lighter", "trades", "BTC-USD", "2026-07-01", dest)
+
+    assert returned == dest
+    assert dest.read_bytes() == b"parquet-bytes"
+    assert session.calls[0]["stream"] is True
+
+
+def test_cached_client_uses_disk_cache(tmp_path):
+    payload = parquet_bytes({"price": [10.0], "amount": [0.5]})
+    session = FakeSession(
+        {
+            (
+                "GET",
+                "https://example.test/v1/data/lighter/trades/BTC-USD/2026-07-01",
+                (("format", "parquet"),),
+            ): FakeResponse(content=payload),
+        }
+    )
+    client = CachedClient("https://example.test", "dtk_test", cache_dir=tmp_path, session=session)
+
+    first = client.load_trades("lighter", "BTC-USD", "2026-07-01", "2026-07-01")
+    second = client.load_trades("lighter", "BTC-USD", "2026-07-01", "2026-07-01")
+
+    assert first.column("price").to_pylist() == [10.0]
+    assert second.column("price").to_pylist() == [10.0]
+    assert len(session.calls) == 1
+    assert client.cache_stats()["cache_hits"] == 1
+    assert client.cache_stats()["cache_misses"] == 1
+
+
+def test_cached_client_accepts_api_key_first_positional_args():
+    session = FakeSession(
+        {
+            ("GET", "https://example.test/v1/entitlements", ()): FakeResponse(
+                json_data={"plan": "pilot"}
+            ),
+        }
+    )
+    client = CachedClient("dtk_test", "https://example.test", session=session)
+
+    assert client.entitlements() == {"plan": "pilot"}
+    assert session.calls[0]["headers"]["X-API-Key"] == "dtk_test"
+
+
+def test_http_errors_raise_sdk_error():
+    session = FakeSession(
+        {
+            ("GET", "https://example.test/v1/entitlements", ()): FakeResponse(
+                403, b"forbidden", reason="Forbidden"
+            ),
+        }
+    )
+    client = DeepTickClient("bad", "https://example.test", session=session)
+
+    with pytest.raises(DeepTickAPIError):
+        client.entitlements()