orcalayer 0.1.0__tar.gz

orcalayer-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.venv/
+.env

orcalayer-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — 2026-06-12
+
+Initial release.
+
+- `OrcaLayer` client with anonymous and Premium (Bearer key) access tiers.
+- Methods: `leaderboard`, `wallet_overview`, `wallet_positions`, `markets`, `whale_alerts` (Premium).
+- Automatic retry on HTTP 429 (honours `Retry-After`, exponential backoff) and single retry on 502.
+- Typed exceptions: `PremiumRequiredError`, `AuthenticationError`, `RateLimitError`, `ServerError`.

orcalayer-0.1.0/LICENSE

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

orcalayer-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: orcalayer
+Version: 0.1.0
+Summary: Python client for the OrcaLayer API — Polymarket whale and market analytics
+Project-URL: Homepage, https://orcalayer.com
+Project-URL: Documentation, https://orcalayer.com/docs
+Project-URL: Repository, https://github.com/orcalayer/orcalayer-python
+Project-URL: Changelog, https://github.com/orcalayer/orcalayer-python/blob/main/CHANGELOG.md
+Author: OrcaLayer
+License: MIT
+License-File: LICENSE
+Keywords: analytics,api-client,polymarket,prediction-markets,trading,whales
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# orcalayer
+
+Official Python client for the [OrcaLayer API](https://orcalayer.com) — Polymarket whale and market analytics: wallet P&L, open positions, smart-whale leaderboard, market search and real-time whale alerts.
+
+## Install
+
+```
+pip install orcalayer
+```
+
+Requires Python 3.10+. Single dependency: `httpx`.
+
+## Quickstart
+
+Three lines to a first result — no API key needed for public endpoints:
+
+```python
+from orcalayer import OrcaLayer
+
+ol = OrcaLayer()
+print(ol.leaderboard(limit=5))
+```
+
+Anonymous access is limited to 200 requests/min per IP, and wallet endpoints (`wallet_overview`, `wallet_positions`) additionally to 300 requests/day per IP. With a Premium API key ([get one here](https://orcalayer.com/pricing)) you get 600 req/min, no daily cap, and access to Premium endpoints such as whale alerts:
+
+```python
+ol = OrcaLayer(api_key="ol_your_key")
+alerts = ol.whale_alerts(minutes=30, min_usd=1000)
+```
+
+## Methods
+
+| Method | Endpoint | Access |
+|---|---|---|
+| `leaderboard(sort, category, limit, ...)` | Smart-whale leaderboard with server-side filters | Public |
+| `wallet_overview(address)` | Wallet profile + trading stats (accepts 0x address or nickname) | Public |
+| `wallet_positions(address, limit, offset)` | Open positions, sorted by current value | Public |
+| `markets(q, category, min_volume, ...)` | Market search (accepts free text or a Polymarket URL) | Public |
+| `whale_alerts(minutes, min_usd, ...)` | Recent smart-whale trades feed | Premium |
+
+All methods return the JSON response as a plain `dict`, exactly as the API sends it. Full field reference: [orcalayer.com/docs](https://orcalayer.com/docs).
+
+## Behavior notes
+
+- **Rate limits**: on HTTP 429 the client reads `Retry-After` and retries with exponential backoff (default 3 attempts). Disable with `OrcaLayer(retry_on_rate_limit=False)`. A `Retry-After` beyond 5 minutes signals the anonymous daily cap rather than a burst — the client then raises `RateLimitError` immediately instead of retrying.
+- **Transient 502** responses are retried once automatically.
+- **Premium endpoints without a key** raise `PremiumRequiredError` with a link to [pricing](https://orcalayer.com/pricing) — no network call is made.
+- **Wallet overview freshness**: responses include `as_of` (data timestamp) and `degraded` (heavy side-stats timed out, core stats still present).
+- **Cold heavy wallets** answer HTTP 202 while their stats are computed server-side. The client retries once automatically after the server's `Retry-After` interval; if the wallet is still not ready it raises `WalletComputingError` (carrying `retry_after`) so a 202 body is never mistaken for wallet data.
+
+## Errors
+
+```python
+from orcalayer import PremiumRequiredError, RateLimitError, AuthenticationError, ServerError
+```
+
+All inherit from `orcalayer.OrcaLayerError`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Data is provided for informational purposes only and is not financial advice.

orcalayer-0.1.0/README.md

@@ -0,0 +1,63 @@
+# orcalayer
+
+Official Python client for the [OrcaLayer API](https://orcalayer.com) — Polymarket whale and market analytics: wallet P&L, open positions, smart-whale leaderboard, market search and real-time whale alerts.
+
+## Install
+
+```
+pip install orcalayer
+```
+
+Requires Python 3.10+. Single dependency: `httpx`.
+
+## Quickstart
+
+Three lines to a first result — no API key needed for public endpoints:
+
+```python
+from orcalayer import OrcaLayer
+
+ol = OrcaLayer()
+print(ol.leaderboard(limit=5))
+```
+
+Anonymous access is limited to 200 requests/min per IP, and wallet endpoints (`wallet_overview`, `wallet_positions`) additionally to 300 requests/day per IP. With a Premium API key ([get one here](https://orcalayer.com/pricing)) you get 600 req/min, no daily cap, and access to Premium endpoints such as whale alerts:
+
+```python
+ol = OrcaLayer(api_key="ol_your_key")
+alerts = ol.whale_alerts(minutes=30, min_usd=1000)
+```
+
+## Methods
+
+| Method | Endpoint | Access |
+|---|---|---|
+| `leaderboard(sort, category, limit, ...)` | Smart-whale leaderboard with server-side filters | Public |
+| `wallet_overview(address)` | Wallet profile + trading stats (accepts 0x address or nickname) | Public |
+| `wallet_positions(address, limit, offset)` | Open positions, sorted by current value | Public |
+| `markets(q, category, min_volume, ...)` | Market search (accepts free text or a Polymarket URL) | Public |
+| `whale_alerts(minutes, min_usd, ...)` | Recent smart-whale trades feed | Premium |
+
+All methods return the JSON response as a plain `dict`, exactly as the API sends it. Full field reference: [orcalayer.com/docs](https://orcalayer.com/docs).
+
+## Behavior notes
+
+- **Rate limits**: on HTTP 429 the client reads `Retry-After` and retries with exponential backoff (default 3 attempts). Disable with `OrcaLayer(retry_on_rate_limit=False)`. A `Retry-After` beyond 5 minutes signals the anonymous daily cap rather than a burst — the client then raises `RateLimitError` immediately instead of retrying.
+- **Transient 502** responses are retried once automatically.
+- **Premium endpoints without a key** raise `PremiumRequiredError` with a link to [pricing](https://orcalayer.com/pricing) — no network call is made.
+- **Wallet overview freshness**: responses include `as_of` (data timestamp) and `degraded` (heavy side-stats timed out, core stats still present).
+- **Cold heavy wallets** answer HTTP 202 while their stats are computed server-side. The client retries once automatically after the server's `Retry-After` interval; if the wallet is still not ready it raises `WalletComputingError` (carrying `retry_after`) so a 202 body is never mistaken for wallet data.
+
+## Errors
+
+```python
+from orcalayer import PremiumRequiredError, RateLimitError, AuthenticationError, ServerError
+```
+
+All inherit from `orcalayer.OrcaLayerError`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Data is provided for informational purposes only and is not financial advice.

orcalayer-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "orcalayer"
+version = "0.1.0"
+description = "Python client for the OrcaLayer API — Polymarket whale and market analytics"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "OrcaLayer" }]
+keywords = ["polymarket", "prediction-markets", "whales", "trading", "analytics", "api-client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://orcalayer.com"
+Documentation = "https://orcalayer.com/docs"
+Repository = "https://github.com/orcalayer/orcalayer-python"
+Changelog = "https://github.com/orcalayer/orcalayer-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/orcalayer"]

orcalayer-0.1.0/src/orcalayer/__init__.py

@@ -0,0 +1,24 @@
+"""orcalayer — Python client for the OrcaLayer API (https://orcalayer.com)."""
+
+from .client import OrcaLayer
+from .errors import (
+    AuthenticationError,
+    OrcaLayerError,
+    PremiumRequiredError,
+    RateLimitError,
+    ServerError,
+    WalletComputingError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OrcaLayer",
+    "OrcaLayerError",
+    "PremiumRequiredError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ServerError",
+    "WalletComputingError",
+    "__version__",
+]

orcalayer-0.1.0/src/orcalayer/client.py

@@ -0,0 +1,303 @@
+"""OrcaLayer API client.
+
+Two access tiers, selected automatically by whether an API key is given:
+
+* Anonymous  — public endpoints under ``/api/v2`` (200 requests/min per IP).
+* Premium    — same data plus Premium endpoints under ``/api/public/v1``
+               with ``Authorization: Bearer`` auth (600 requests/min per key).
+
+All methods return the JSON response as a plain ``dict`` — exactly what the
+API sends, no client-side reshaping.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from .errors import (
+    AuthenticationError,
+    OrcaLayerError,
+    PremiumRequiredError,
+    RateLimitError,
+    ServerError,
+    WalletComputingError,
+)
+
+DEFAULT_BASE_URL = "https://orcalayer.com"
+PUBLIC_PREFIX = "/api/v2"
+PREMIUM_PREFIX = "/api/public/v1"
+USER_AGENT = "Mozilla/5.0 (compatible; orcalayer-python/0.1.0)"
+
+
+class OrcaLayer:
+    """Client for the OrcaLayer API.
+
+    Args:
+        api_key: Premium API key. Omit for anonymous access to public
+            endpoints; Premium endpoints then raise ``PremiumRequiredError``.
+        base_url: API host. Defaults to ``https://orcalayer.com``.
+        timeout: Per-request timeout in seconds.
+        retry_on_rate_limit: When True (default), HTTP 429 responses are
+            retried using the server's ``Retry-After`` header with
+            exponential backoff. Set False to raise ``RateLimitError``
+            immediately.
+        max_retries: Maximum retry attempts for 429 responses.
+
+    Example:
+        >>> from orcalayer import OrcaLayer
+        >>> ol = OrcaLayer()
+        >>> top = ol.leaderboard(limit=10)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        retry_on_rate_limit: bool = True,
+        max_retries: int = 3,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.retry_on_rate_limit = retry_on_rate_limit
+        self.max_retries = max_retries
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._client = httpx.Client(timeout=timeout, headers=headers)
+
+    # ── HTTP core ────────────────────────────────────────────────────────
+
+    def _get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        *,
+        premium_only: bool = False,
+    ) -> dict:
+        """GET ``path`` (no leading slash) and return the parsed JSON dict.
+
+        With an API key every call is routed through the Premium surface
+        (``/api/public/v1``, Bearer auth, higher rate limit). Without a key,
+        public endpoints go to ``/api/v2`` and Premium-only endpoints raise
+        ``PremiumRequiredError``.
+        """
+        if premium_only and not self.api_key:
+            raise PremiumRequiredError(path)
+        prefix = PREMIUM_PREFIX if self.api_key else PUBLIC_PREFIX
+        url = f"{self.base_url}{prefix}/{path}"
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+
+        attempt = 0
+        retried_202 = False
+        while True:
+            try:
+                resp = self._client.get(url, params=clean)
+            except httpx.HTTPError as exc:
+                raise OrcaLayerError(f"Request to {url} failed: {exc}") from exc
+
+            if resp.status_code == 202:
+                # Cold heavy wallet: stats are being computed server-side.
+                # One automatic retry after Retry-After, then a typed error
+                # so callers never mistake the 202 body for real data.
+                retry_after = _retry_after_seconds(resp)
+                if retried_202:
+                    raise WalletComputingError(retry_after)
+                retried_202 = True
+                time.sleep(min(retry_after, 60))
+                continue
+
+            if resp.status_code == 429:
+                retry_after = _retry_after_seconds(resp)
+                # A Retry-After beyond 5 minutes signals a daily quota, not a
+                # sliding-window burst — retrying within this process is futile.
+                if (
+                    not self.retry_on_rate_limit
+                    or attempt >= self.max_retries
+                    or retry_after > 300
+                ):
+                    raise RateLimitError(retry_after, _detail(resp))
+                # Server window is sliding 60s; honour Retry-After and add
+                # exponential backoff across attempts so bursts drain cleanly.
+                time.sleep(min(max(retry_after, 2.0 ** attempt), 120.0))
+                attempt += 1
+                continue
+
+            if resp.status_code == 502 and attempt == 0:
+                # Transient gateway hiccup: a single retry, then give up.
+                attempt += 1
+                time.sleep(1)
+                continue
+
+            if resp.status_code in (401, 403):
+                raise AuthenticationError(resp.status_code, _detail(resp))
+
+            if resp.status_code >= 500:
+                raise ServerError(resp.status_code, resp.text)
+
+            resp.raise_for_status()
+            return resp.json()
+
+    # ── Public endpoints (work with or without a key) ────────────────────
+
+    def leaderboard(
+        self,
+        *,
+        sort: str = "pnl",
+        category: str | None = None,
+        filter: str = "smart",
+        limit: int = 50,
+        offset: int = 0,
+        min_markets: int | None = None,
+        min_wr: float | None = None,
+        min_pnl: float | None = None,
+        min_profit_factor: float | None = None,
+        max_avg_entry: float | None = None,
+        max_sports_pct: float | None = None,
+    ) -> dict:
+        """Smart-whale leaderboard.
+
+        Args:
+            sort: ``pnl`` (default), ``win_rate``, ``volume`` or ``trades``.
+            category: Market category filter (e.g. ``Crypto``, ``Sports``).
+            filter: ``smart`` (curated whales, default) or ``all``.
+            limit / offset: Pagination.
+            min_markets, min_wr, min_pnl, min_profit_factor, max_avg_entry,
+            max_sports_pct: Optional numeric screens, applied server-side.
+        """
+        return self._get(
+            "whales/leaderboard",
+            {
+                "sort": sort,
+                "category": category,
+                "filter": filter,
+                "limit": limit,
+                "offset": offset,
+                "min_markets": min_markets,
+                "min_wr": min_wr,
+                "min_pnl": min_pnl,
+                "min_profit_factor": min_profit_factor,
+                "max_avg_entry": max_avg_entry,
+                "max_sports_pct": max_sports_pct,
+            },
+        )
+
+    def wallet_overview(self, address: str) -> dict:
+        """Wallet profile and trading stats.
+
+        ``address`` is a 0x wallet address or an OrcaLayer nickname.
+        The response carries ``as_of`` (data timestamp, epoch seconds) and
+        ``degraded`` (True when heavy side-stats timed out; core stats are
+        still present). A cold heavy wallet answers HTTP 202 while its stats
+        are computed: the client retries once automatically after the
+        server's ``Retry-After`` interval and raises ``WalletComputingError``
+        if the wallet is still not ready.
+        """
+        return self._get(f"wallet/{address}/overview")
+
+    def wallet_positions(self, address: str, *, limit: int = 200, offset: int = 0) -> dict:
+        """Open positions for a wallet (sorted by current value, cap 500/page)."""
+        return self._get(
+            f"wallet/{address}/positions", {"limit": limit, "offset": offset}
+        )
+
+    def markets(
+        self,
+        q: str = "",
+        *,
+        category: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        min_volume: float | None = None,
+        min_whales: int | None = None,
+        price_min: int | None = None,
+        price_max: int | None = None,
+    ) -> dict:
+        """Search or browse markets.
+
+        Args:
+            q: Free-text query; also accepts a Polymarket URL or slug.
+            category: ``Crypto`` | ``Geopolitics`` | ``Sports`` | ``Politics``
+                | ``Economics`` | ``Tech/AI``.
+            min_volume: Minimum market volume in USD.
+            min_whales: Minimum count of smart whales in the market.
+            price_min / price_max: YES price band in cents (0-100).
+        """
+        return self._get(
+            "markets/search",
+            {
+                "q": q,
+                "category": category,
+                "limit": limit,
+                "offset": offset,
+                "min_volume": min_volume,
+                "min_whales": min_whales,
+                "price_min": price_min,
+                "price_max": price_max,
+            },
+        )
+
+    # ── Premium endpoints (API key required) ─────────────────────────────
+
+    def whale_alerts(
+        self,
+        *,
+        minutes: int = 10,
+        wallet: str | None = None,
+        market_id: str | None = None,
+        min_usd: float = 10,
+        smart_only: bool = True,
+        limit: int = 50,
+        category: str | None = None,
+    ) -> dict:
+        """Recent smart-whale trades (Premium).
+
+        Args:
+            minutes: Lookback window, max 1440 (24h).
+            wallet: Filter to one wallet address.
+            market_id: Filter to one market.
+            min_usd: Minimum trade size in USD.
+            smart_only: Only curated smart whales (default True).
+        """
+        return self._get(
+            "whale-alerts",
+            {
+                "minutes": minutes,
+                "wallet": wallet,
+                "market_id": market_id,
+                "min_usd": min_usd,
+                "smart_only": smart_only,
+                "limit": limit,
+                "category": category,
+            },
+            premium_only=True,
+        )
+
+    # ── Lifecycle ────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "OrcaLayer":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+def _retry_after_seconds(resp: httpx.Response) -> float:
+    try:
+        return max(1.0, float(resp.headers.get("Retry-After", "60")))
+    except ValueError:
+        return 60.0
+
+
+def _detail(resp: httpx.Response) -> str:
+    try:
+        return str(resp.json().get("error", ""))
+    except Exception:
+        return ""

orcalayer-0.1.0/src/orcalayer/errors.py

@@ -0,0 +1,67 @@
+"""Exception types raised by the OrcaLayer client."""
+
+PRICING_URL = "https://orcalayer.com/pricing"
+
+
+class OrcaLayerError(Exception):
+    """Base class for all OrcaLayer client errors."""
+
+
+class PremiumRequiredError(OrcaLayerError):
+    """A Premium endpoint was called without an API key."""
+
+    def __init__(self, endpoint: str):
+        super().__init__(
+            f"'{endpoint}' is a Premium endpoint and requires an API key. "
+            f"Create one at {PRICING_URL} and pass it as "
+            f"OrcaLayer(api_key=\"...\")."
+        )
+        self.endpoint = endpoint
+
+
+class AuthenticationError(OrcaLayerError):
+    """The API key was rejected (HTTP 401/403)."""
+
+    def __init__(self, status_code: int, detail: str = ""):
+        msg = f"API key rejected (HTTP {status_code})."
+        if detail:
+            msg += f" Server said: {detail}"
+        msg += f" Check your key at https://orcalayer.com/settings or get one at {PRICING_URL}."
+        super().__init__(msg)
+        self.status_code = status_code
+
+
+class WalletComputingError(OrcaLayerError):
+    """The wallet's stats are still being computed server-side (HTTP 202).
+
+    Raised after one automatic retry. Poll again after ``retry_after`` seconds.
+    """
+
+    def __init__(self, retry_after: float):
+        super().__init__(
+            f"Wallet stats are still computing server-side; "
+            f"retry in {retry_after:.0f}s."
+        )
+        self.retry_after = retry_after
+
+
+class RateLimitError(OrcaLayerError):
+    """Rate limit still exceeded after all retries (HTTP 429)."""
+
+    def __init__(self, retry_after: float, detail: str = ""):
+        msg = f"Rate limit exceeded; retry after {retry_after:.0f}s."
+        if detail:
+            msg += f" Server said: {detail}"
+        super().__init__(msg)
+        self.retry_after = retry_after
+
+
+class ServerError(OrcaLayerError):
+    """The API returned an unexpected 5xx response."""
+
+    def __init__(self, status_code: int, detail: str = ""):
+        msg = f"OrcaLayer API server error (HTTP {status_code})."
+        if detail:
+            msg += f" Body: {detail[:200]}"
+        super().__init__(msg)
+        self.status_code = status_code

orcalayer-0.1.0/tests/test_retry.py

@@ -0,0 +1,63 @@
+"""Offline tests for retry semantics (202 / 429 / 502) via httpx.MockTransport."""
+
+import httpx
+import pytest
+
+from orcalayer import OrcaLayer, RateLimitError, WalletComputingError
+
+
+def make_client(responses: list[httpx.Response]) -> OrcaLayer:
+    """OrcaLayer whose HTTP layer replays canned responses in order."""
+    queue = list(responses)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return queue.pop(0)
+
+    ol = OrcaLayer()
+    ol._client = httpx.Client(transport=httpx.MockTransport(handler))
+    return ol
+
+
+def test_202_retries_once_then_returns_data():
+    ol = make_client([
+        httpx.Response(202, headers={"Retry-After": "1"}, json={"detail": "computing"}),
+        httpx.Response(200, json={"wallet": "0xabc", "total_pnl": 1.0}),
+    ])
+    data = ol.wallet_overview("0xabc")
+    assert data["total_pnl"] == 1.0
+
+
+def test_202_twice_raises_computing_error():
+    ol = make_client([
+        httpx.Response(202, headers={"Retry-After": "1"}, json={"detail": "computing"}),
+        httpx.Response(202, headers={"Retry-After": "30"}, json={"detail": "computing"}),
+    ])
+    with pytest.raises(WalletComputingError) as exc:
+        ol.wallet_overview("0xabc")
+    assert exc.value.retry_after == 30
+
+
+def test_429_long_retry_after_raises_immediately():
+    # Retry-After beyond 300s = daily quota; must not sleep/retry.
+    ol = make_client([
+        httpx.Response(429, headers={"Retry-After": "3600"}, json={"error": "daily"}),
+    ])
+    with pytest.raises(RateLimitError) as exc:
+        ol.wallet_overview("0xabc")
+    assert exc.value.retry_after == 3600
+
+
+def test_429_short_then_ok_retries():
+    ol = make_client([
+        httpx.Response(429, headers={"Retry-After": "1"}, json={"error": "burst"}),
+        httpx.Response(200, json={"ok": True}),
+    ])
+    assert ol.wallet_overview("0xabc") == {"ok": True}
+
+
+def test_502_single_retry():
+    ol = make_client([
+        httpx.Response(502, text="bad gateway"),
+        httpx.Response(200, json={"ok": True}),
+    ])
+    assert ol.markets(limit=1) == {"ok": True}

orcalayer-0.1.0/tests/test_smoke.py

@@ -0,0 +1,78 @@
+"""Smoke tests against the live API.
+
+Anonymous tests always run. Premium tests need ORCALAYER_TEST_API_KEY in the
+environment and are skipped otherwise. Run: python -m pytest tests/ -v
+"""
+
+import os
+
+import pytest
+
+from orcalayer import OrcaLayer, PremiumRequiredError
+
+PREMIUM_KEY = os.environ.get("ORCALAYER_TEST_API_KEY", "")
+# Known active wallet for read-only smoke checks (public leaderboard member).
+TEST_WALLET = os.environ.get("ORCALAYER_TEST_WALLET", "")
+
+
+@pytest.fixture(scope="module")
+def anon():
+    with OrcaLayer() as client:
+        yield client
+
+
+def test_leaderboard_anon(anon):
+    data = anon.leaderboard(limit=5)
+    assert isinstance(data, dict)
+    whales = data.get("whales") or data.get("leaderboard") or data.get("results")
+    assert whales, f"unexpected leaderboard shape: {list(data)}"
+    assert len(whales) <= 5
+
+
+def test_markets_anon(anon):
+    data = anon.markets(limit=5)
+    assert isinstance(data, dict)
+    assert data.get("markets") or data.get("results"), f"unexpected shape: {list(data)}"
+
+
+def test_wallet_overview_anon(anon):
+    address = TEST_WALLET or _first_leaderboard_wallet(anon)
+    data = anon.wallet_overview(address)
+    assert isinstance(data, dict)
+    assert "error" not in data, data.get("error")
+
+
+def test_wallet_positions_anon(anon):
+    address = TEST_WALLET or _first_leaderboard_wallet(anon)
+    data = anon.wallet_positions(address, limit=10)
+    assert isinstance(data, dict)
+
+
+def test_premium_without_key_raises(anon):
+    with pytest.raises(PremiumRequiredError) as exc:
+        anon.whale_alerts()
+    assert "pricing" in str(exc.value)
+
+
+@pytest.mark.skipif(not PREMIUM_KEY, reason="ORCALAYER_TEST_API_KEY not set")
+def test_whale_alerts_premium():
+    with OrcaLayer(api_key=PREMIUM_KEY) as client:
+        data = client.whale_alerts(minutes=60, limit=5)
+    assert isinstance(data, dict)
+    assert "error" not in data, data.get("error")
+
+
+@pytest.mark.skipif(not PREMIUM_KEY, reason="ORCALAYER_TEST_API_KEY not set")
+def test_overview_via_premium_surface():
+    with OrcaLayer(api_key=PREMIUM_KEY) as client:
+        address = TEST_WALLET or _first_leaderboard_wallet(client)
+        data = client.wallet_overview(address)
+    assert isinstance(data, dict)
+    assert "error" not in data, data.get("error")
+
+
+def _first_leaderboard_wallet(client):
+    data = client.leaderboard(limit=1)
+    whales = data.get("whales") or data.get("leaderboard") or data.get("results")
+    entry = whales[0]
+    return entry.get("wallet") or entry.get("address") or entry.get("proxy_wallet")