klinelens 0.1.0__tar.gz

klinelens-0.1.0/LICENSE

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

klinelens-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: klinelens
+Version: 0.1.0
+Summary: Python client for the K-Line Lens API: Bitcoin order flow, liquidations, large trades, the order book and derivatives.
+Author-email: K-Line Lens <support@klinelens.com>
+License: MIT
+Project-URL: Homepage, https://klinelens.com
+Project-URL: Documentation, https://klinelens.com/api
+Keywords: bitcoin,order flow,liquidations,cvd,crypto,market data,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Dynamic: license-file
+
+# klinelens
+
+The Python client for the [K-Line Lens API](https://klinelens.com/api): Bitcoin taker buying and selling, liquidations, large trades, the order book, funding and open interest, in a few lines.
+
+```bash
+pip install klinelens            # no dependencies
+pip install "klinelens[pandas]"  # adds .to_pandas()
+```
+
+Create a key at [klinelens.com/api](https://klinelens.com/api). The free plan needs no card.
+
+```python
+from klinelens import Client
+
+kl = Client()   # reads KLINELENS_API_KEY; or Client("kll_live_...")
+
+snap = kl.snapshot()
+print(snap["lastHour"]["liquidations"])   # {'longUsd': ..., 'shortUsd': ..., 'count': ...}
+
+flow = kl.flow(window="24h", interval="1h").to_pandas()
+print(flow[["at", "deltaUsd", "cumulativeUsd"]].tail())
+```
+
+## Methods
+
+| Method | Endpoint | What it returns |
+|---|---|---|
+| `read()` | `/v1/read` | The read right now: the lean, how its readings vote, each one's side |
+| `forecast(tf="15m")` | `/v1/forecast` | The forecast model's latest call and its path |
+| `snapshot()` | `/v1/snapshot` | The last hour's flow, liquidations and large trades, the book and derivatives now |
+| `flow(window, interval)` | `/v1/flow` | Taker buys and sells per interval, the delta and its running total (CVD) |
+| `liquidations(window, interval, limit)` | `/v1/liquidations` | Longs and shorts forced closed per interval, and the latest ones |
+| `whales(window, interval, min_usd, limit)` | `/v1/whales` | Trades of $50,000 and up per interval, and the latest ones |
+| `book(levels, window, interval)` | `/v1/book` | The order book now, and its history with `window` |
+| `derivatives(window, interval)` | `/v1/derivatives` | Funding, open interest, mark and index, and their history with `window` |
+| `setup()` | `/v1/setup` | The ledger's open trade, or `None` |
+| `ledger(limit)` | `/v1/ledger` | The ledger's account, totals and latest trades |
+
+`window` is a number and `m`, `h` or `d` (`90m`, `24h`, `7d`). `interval` is one of `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. How far back you can read, the smallest interval and how many events are listed depend on your plan; `result.meta["plan"]` says what yours allows.
+
+## What you get back
+
+Every method returns a `Result`:
+
+- `result.data`: the answer. `result["totals"]` reads from it.
+- `result.meta`: when it was made, the window, any gaps in the record, your plan's limits.
+- `result.quota`: `{"limit": ..., "remaining": ...}` requests for today (UTC).
+- `result.to_pandas()`: the answer's list (points, events, trades, history or path) as a DataFrame, timestamps in UTC. Name one with `to_pandas("events")`.
+
+## Errors
+
+Failures raise a subclass of `klinelens.KlineLensError`, with `.status` and `.message`:
+
+| Error | When |
+|---|---|
+| `BadRequestError` | 400: a parameter is wrong; the message says which |
+| `AuthError` | 401: no key, or not a valid one |
+| `PlanError` | 403: outside your plan (more history, a smaller interval) |
+| `RateLimitError` | 429: today's requests are used up; they reset at 00:00 UTC |
+| `ServiceError` | 5xx or no connection, after two retries |
+
+```python
+from klinelens import Client, PlanError
+
+try:
+    Client().flow(window="30d", interval="1m")
+except PlanError as e:
+    print(e.message)   # "Your plan reads 1 day of history. ..."
+```
+
+## Good to know
+
+- Order flow, liquidations, large trades and the book come from one major exchange's Bitcoin perpetual market. Totals across every exchange are larger.
+- Readings describe the market; they are not financial advice. The ledger places no real orders.
+- The full API reference, and the OpenAPI description at `https://klinelens.com/v1/openapi.json`, are linked from [klinelens.com/api](https://klinelens.com/api).
+
+MIT licence.

klinelens-0.1.0/README.md

@@ -0,0 +1,77 @@
+# klinelens
+
+The Python client for the [K-Line Lens API](https://klinelens.com/api): Bitcoin taker buying and selling, liquidations, large trades, the order book, funding and open interest, in a few lines.
+
+```bash
+pip install klinelens            # no dependencies
+pip install "klinelens[pandas]"  # adds .to_pandas()
+```
+
+Create a key at [klinelens.com/api](https://klinelens.com/api). The free plan needs no card.
+
+```python
+from klinelens import Client
+
+kl = Client()   # reads KLINELENS_API_KEY; or Client("kll_live_...")
+
+snap = kl.snapshot()
+print(snap["lastHour"]["liquidations"])   # {'longUsd': ..., 'shortUsd': ..., 'count': ...}
+
+flow = kl.flow(window="24h", interval="1h").to_pandas()
+print(flow[["at", "deltaUsd", "cumulativeUsd"]].tail())
+```
+
+## Methods
+
+| Method | Endpoint | What it returns |
+|---|---|---|
+| `read()` | `/v1/read` | The read right now: the lean, how its readings vote, each one's side |
+| `forecast(tf="15m")` | `/v1/forecast` | The forecast model's latest call and its path |
+| `snapshot()` | `/v1/snapshot` | The last hour's flow, liquidations and large trades, the book and derivatives now |
+| `flow(window, interval)` | `/v1/flow` | Taker buys and sells per interval, the delta and its running total (CVD) |
+| `liquidations(window, interval, limit)` | `/v1/liquidations` | Longs and shorts forced closed per interval, and the latest ones |
+| `whales(window, interval, min_usd, limit)` | `/v1/whales` | Trades of $50,000 and up per interval, and the latest ones |
+| `book(levels, window, interval)` | `/v1/book` | The order book now, and its history with `window` |
+| `derivatives(window, interval)` | `/v1/derivatives` | Funding, open interest, mark and index, and their history with `window` |
+| `setup()` | `/v1/setup` | The ledger's open trade, or `None` |
+| `ledger(limit)` | `/v1/ledger` | The ledger's account, totals and latest trades |
+
+`window` is a number and `m`, `h` or `d` (`90m`, `24h`, `7d`). `interval` is one of `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. How far back you can read, the smallest interval and how many events are listed depend on your plan; `result.meta["plan"]` says what yours allows.
+
+## What you get back
+
+Every method returns a `Result`:
+
+- `result.data`: the answer. `result["totals"]` reads from it.
+- `result.meta`: when it was made, the window, any gaps in the record, your plan's limits.
+- `result.quota`: `{"limit": ..., "remaining": ...}` requests for today (UTC).
+- `result.to_pandas()`: the answer's list (points, events, trades, history or path) as a DataFrame, timestamps in UTC. Name one with `to_pandas("events")`.
+
+## Errors
+
+Failures raise a subclass of `klinelens.KlineLensError`, with `.status` and `.message`:
+
+| Error | When |
+|---|---|
+| `BadRequestError` | 400: a parameter is wrong; the message says which |
+| `AuthError` | 401: no key, or not a valid one |
+| `PlanError` | 403: outside your plan (more history, a smaller interval) |
+| `RateLimitError` | 429: today's requests are used up; they reset at 00:00 UTC |
+| `ServiceError` | 5xx or no connection, after two retries |
+
+```python
+from klinelens import Client, PlanError
+
+try:
+    Client().flow(window="30d", interval="1m")
+except PlanError as e:
+    print(e.message)   # "Your plan reads 1 day of history. ..."
+```
+
+## Good to know
+
+- Order flow, liquidations, large trades and the book come from one major exchange's Bitcoin perpetual market. Totals across every exchange are larger.
+- Readings describe the market; they are not financial advice. The ledger places no real orders.
+- The full API reference, and the OpenAPI description at `https://klinelens.com/v1/openapi.json`, are linked from [klinelens.com/api](https://klinelens.com/api).
+
+MIT licence.

klinelens-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "klinelens"
+version = "0.1.0"
+description = "Python client for the K-Line Lens API: Bitcoin order flow, liquidations, large trades, the order book and derivatives."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "K-Line Lens", email = "support@klinelens.com" }]
+keywords = ["bitcoin", "order flow", "liquidations", "cvd", "crypto", "market data", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.5"]
+
+[project.urls]
+Homepage = "https://klinelens.com"
+Documentation = "https://klinelens.com/api"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+klinelens = ["py.typed"]

klinelens-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

klinelens-0.1.0/src/klinelens/__init__.py

@@ -0,0 +1,27 @@
+"""K-Line Lens: Bitcoin order flow, liquidations, large trades, the book and
+derivatives, from https://klinelens.com/api."""
+from ._client import DEFAULT_BASE_URL, Client, __version__
+from ._errors import (
+    AuthError,
+    BadRequestError,
+    KlineLensError,
+    NotFoundError,
+    PlanError,
+    RateLimitError,
+    ServiceError,
+)
+from ._result import Result
+
+__all__ = [
+    "Client",
+    "Result",
+    "KlineLensError",
+    "BadRequestError",
+    "AuthError",
+    "PlanError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServiceError",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

klinelens-0.1.0/src/klinelens/_client.py

@@ -0,0 +1,157 @@
+"""The K-Line Lens API client: one method per /v1 endpoint."""
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Mapping, Optional
+
+from ._errors import (
+    AuthError,
+    BadRequestError,
+    KlineLensError,
+    NotFoundError,
+    PlanError,
+    RateLimitError,
+    ServiceError,
+)
+from ._result import Result
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://klinelens.com"
+_RETRY_STATUS = {502, 503, 504}
+_ERRORS = {400: BadRequestError, 401: AuthError, 403: PlanError, 404: NotFoundError, 429: RateLimitError}
+
+
+class Client:
+    """A client for the K-Line Lens API.
+
+    >>> from klinelens import Client
+    >>> kl = Client()                      # reads KLINELENS_API_KEY
+    >>> kl.liquidations(window="1h").data["totals"]
+
+    Every method returns a :class:`Result`: ``.data``, ``.meta``, ``.quota``,
+    and ``.to_pandas()`` when pandas is installed.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+        retries: int = 2,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("KLINELENS_API_KEY")
+        if not key:
+            raise AuthError(401, "No API key. Pass api_key=... or set KLINELENS_API_KEY. Create one at https://klinelens.com/api.")
+        self._key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retries = max(0, int(retries))
+
+    def __repr__(self) -> str:
+        return f"Client(base_url={self.base_url!r})"
+
+    # ------------------------------------------------------------ the read
+
+    def read(self) -> Result:
+        """The read right now: the lean, how its readings vote, each one's side."""
+        return self._get("/v1/read")
+
+    def forecast(self, tf: str = "15m") -> Result:
+        """The forecast model's latest call for ``tf`` (5m, 15m or 1h; Free reads 15m)."""
+        return self._get("/v1/forecast", {"tf": tf})
+
+    # ------------------------------------------------------------ market data
+
+    def snapshot(self) -> Result:
+        """The last hour's flow, liquidations and large trades, the book and derivatives now."""
+        return self._get("/v1/snapshot")
+
+    def flow(self, window: str = "24h", interval: str = "1h") -> Result:
+        """Taker buying and selling per interval, with the running delta (CVD)."""
+        return self._get("/v1/flow", {"window": window, "interval": interval})
+
+    def liquidations(self, window: str = "24h", interval: str = "4h", limit: Optional[int] = None) -> Result:
+        """Longs and shorts forced closed per interval, and the latest single ones."""
+        return self._get("/v1/liquidations", {"window": window, "interval": interval, "limit": limit})
+
+    def whales(
+        self,
+        window: str = "24h",
+        interval: str = "4h",
+        min_usd: Optional[float] = None,
+        limit: Optional[int] = None,
+    ) -> Result:
+        """Large single trades ($50,000 and up, or ``min_usd``) per interval, and the latest ones."""
+        return self._get("/v1/whales", {"window": window, "interval": interval, "min": min_usd, "limit": limit})
+
+    def book(self, levels: int = 20, window: Optional[str] = None, interval: Optional[str] = None) -> Result:
+        """The order book as of the last minute; with ``window``, its history too."""
+        return self._get("/v1/book", {"levels": levels, "window": window, "interval": interval})
+
+    def derivatives(self, window: Optional[str] = None, interval: Optional[str] = None) -> Result:
+        """Funding, open interest, mark and index now; with ``window``, their history too."""
+        return self._get("/v1/derivatives", {"window": window, "interval": interval})
+
+    # ------------------------------------------------------------ the ledger
+
+    def setup(self) -> Result:
+        """The ledger's open trade, or ``data`` None when none is open (``meta['reason']``)."""
+        return self._get("/v1/setup")
+
+    def ledger(self, limit: Optional[int] = None) -> Result:
+        """The ledger's account, totals and latest trades, newest first."""
+        return self._get("/v1/ledger", {"limit": limit})
+
+    # ------------------------------------------------------------ transport
+
+    def _get(self, path: str, params: Optional[Mapping[str, Any]] = None) -> Result:
+        query = {k: v for k, v in (params or {}).items() if v is not None}
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+        headers = {
+            "Authorization": f"Bearer {self._key}",
+            "Accept": "application/json",
+            "User-Agent": f"klinelens-python/{__version__}",
+        }
+        attempt = 0
+        while True:
+            try:
+                req = urllib.request.Request(url, headers=headers, method="GET")
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return Result(_decode(resp.read()), resp.headers)
+            except urllib.error.HTTPError as err:
+                body = _decode(err.read(), strict=False)
+                message = body.get("error") if isinstance(body, dict) else None
+                if err.code in _RETRY_STATUS and attempt < self.retries:
+                    attempt += 1
+                    _pause(attempt)
+                    continue
+                cls = _ERRORS.get(err.code, ServiceError if err.code >= 500 else KlineLensError)
+                raise cls(err.code, message or f"HTTP {err.code}", err.headers) from None
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as err:
+                if attempt < self.retries:
+                    attempt += 1
+                    _pause(attempt)
+                    continue
+                reason = getattr(err, "reason", err)
+                raise ServiceError(None, f"Could not reach {self.base_url}: {reason}") from None
+
+
+def _decode(raw: bytes, strict: bool = True) -> Any:
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        if strict:
+            raise ServiceError(None, "The API answered with something that is not JSON.") from None
+        return None
+
+
+def _pause(attempt: int) -> None:
+    time.sleep(min(8.0, 0.5 * 2 ** (attempt - 1)) + random.random() * 0.25)

klinelens-0.1.0/src/klinelens/_errors.py

@@ -0,0 +1,41 @@
+"""Errors the API answers with, one class per kind."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class KlineLensError(Exception):
+    """An answer that is not data. ``status`` is the HTTP status (None if the API was not reached)."""
+
+    def __init__(self, status: Optional[int], message: str, headers: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.headers = headers
+
+    def __str__(self) -> str:
+        return f"{self.status}: {self.message}" if self.status else self.message
+
+
+class BadRequestError(KlineLensError):
+    """400: a parameter is wrong; the message says which."""
+
+
+class AuthError(KlineLensError):
+    """401: no key, or not a valid one."""
+
+
+class PlanError(KlineLensError):
+    """403: outside your plan (more history, a smaller interval or another timeframe)."""
+
+
+class NotFoundError(KlineLensError):
+    """404: no such endpoint."""
+
+
+class RateLimitError(KlineLensError):
+    """429: today's requests are used up. It resets at 00:00 UTC."""
+
+
+class ServiceError(KlineLensError):
+    """5xx, or the API could not be reached. Retried before it is raised."""

klinelens-0.1.0/src/klinelens/_result.py

@@ -0,0 +1,64 @@
+"""What every call returns: the data, its meta, today's quota, and a table."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+# The list in each answer that makes the natural table, in order of preference.
+_TABLES = ("points", "events", "trades", "history", "path")
+
+
+class Result:
+    """An API answer. ``data`` and ``meta`` are the envelope's two halves;
+    ``result["totals"]`` reads from ``data``."""
+
+    def __init__(self, body: Mapping[str, Any], headers: Any = None) -> None:
+        self.data: Any = body.get("data")
+        self.meta: dict = dict(body.get("meta") or {})
+        limit = _int(headers.get("X-Quota-Limit")) if headers is not None else None
+        remaining = _int(headers.get("X-Quota-Remaining")) if headers is not None else None
+        self.quota = {"limit": limit, "remaining": remaining}
+
+    def __getitem__(self, key: str) -> Any:
+        if not isinstance(self.data, Mapping):
+            raise KeyError(key)
+        return self.data[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default) if isinstance(self.data, Mapping) else default
+
+    def __repr__(self) -> str:
+        keys = list(self.data) if isinstance(self.data, Mapping) else type(self.data).__name__
+        return f"Result(data={keys}, quota={self.quota})"
+
+    def to_pandas(self, table: Optional[str] = None):
+        """The answer's list as a pandas DataFrame: points, events, trades,
+        history or path, whichever it has, or the one named in ``table``.
+        Timestamps become UTC datetimes. Needs ``pip install klinelens[pandas]``."""
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError("to_pandas() needs pandas: pip install klinelens[pandas]") from None
+        data = self.data if isinstance(self.data, Mapping) else {}
+        name = table or next((k for k in _TABLES if isinstance(data.get(k), list)), None)
+        if name is None:
+            # The book's two sides, as price and size.
+            if isinstance(data.get("bids"), list) or isinstance((data.get("now") or {}).get("bids"), list):
+                src = data if "bids" in data else data["now"]
+                rows = [{"side": side, "price": p, "qty": q} for side in ("bids", "asks") for p, q in src.get(side) or []]
+                return pd.DataFrame(rows, columns=["side", "price", "qty"])
+            raise ValueError(f"No table in this answer. Choose one of: {', '.join(k for k, v in data.items() if isinstance(v, list)) or 'none'}")
+        rows = data.get(name)
+        if not isinstance(rows, list):
+            raise ValueError(f"{name!r} is not a list in this answer.")
+        frame = pd.DataFrame(rows)
+        for col in ("at", "openedAt", "closedAt"):
+            if col in frame.columns:
+                frame[col] = pd.to_datetime(frame[col], utc=True)
+        return frame
+
+
+def _int(value: Any) -> Optional[int]:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None

klinelens-0.1.0/src/klinelens.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: klinelens
+Version: 0.1.0
+Summary: Python client for the K-Line Lens API: Bitcoin order flow, liquidations, large trades, the order book and derivatives.
+Author-email: K-Line Lens <support@klinelens.com>
+License: MIT
+Project-URL: Homepage, https://klinelens.com
+Project-URL: Documentation, https://klinelens.com/api
+Keywords: bitcoin,order flow,liquidations,cvd,crypto,market data,api
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Dynamic: license-file
+
+# klinelens
+
+The Python client for the [K-Line Lens API](https://klinelens.com/api): Bitcoin taker buying and selling, liquidations, large trades, the order book, funding and open interest, in a few lines.
+
+```bash
+pip install klinelens            # no dependencies
+pip install "klinelens[pandas]"  # adds .to_pandas()
+```
+
+Create a key at [klinelens.com/api](https://klinelens.com/api). The free plan needs no card.
+
+```python
+from klinelens import Client
+
+kl = Client()   # reads KLINELENS_API_KEY; or Client("kll_live_...")
+
+snap = kl.snapshot()
+print(snap["lastHour"]["liquidations"])   # {'longUsd': ..., 'shortUsd': ..., 'count': ...}
+
+flow = kl.flow(window="24h", interval="1h").to_pandas()
+print(flow[["at", "deltaUsd", "cumulativeUsd"]].tail())
+```
+
+## Methods
+
+| Method | Endpoint | What it returns |
+|---|---|---|
+| `read()` | `/v1/read` | The read right now: the lean, how its readings vote, each one's side |
+| `forecast(tf="15m")` | `/v1/forecast` | The forecast model's latest call and its path |
+| `snapshot()` | `/v1/snapshot` | The last hour's flow, liquidations and large trades, the book and derivatives now |
+| `flow(window, interval)` | `/v1/flow` | Taker buys and sells per interval, the delta and its running total (CVD) |
+| `liquidations(window, interval, limit)` | `/v1/liquidations` | Longs and shorts forced closed per interval, and the latest ones |
+| `whales(window, interval, min_usd, limit)` | `/v1/whales` | Trades of $50,000 and up per interval, and the latest ones |
+| `book(levels, window, interval)` | `/v1/book` | The order book now, and its history with `window` |
+| `derivatives(window, interval)` | `/v1/derivatives` | Funding, open interest, mark and index, and their history with `window` |
+| `setup()` | `/v1/setup` | The ledger's open trade, or `None` |
+| `ledger(limit)` | `/v1/ledger` | The ledger's account, totals and latest trades |
+
+`window` is a number and `m`, `h` or `d` (`90m`, `24h`, `7d`). `interval` is one of `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. How far back you can read, the smallest interval and how many events are listed depend on your plan; `result.meta["plan"]` says what yours allows.
+
+## What you get back
+
+Every method returns a `Result`:
+
+- `result.data`: the answer. `result["totals"]` reads from it.
+- `result.meta`: when it was made, the window, any gaps in the record, your plan's limits.
+- `result.quota`: `{"limit": ..., "remaining": ...}` requests for today (UTC).
+- `result.to_pandas()`: the answer's list (points, events, trades, history or path) as a DataFrame, timestamps in UTC. Name one with `to_pandas("events")`.
+
+## Errors
+
+Failures raise a subclass of `klinelens.KlineLensError`, with `.status` and `.message`:
+
+| Error | When |
+|---|---|
+| `BadRequestError` | 400: a parameter is wrong; the message says which |
+| `AuthError` | 401: no key, or not a valid one |
+| `PlanError` | 403: outside your plan (more history, a smaller interval) |
+| `RateLimitError` | 429: today's requests are used up; they reset at 00:00 UTC |
+| `ServiceError` | 5xx or no connection, after two retries |
+
+```python
+from klinelens import Client, PlanError
+
+try:
+    Client().flow(window="30d", interval="1m")
+except PlanError as e:
+    print(e.message)   # "Your plan reads 1 day of history. ..."
+```
+
+## Good to know
+
+- Order flow, liquidations, large trades and the book come from one major exchange's Bitcoin perpetual market. Totals across every exchange are larger.
+- Readings describe the market; they are not financial advice. The ledger places no real orders.
+- The full API reference, and the OpenAPI description at `https://klinelens.com/v1/openapi.json`, are linked from [klinelens.com/api](https://klinelens.com/api).
+
+MIT licence.

klinelens-0.1.0/src/klinelens.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/klinelens/__init__.py
+src/klinelens/_client.py
+src/klinelens/_errors.py
+src/klinelens/_result.py
+src/klinelens/py.typed
+src/klinelens.egg-info/PKG-INFO
+src/klinelens.egg-info/SOURCES.txt
+src/klinelens.egg-info/dependency_links.txt
+src/klinelens.egg-info/requires.txt
+src/klinelens.egg-info/top_level.txt
+tests/test_client.py

klinelens-0.1.0/src/klinelens.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

klinelens-0.1.0/src/klinelens.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[pandas]
+pandas>=1.5

klinelens-0.1.0/src/klinelens.egg-info/top_level.txt

@@ -0,0 +1 @@
+klinelens

klinelens-0.1.0/tests/test_client.py

@@ -0,0 +1,172 @@
+"""The client against a local server that answers like the API."""
+import json
+import os
+import sys
+import threading
+import types
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+import klinelens  # noqa: E402
+from klinelens import AuthError, BadRequestError, Client, PlanError, RateLimitError, ServiceError  # noqa: E402
+
+SEEN = []          # (path, query, headers) of every request
+SCRIPT = {}        # path -> list of (status, body) answered in turn; the last repeats
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_GET(self):
+        u = urlparse(self.path)
+        SEEN.append((u.path, parse_qs(u.query), dict(self.headers)))
+        queue = SCRIPT.get(u.path) or [(200, {"data": {"path": u.path}, "meta": {"version": "v1"}})]
+        status, body = queue.pop(0) if len(queue) > 1 else queue[0]
+        raw = body if isinstance(body, bytes) else json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("X-Quota-Limit", "100")
+        self.send_header("X-Quota-Remaining", "97")
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def log_message(self, *args):
+        pass
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_port}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        SEEN.clear()
+        SCRIPT.clear()
+        klinelens._client._pause = lambda attempt: None   # no waiting between retries here
+        self.kl = Client("kll_live_test", base_url=self.base)
+
+    def test_key_in_the_header_never_the_url(self):
+        self.kl.read()
+        path, query, headers = SEEN[0]
+        self.assertEqual(path, "/v1/read")
+        self.assertEqual(headers["Authorization"], "Bearer kll_live_test")
+        self.assertNotIn("key", query)
+        self.assertTrue(headers["User-Agent"].startswith("klinelens-python/"))
+
+    def test_key_from_the_environment_or_a_clear_error(self):
+        os.environ["KLINELENS_API_KEY"] = "kll_live_env"
+        try:
+            Client(base_url=self.base).snapshot()
+            self.assertEqual(SEEN[0][2]["Authorization"], "Bearer kll_live_env")
+        finally:
+            del os.environ["KLINELENS_API_KEY"]
+        with self.assertRaises(AuthError):
+            Client(base_url=self.base)
+
+    def test_each_method_asks_its_endpoint_with_its_parameters(self):
+        calls = [
+            (lambda: self.kl.forecast("1h"), "/v1/forecast", {"tf": ["1h"]}),
+            (lambda: self.kl.flow("7d", "4h"), "/v1/flow", {"window": ["7d"], "interval": ["4h"]}),
+            (lambda: self.kl.liquidations("1h", "15m", 10), "/v1/liquidations", {"window": ["1h"], "interval": ["15m"], "limit": ["10"]}),
+            (lambda: self.kl.whales(min_usd=250000), "/v1/whales", {"window": ["24h"], "interval": ["4h"], "min": ["250000"]}),
+            (lambda: self.kl.book(), "/v1/book", {"levels": ["20"]}),
+            (lambda: self.kl.book(5, "2h", "1h"), "/v1/book", {"levels": ["5"], "window": ["2h"], "interval": ["1h"]}),
+            (lambda: self.kl.derivatives(), "/v1/derivatives", {}),
+            (lambda: self.kl.setup(), "/v1/setup", {}),
+            (lambda: self.kl.ledger(5), "/v1/ledger", {"limit": ["5"]}),
+        ]
+        for call, path, query in calls:
+            SEEN.clear()
+            call()
+            self.assertEqual((SEEN[0][0], SEEN[0][1]), (path, query), path)
+
+    def test_result_data_meta_and_quota(self):
+        SCRIPT["/v1/liquidations"] = [(200, {"data": {"totals": {"count": 3}}, "meta": {"interval": "4h"}})]
+        r = self.kl.liquidations()
+        self.assertEqual(r["totals"]["count"], 3)
+        self.assertEqual(r.meta["interval"], "4h")
+        self.assertEqual(r.quota, {"limit": 100, "remaining": 97})
+
+    def test_null_data_is_kept(self):
+        SCRIPT["/v1/setup"] = [(200, {"data": None, "meta": {"reason": "No trade is open right now."}})]
+        r = self.kl.setup()
+        self.assertIsNone(r.data)
+        self.assertEqual(r.meta["reason"], "No trade is open right now.")
+        self.assertIsNone(r.get("entry"))
+
+    def test_errors_by_status(self):
+        for status, cls in [(400, BadRequestError), (401, AuthError), (403, PlanError), (429, RateLimitError)]:
+            SCRIPT["/v1/flow"] = [(status, {"error": f"said {status}"})]
+            with self.assertRaises(cls) as ctx:
+                self.kl.flow()
+            self.assertEqual((ctx.exception.status, ctx.exception.message), (status, f"said {status}"))
+
+    def test_a_restart_is_retried_then_answers(self):
+        SCRIPT["/v1/read"] = [(503, {"error": "restarting"}), (503, {"error": "restarting"}), (200, {"data": {"ok": 1}, "meta": {}})]
+        self.assertEqual(self.kl.read()["ok"], 1)
+        self.assertEqual(len(SEEN), 3)
+
+    def test_a_quota_refusal_is_not_retried(self):
+        SCRIPT["/v1/read"] = [(429, {"error": "used up"})]
+        with self.assertRaises(RateLimitError):
+            self.kl.read()
+        self.assertEqual(len(SEEN), 1)
+
+    def test_retries_run_out(self):
+        SCRIPT["/v1/read"] = [(503, {"error": "down"})]
+        with self.assertRaises(ServiceError):
+            self.kl.read()
+        self.assertEqual(len(SEEN), 3)
+
+    def test_no_server(self):
+        kl = Client("kll_live_test", base_url="http://127.0.0.1:9", retries=0, timeout=2)
+        with self.assertRaises(ServiceError):
+            kl.read()
+
+    def test_to_pandas(self):
+        frames = []
+
+        class FakeFrame:
+            def __init__(self, rows, columns=None):
+                self.rows, self.columns = rows, columns or (list(rows[0]) if rows else [])
+                frames.append(self)
+
+            def __setitem__(self, k, v):
+                self.converted = k
+
+            def __getitem__(self, k):
+                return k
+
+        fake = types.ModuleType("pandas")
+        fake.DataFrame = FakeFrame
+        fake.to_datetime = lambda col, utc: ("utc", col)
+        sys.modules["pandas"] = fake
+        try:
+            SCRIPT["/v1/flow"] = [(200, {"data": {"points": [{"at": "2026-11-12T12:00:00Z", "deltaUsd": 1}], "totals": {}}, "meta": {}})]
+            f = self.kl.flow().to_pandas()
+            self.assertEqual(f.rows[0]["deltaUsd"], 1)
+            self.assertEqual(f.converted, "at")
+            SCRIPT["/v1/book"] = [(200, {"data": {"now": {"bids": [[1, 2]], "asks": [[3, 4]]}, "history": None}, "meta": {}})]
+            b = self.kl.book().to_pandas()
+            self.assertEqual(b.rows, [{"side": "bids", "price": 1, "qty": 2}, {"side": "asks", "price": 3, "qty": 4}])
+            SCRIPT["/v1/read"] = [(200, {"data": {"direction": "long"}, "meta": {}})]
+            with self.assertRaises(ValueError):
+                self.kl.read().to_pandas()
+        finally:
+            del sys.modules["pandas"]
+        try:
+            import pandas  # noqa: F401
+        except ImportError:
+            SCRIPT["/v1/flow"] = [(200, {"data": {"points": []}, "meta": {}})]
+            with self.assertRaises(ImportError):
+                self.kl.flow().to_pandas()
+
+
+if __name__ == "__main__":
+    unittest.main()