depthy-python 0.1.0__py3-none-any.whl

depthy/__init__.py

@@ -0,0 +1,13 @@
+"""Depthy Python SDK — real-time crypto liquidity intelligence."""
+
+from .client import AsyncDepthyClient, DepthyClient
+from .exceptions import AuthError, DepthyError, NotFoundError, RateLimitError
+
+__all__ = [
+    "DepthyClient",
+    "AsyncDepthyClient",
+    "DepthyError",
+    "AuthError",
+    "RateLimitError",
+    "NotFoundError",
+]

depthy/client.py

@@ -0,0 +1,200 @@
+"""Depthy Python SDK — sync and async clients for the Depthy REST API."""
+
+from __future__ import annotations
+
+import httpx
+
+from .exceptions import AuthError, DepthyError, NotFoundError, RateLimitError
+
+DEFAULT_BASE_URL = "https://depthy.io"
+DEFAULT_TIMEOUT = 30
+
+
+def _normalize(symbol: str) -> str:
+    s = symbol.upper().strip()
+    if not s.endswith("-PERP"):
+        s += "-PERP"
+    return s
+
+
+def _handle_error(resp: httpx.Response) -> None:
+    if resp.status_code == 401:
+        raise AuthError("Invalid API key. Get a free key at https://depthy.io", 401)
+    if resp.status_code == 403:
+        raise AuthError("This endpoint requires a Pro key. Upgrade at https://depthy.io", 403)
+    if resp.status_code == 404:
+        raise NotFoundError(f"Resource not found: {resp.url}", 404)
+    if resp.status_code == 429:
+        raise RateLimitError("Rate limit exceeded. Free tier: 30 req/min, 100/day", 429)
+    if resp.status_code >= 500:
+        raise DepthyError("Depthy API temporarily unavailable", resp.status_code)
+    resp.raise_for_status()
+
+
+class DepthyClient:
+    """Synchronous Depthy API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required. Get a free key at https://depthy.io")
+        self._client = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        resp = self._client.get(path, params=params)
+        _handle_error(resp)
+        return resp.json()
+
+    # ── Hyperliquid ────────────────────────────────────────────
+
+    def list_symbols(self, exchange: str = "hyperliquid") -> dict:
+        """List all available trading symbols."""
+        return self._get("/v1/symbols", {"exchange": exchange})
+
+    def get_depth(self, symbol: str, levels: int = 20) -> dict:
+        """Get order book depth and bid/ask imbalance."""
+        return self._get(f"/v1/depth/hyperliquid/{_normalize(symbol)}", {"levels": levels})
+
+    def get_depth_recent(self, symbol: str, minutes: int = 30) -> dict:
+        """Get recent depth snapshots over the last N minutes."""
+        return self._get(
+            f"/v1/depth/hyperliquid/{_normalize(symbol)}/recent", {"minutes": minutes}
+        )
+
+    def get_walls(self, symbol: str, min_size_usd: float = 100000) -> dict:
+        """Find large resting orders (walls) in the order book."""
+        return self._get(
+            f"/v1/walls/hyperliquid/{_normalize(symbol)}", {"min_size_usd": min_size_usd}
+        )
+
+    def get_liquidation_clusters(self, symbol: str) -> dict:
+        """Get liquidation cluster zones."""
+        return self._get(f"/v1/liquidations/hyperliquid/{_normalize(symbol)}/clusters")
+
+    def get_market(self, symbol: str) -> dict:
+        """Get market overview: price, volume, funding, open interest."""
+        return self._get(f"/v1/market/hyperliquid/{_normalize(symbol)}")
+
+    def get_oi_change(self, symbol: str) -> dict:
+        """Get open interest changes over recent time windows."""
+        return self._get("/api/oi/change", {"symbol": _normalize(symbol)})
+
+    def compare_symbols(self, symbols: list[str]) -> dict:
+        """Compare depth and liquidity across symbols. Requires Pro key."""
+        return self._get("/v1/compare/hyperliquid", {"symbols": ",".join(symbols)})
+
+    # ── Polymarket ─────────────────────────────────────────────
+
+    def list_pm_markets(self, market_type: str = "", limit: int = 20) -> dict:
+        """List active Polymarket prediction markets."""
+        params = {"limit": limit}
+        if market_type:
+            params["market_type"] = market_type
+        return self._get("/v1/polymarket/markets/active", params)
+
+    def get_pm_signals(self, limit: int = 10) -> dict:
+        """Get latest Polymarket trading signals."""
+        return self._get("/v1/pm/signals/latest", {"limit": limit})
+
+    def get_pm_top_wallets(self, limit: int = 10) -> dict:
+        """Get top-performing Polymarket wallets by profit."""
+        return self._get("/v1/pm/wallets/top", {"limit": limit})
+
+
+class AsyncDepthyClient:
+    """Asynchronous Depthy API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required. Get a free key at https://depthy.io")
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def _get(self, path: str, params: dict | None = None) -> dict:
+        resp = await self._client.get(path, params=params)
+        _handle_error(resp)
+        return resp.json()
+
+    # ── Hyperliquid ────────────────────────────────────────────
+
+    async def list_symbols(self, exchange: str = "hyperliquid") -> dict:
+        return await self._get("/v1/symbols", {"exchange": exchange})
+
+    async def get_depth(self, symbol: str, levels: int = 20) -> dict:
+        return await self._get(
+            f"/v1/depth/hyperliquid/{_normalize(symbol)}", {"levels": levels}
+        )
+
+    async def get_depth_recent(self, symbol: str, minutes: int = 30) -> dict:
+        return await self._get(
+            f"/v1/depth/hyperliquid/{_normalize(symbol)}/recent", {"minutes": minutes}
+        )
+
+    async def get_walls(self, symbol: str, min_size_usd: float = 100000) -> dict:
+        return await self._get(
+            f"/v1/walls/hyperliquid/{_normalize(symbol)}", {"min_size_usd": min_size_usd}
+        )
+
+    async def get_liquidation_clusters(self, symbol: str) -> dict:
+        return await self._get(
+            f"/v1/liquidations/hyperliquid/{_normalize(symbol)}/clusters"
+        )
+
+    async def get_market(self, symbol: str) -> dict:
+        return await self._get(f"/v1/market/hyperliquid/{_normalize(symbol)}")
+
+    async def get_oi_change(self, symbol: str) -> dict:
+        return await self._get("/api/oi/change", {"symbol": _normalize(symbol)})
+
+    async def compare_symbols(self, symbols: list[str]) -> dict:
+        return await self._get(
+            "/v1/compare/hyperliquid", {"symbols": ",".join(symbols)}
+        )
+
+    # ── Polymarket ─────────────────────────────────────────────
+
+    async def list_pm_markets(self, market_type: str = "", limit: int = 20) -> dict:
+        params = {"limit": limit}
+        if market_type:
+            params["market_type"] = market_type
+        return await self._get("/v1/polymarket/markets/active", params)
+
+    async def get_pm_signals(self, limit: int = 10) -> dict:
+        return await self._get("/v1/pm/signals/latest", {"limit": limit})
+
+    async def get_pm_top_wallets(self, limit: int = 10) -> dict:
+        return await self._get("/v1/pm/wallets/top", {"limit": limit})

depthy/exceptions.py

@@ -0,0 +1,24 @@
+"""Depthy SDK exceptions."""
+
+
+class DepthyError(Exception):
+    """Base exception for Depthy SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class AuthError(DepthyError):
+    """Invalid or missing API key."""
+    pass
+
+
+class RateLimitError(DepthyError):
+    """Rate limit exceeded."""
+    pass
+
+
+class NotFoundError(DepthyError):
+    """Resource not found."""
+    pass

depthy_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: depthy-python
+Version: 0.1.0
+Summary: Python SDK for Depthy — real-time crypto liquidity intelligence
+Project-URL: Homepage, https://depthy.io
+Project-URL: Documentation, https://depthy.io/api-docs
+Project-URL: Repository, https://github.com/depthy-io/depthy-python
+Author-email: Depthy <hello@depthy.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crypto,hyperliquid,liquidity,order-book,polymarket,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# Depthy Python SDK
+
+Python client for the [Depthy](https://depthy.io) API — real-time crypto order book depth, liquidity walls, liquidation clusters, and Polymarket signals.
+
+## Install
+
+```bash
+pip install depthy-python
+```
+
+## Quick Start
+
+```python
+from depthy import DepthyClient
+
+client = DepthyClient(api_key="dk_live_your_key_here")
+
+# List available symbols
+symbols = client.list_symbols()
+
+# Order book depth
+depth = client.get_depth("BTC")
+
+# Liquidity walls
+walls = client.get_walls("ETH", min_size_usd=200000)
+
+# Liquidation clusters
+clusters = client.get_liquidation_clusters("SOL")
+
+# Market overview
+market = client.get_market("BTC")
+
+# Open interest changes
+oi = client.get_oi_change("BTC")
+
+# Compare multiple symbols (Pro key required)
+comparison = client.compare_symbols(["BTC", "ETH", "SOL"])
+```
+
+## Async Usage
+
+```python
+from depthy import AsyncDepthyClient
+
+async with AsyncDepthyClient(api_key="dk_live_your_key_here") as client:
+    depth = await client.get_depth("BTC")
+    walls = await client.get_walls("ETH")
+```
+
+## Polymarket
+
+```python
+# Active prediction markets
+markets = client.list_pm_markets(market_type="crypto_15m")
+
+# Smart-money signals
+signals = client.get_pm_signals(limit=10)
+
+# Top wallets by profit
+wallets = client.get_pm_top_wallets(limit=5)
+```
+
+## Error Handling
+
+```python
+from depthy import DepthyClient, AuthError, RateLimitError, NotFoundError
+
+client = DepthyClient(api_key="dk_live_...")
+
+try:
+    depth = client.get_depth("BTC")
+except AuthError:
+    print("Check your API key")
+except RateLimitError:
+    print("Slow down — free tier: 30 req/min")
+except NotFoundError:
+    print("Symbol not found")
+```
+
+## API Methods
+
+| Method | Description | Free Tier |
+|---|---|---|
+| `list_symbols()` | List tradable symbols | Yes |
+| `get_depth(symbol)` | Order book depth & imbalance | Yes (T1) |
+| `get_depth_recent(symbol)` | Depth snapshots over time | Yes (T1) |
+| `get_walls(symbol)` | Large resting orders | Yes (T1) |
+| `get_liquidation_clusters(symbol)` | Liquidation risk zones | Yes (T1) |
+| `get_market(symbol)` | Price, volume, funding, OI | Yes (T1) |
+| `get_oi_change(symbol)` | Open interest changes | Yes |
+| `compare_symbols(symbols)` | Multi-symbol comparison | Pro+ |
+| `list_pm_markets()` | Polymarket markets | Yes |
+| `get_pm_signals()` | Smart-money signals | Yes |
+| `get_pm_top_wallets()` | Top wallets by profit | Yes |
+
+## Get an API Key
+
+Sign up for a free key at [depthy.io](https://depthy.io).
+
+## Links
+
+- [MCP Server](https://github.com/depthy-io/depthy-mcp) — For Claude Desktop, Cursor, etc.
+- [API Docs](https://depthy.io/api-docs) — Full endpoint reference
+
+## License
+
+MIT

depthy_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+depthy/__init__.py,sha256=0MyYyPhue7j3wdRRgMcDluxpA9xsnL39l7vCuAWYXfQ,339
+depthy/client.py,sha256=OObrnpm6VQf61bRqxaYO2P5vXD_pQHu09fPD9AlXfrc,7734
+depthy/exceptions.py,sha256=CmEGhS6SCtaVZ3h9-FguAEJQRMaGfUmxe4OA9Hh76cc,484
+depthy_python-0.1.0.dist-info/METADATA,sha256=Zi_GSHQrFJgjWL-lnuVvhBtZeEQsTbnQbSpQ9Ns5H_w,3446
+depthy_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+depthy_python-0.1.0.dist-info/licenses/LICENSE,sha256=__w8pkSfkWSCMHTk7FflzEl_EgIMWeVXjIfW1sbm7LY,1063
+depthy_python-0.1.0.dist-info/RECORD,,

depthy_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

depthy_python-0.1.0.dist-info/licenses/LICENSE

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