kalshieye 0.2.1__tar.gz

kalshieye-0.2.1/LICENSE

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

kalshieye-0.2.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: kalshieye
+Version: 0.2.1
+Summary: Download Kalshi Eye flat files (order book, book snapshots, top of book, bars, trades, spot, markets, settlements) and load them into pandas or Polars.
+License-Expression: MIT
+Project-URL: Homepage, https://kalshieye.com
+Project-URL: Documentation, https://kalshieye.com/docs/bulk/
+Project-URL: Source, https://github.com/KalshiEye/kalshieye-python
+Keywords: kalshi,prediction markets,order book,market data,parquet
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == "pandas"
+Requires-Dist: pyarrow>=14; extra == "pandas"
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == "polars"
+Dynamic: license-file
+
+# kalshieye
+
+Python client for Kalshi Eye flat files: daily Parquet for the order book (`book_l2`), 1-second top-10 book snapshots (`book_snap_1s`), top of book (`bbo`), one-minute bars (`bbo_1m`), trades, crypto spot (`spot`), and the reference tables (`markets`, `settlements`, `series`, `incidents`).
+
+```bash
+pip install "kalshieye[pandas]"      # or kalshieye[polars], or plain kalshieye
+export KALSHIEYE_API_KEY=clab_...     # create one under API keys
+```
+
+```python
+from kalshieye import Client, replay_book
+
+kx = Client()
+kx.datasets()                                             # schemas, coverage, required plan
+kx.estimate(["bbo_1m", "trades"], "2026-10-12", "2026-10-18", series=["KXBTC*"])
+
+kx.download(["bbo_1m", "trades"], "2026-10-12", "2026-10-18",
+            series=["KXBTC*"], dest="data", progress=True)
+
+df = kx.load("bbo_1m", "2026-10-12", "2026-10-18", series="KXBTC15M")
+fills = kx.load("trades", "2026-10-12", "2026-10-12", tickers=["KXBTC15M-26OCT121545-45"])
+
+# Rebuild the book from book_l2 rows
+book = kx.load("book_l2", "2026-10-12", "2026-10-12", tickers=["KXBTC15M-26OCT121545-45"])
+for ts, ticker, bids, asks in replay_book(book):
+    ...
+
+# One event in one zip: book, snapshots, trades, spot, metadata.json, settlement.json
+kx.bundle("KXBTC15M-26OCT121545")
+
+# CSV.gz copy of a single file
+f = next(kx.files("trades", "2026-10-12", "2026-10-12", series="KXBTC15M"))
+kx.csv(f["key"])
+
+# S3 access (paid plans): a read-only key for aws s3 sync, rclone, DuckDB, boto3
+key = kx.create_s3_key("laptop")
+print(key["snippets"]["aws_cli"])
+```
+
+- Files land under `dest` in the lake layout (`bbo_1m/date=2026-10-12/series=KXBTC15M/...parquet`), so DuckDB, Polars, and Spark can read the folder as a hive-partitioned dataset. `spot` is partitioned by `asset=` instead of `series=`.
+- Every file is checked against its sha256. Files already on disk are skipped and do not count toward your monthly download allowance.
+- `series` accepts wildcards (`KXBTC*`). `categories` filters by archive category (`crypto`, `politics`, ...). `tickers` picks the series files holding those markets, and `load` keeps only their rows.
+- `bundle`, `csv`, and `replay` are built on the server the first time; the client waits for them.
+- Errors raise `kalshieye.ApiError`. Use `err.code` to tell plan limits (`plan_required`, `history_limited`, `download_quota`) apart.
+
+## Without an account
+
+`replay_book` works on any `book_l2` rows, including the free one-day sample on Hugging Face ([KalshiEye/kalshi-order-book-sample](https://huggingface.co/datasets/KalshiEye/kalshi-order-book-sample)), which DuckDB reads in place:
+
+```python
+# pip install "kalshieye[pandas]" duckdb
+import duckdb
+from kalshieye import replay_book
+
+# Bills vs Rams, YES if Buffalo wins: every book change up to 11 PM Eastern
+book = duckdb.sql("""
+  SELECT * FROM 'hf://datasets/KalshiEye/kalshi-order-book-sample/kalshieye-data/book_l2/*/series=KXNFLGAME/*.parquet'
+  WHERE ticker = 'KXNFLGAME-26OCT12BUFLAR-BUF'
+    AND ts_recv::TIMESTAMPTZ <= '2026-10-13 03:00:00+00'::TIMESTAMPTZ
+  ORDER BY ts_recv, seq
+""").df()
+
+*_, (ts, ticker, bids, asks) = replay_book(book, levels=3)
+print(bids)  # [(0.51, 155253.51), (0.5, 405328.0), (0.49, 15126.0)]
+print(asks)  # [(0.52, 960851.07), (0.53, 862817.41), (0.54, 113351.03)]
+```
+
+More runnable examples (a backtest, spreads and depth, calibration) are in [KalshiEye/kalshieye-examples](https://github.com/KalshiEye/kalshieye-examples). Every column is described in the [data dictionary](https://kalshieye.com/docs/datasets/).

kalshieye-0.2.1/README.md

@@ -0,0 +1,68 @@
+# kalshieye
+
+Python client for Kalshi Eye flat files: daily Parquet for the order book (`book_l2`), 1-second top-10 book snapshots (`book_snap_1s`), top of book (`bbo`), one-minute bars (`bbo_1m`), trades, crypto spot (`spot`), and the reference tables (`markets`, `settlements`, `series`, `incidents`).
+
+```bash
+pip install "kalshieye[pandas]"      # or kalshieye[polars], or plain kalshieye
+export KALSHIEYE_API_KEY=clab_...     # create one under API keys
+```
+
+```python
+from kalshieye import Client, replay_book
+
+kx = Client()
+kx.datasets()                                             # schemas, coverage, required plan
+kx.estimate(["bbo_1m", "trades"], "2026-10-12", "2026-10-18", series=["KXBTC*"])
+
+kx.download(["bbo_1m", "trades"], "2026-10-12", "2026-10-18",
+            series=["KXBTC*"], dest="data", progress=True)
+
+df = kx.load("bbo_1m", "2026-10-12", "2026-10-18", series="KXBTC15M")
+fills = kx.load("trades", "2026-10-12", "2026-10-12", tickers=["KXBTC15M-26OCT121545-45"])
+
+# Rebuild the book from book_l2 rows
+book = kx.load("book_l2", "2026-10-12", "2026-10-12", tickers=["KXBTC15M-26OCT121545-45"])
+for ts, ticker, bids, asks in replay_book(book):
+    ...
+
+# One event in one zip: book, snapshots, trades, spot, metadata.json, settlement.json
+kx.bundle("KXBTC15M-26OCT121545")
+
+# CSV.gz copy of a single file
+f = next(kx.files("trades", "2026-10-12", "2026-10-12", series="KXBTC15M"))
+kx.csv(f["key"])
+
+# S3 access (paid plans): a read-only key for aws s3 sync, rclone, DuckDB, boto3
+key = kx.create_s3_key("laptop")
+print(key["snippets"]["aws_cli"])
+```
+
+- Files land under `dest` in the lake layout (`bbo_1m/date=2026-10-12/series=KXBTC15M/...parquet`), so DuckDB, Polars, and Spark can read the folder as a hive-partitioned dataset. `spot` is partitioned by `asset=` instead of `series=`.
+- Every file is checked against its sha256. Files already on disk are skipped and do not count toward your monthly download allowance.
+- `series` accepts wildcards (`KXBTC*`). `categories` filters by archive category (`crypto`, `politics`, ...). `tickers` picks the series files holding those markets, and `load` keeps only their rows.
+- `bundle`, `csv`, and `replay` are built on the server the first time; the client waits for them.
+- Errors raise `kalshieye.ApiError`. Use `err.code` to tell plan limits (`plan_required`, `history_limited`, `download_quota`) apart.
+
+## Without an account
+
+`replay_book` works on any `book_l2` rows, including the free one-day sample on Hugging Face ([KalshiEye/kalshi-order-book-sample](https://huggingface.co/datasets/KalshiEye/kalshi-order-book-sample)), which DuckDB reads in place:
+
+```python
+# pip install "kalshieye[pandas]" duckdb
+import duckdb
+from kalshieye import replay_book
+
+# Bills vs Rams, YES if Buffalo wins: every book change up to 11 PM Eastern
+book = duckdb.sql("""
+  SELECT * FROM 'hf://datasets/KalshiEye/kalshi-order-book-sample/kalshieye-data/book_l2/*/series=KXNFLGAME/*.parquet'
+  WHERE ticker = 'KXNFLGAME-26OCT12BUFLAR-BUF'
+    AND ts_recv::TIMESTAMPTZ <= '2026-10-13 03:00:00+00'::TIMESTAMPTZ
+  ORDER BY ts_recv, seq
+""").df()
+
+*_, (ts, ticker, bids, asks) = replay_book(book, levels=3)
+print(bids)  # [(0.51, 155253.51), (0.5, 405328.0), (0.49, 15126.0)]
+print(asks)  # [(0.52, 960851.07), (0.53, 862817.41), (0.54, 113351.03)]
+```
+
+More runnable examples (a backtest, spreads and depth, calibration) are in [KalshiEye/kalshieye-examples](https://github.com/KalshiEye/kalshieye-examples). Every column is described in the [data dictionary](https://kalshieye.com/docs/datasets/).

kalshieye-0.2.1/kalshieye/__init__.py

@@ -0,0 +1,7 @@
+"""Kalshi Eye flat-file client."""
+
+from kalshieye.book import Book, replay_book
+from kalshieye.client import ApiError, Client
+
+__all__ = ["ApiError", "Book", "Client", "replay_book"]
+__version__ = "0.2.1"

kalshieye-0.2.1/kalshieye/book.py

@@ -0,0 +1,97 @@
+"""Rebuild Kalshi order books from ``book_l2`` rows.
+
+    from kalshieye import replay_book
+    for ts, ticker, bids, asks in replay_book(df, ticker="KXBTC15M-26OCT121545-45"):
+        ...  # bids/asks: [(price, size), ...] best first, YES terms
+
+Kalshi books are bids only. A NO bid at p is a YES ask at 1 - p, so asks here
+are derived from the NO side.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Iterator
+
+
+class Book:
+    """One ticker's book. ``apply`` takes book_l2 rows in file order."""
+
+    def __init__(self) -> None:
+        self.yes: dict[float, float] = {}
+        self.no: dict[float, float] = {}
+        self._snap_ts: Any = None
+
+    def apply(self, row: dict[str, Any]) -> None:
+        side, price, size = row.get("side"), row.get("price"), row.get("size")
+        if row.get("is_snapshot"):
+            if row.get("ts_recv") != self._snap_ts:
+                self.yes.clear()
+                self.no.clear()
+                self._snap_ts = row.get("ts_recv")
+            if side is None or price is None:
+                return
+            book = self.yes if side == "yes" else self.no
+            if size and size > 0:
+                book[float(price)] = float(size)
+            else:
+                book.pop(float(price), None)
+            return
+        self._snap_ts = None
+        if side is None or price is None or size is None:
+            return
+        book = self.yes if side == "yes" else self.no
+        p = float(price)
+        # Sizes are fractional; rounding keeps float residue from leaving a phantom level.
+        left = round(book.get(p, 0.0) + float(size), 6)
+        if left > 0:
+            book[p] = left
+        else:
+            book.pop(p, None)
+
+    def bids(self, levels: int = 10) -> list[tuple[float, float]]:
+        return sorted(self.yes.items(), reverse=True)[:levels]
+
+    def asks(self, levels: int = 10) -> list[tuple[float, float]]:
+        return [(round(1.0 - p, 6), s) for p, s in sorted(self.no.items(), reverse=True)[:levels]]
+
+    def best(self) -> tuple[float | None, float | None]:
+        b = max(self.yes) if self.yes else None
+        a = round(1.0 - max(self.no), 6) if self.no else None
+        return b, a
+
+
+def _rows(data: Any) -> Iterable[dict[str, Any]]:
+    if hasattr(data, "to_pylist"):
+        return data.to_pylist()
+    if hasattr(data, "to_dicts"):
+        return data.to_dicts()
+    if hasattr(data, "to_dict") and hasattr(data, "columns"):
+        return data.to_dict("records")
+    return data
+
+
+def replay_book(
+    data: Any, *, ticker: str | None = None, levels: int = 10
+) -> Iterator[tuple[Any, str, list[tuple[float, float]], list[tuple[float, float]]]]:
+    """Yield ``(ts_recv, ticker, bids, asks)`` after each book message.
+
+    ``data`` is a pandas or polars DataFrame, a pyarrow Table, or an iterable of
+    dicts with the book_l2 columns. Rows of one message share ts_recv; the state
+    is yielded once the message is fully applied.
+    """
+    books: dict[str, Book] = {}
+    pending: tuple[Any, str] | None = None
+    want = ticker.upper() if ticker else None
+    for row in _rows(data):
+        t = str(row.get("ticker") or "")
+        if want and t.upper() != want:
+            continue
+        key = (row.get("ts_recv"), t)
+        if pending is not None and key != pending:
+            b = books[pending[1]]
+            yield pending[0], pending[1], b.bids(levels), b.asks(levels)
+        books.setdefault(t, Book()).apply(row)
+        pending = key
+    if pending is not None:
+        b = books[pending[1]]
+        yield pending[0], pending[1], b.bids(levels), b.asks(levels)

kalshieye-0.2.1/kalshieye/client.py

@@ -0,0 +1,406 @@
+"""Small, dependency-free client for the Kalshi Eye data API.
+
+    from kalshieye import Client
+
+    kx = Client()                     # reads KALSHIEYE_API_KEY
+    kx.estimate(["bbo_1m"], "2026-10-01", "2026-10-07", series=["KXBTC*"])
+    paths = kx.download(["bbo_1m"], "2026-10-01", "2026-10-07", series=["KXBTC*"], dest="data")
+    df = kx.load("bbo_1m", "2026-10-01", "2026-10-07", series=["KXBTC15M"])   # pandas
+    df = kx.load("trades", "2026-10-12", "2026-10-12", tickers=["KXBTC15M-26OCT121545-45"])
+    zip_path = kx.bundle("KXBTC15M-26OCT121545")      # one event: book, trades, spot, settlement
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Callable, Iterable, Iterator, Sequence
+
+DEFAULT_BASE_URL = "https://kalshieye.com"
+_LINK_BATCH = 200
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, detail: Any) -> None:
+        self.status = status
+        self.detail = detail
+        if isinstance(detail, dict):
+            message = detail.get("message") or json.dumps(detail)
+        else:
+            message = str(detail)
+        super().__init__(f"{status}: {message}")
+
+    @property
+    def code(self) -> str | None:
+        return self.detail.get("code") if isinstance(self.detail, dict) else None
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _as_list(value: str | Iterable[str] | None) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    return [str(v) for v in value]
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 120.0,
+        poll_interval: float = 2.0,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("KALSHIEYE_API_KEY")
+        self.base_url = (base_url or os.environ.get("KALSHIEYE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.poll_interval = poll_interval
+
+    # ------------------------------------------------------------------ transport
+
+    def _request(self, method: str, path: str, *, params: dict[str, Any] | None = None, body: Any = None) -> Any:
+        url = self.base_url + path
+        if params:
+            pairs: list[tuple[str, str]] = []
+            for k, v in params.items():
+                if v is None:
+                    continue
+                for item in v if isinstance(v, (list, tuple)) else [v]:
+                    pairs.append((k, str(item).lower() if isinstance(item, bool) else str(item)))
+            if pairs:
+                url += "?" + urllib.parse.urlencode(pairs)
+        headers = {"Accept": "application/json", "User-Agent": "kalshieye-python/0.2"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                raw = res.read()
+        except urllib.error.HTTPError as exc:
+            text = exc.read().decode("utf-8", errors="replace")
+            try:
+                detail = json.loads(text).get("detail", text)
+            except (json.JSONDecodeError, AttributeError):
+                detail = text
+            raise ApiError(exc.code, detail) from None
+        return json.loads(raw) if raw else None
+
+    def _fetch(self, url: str, dest: Path) -> None:
+        with urllib.request.urlopen(url, timeout=self.timeout) as res, dest.open("wb") as fh:
+            shutil.copyfileobj(res, fh, length=1 << 20)
+
+    def _need_key(self) -> None:
+        if not self.api_key:
+            raise ApiError(401, "Set KALSHIEYE_API_KEY or pass api_key= (create a key under API keys).")
+
+    def _poll(self, call: Callable[[], dict[str, Any]], *, wait: float) -> dict[str, Any]:
+        """Repeat ``call`` while the server reports ``building``."""
+        deadline = time.monotonic() + wait
+        while True:
+            out = call()
+            status = out.get("status")
+            if status == "error":
+                raise ApiError(500, out.get("error") or "build failed")
+            if status != "building" or time.monotonic() >= deadline:
+                return out
+            time.sleep(self.poll_interval)
+
+    def _save(self, f: dict[str, Any], dest: Path) -> Path:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        tmp = dest.with_name(dest.name + ".part")
+        self._fetch(f["url"], tmp)
+        tmp.replace(dest)
+        return dest
+
+    # ------------------------------------------------------------------ catalog
+
+    def datasets(self) -> list[dict[str, Any]]:
+        """Every dataset with columns, coverage, required plan, and sample links."""
+        return self._request("GET", "/api/v1/datasets")["datasets"]
+
+    def dataset(self, dataset_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/datasets/{dataset_id}")
+
+    def series(self, dataset_id: str, q: str | None = None, *, limit: int = 500) -> list[dict[str, Any]]:
+        """Per-series coverage (days, rows, bytes, first/last date) for a dataset."""
+        out: list[dict[str, Any]] = []
+        offset = 0
+        while True:
+            page = self._request(
+                "GET",
+                f"/api/v1/datasets/{dataset_id}/series",
+                params={"q": q, "offset": offset, "limit": min(limit, 500)},
+            )
+            out.extend(page["series"])
+            offset += len(page["series"])
+            if not page["series"] or offset >= page["total"]:
+                return out
+
+    def plan(self) -> dict[str, Any]:
+        self._need_key()
+        return self._request("GET", "/api/v1/plan")
+
+    # ------------------------------------------------------------------ selection
+
+    @staticmethod
+    def _selection(
+        datasets: str | Sequence[str],
+        start_date: str,
+        end_date: str,
+        series: str | Iterable[str] | None,
+        categories: str | Iterable[str] | None,
+        tickers: str | Iterable[str] | None = None,
+    ) -> dict[str, Any]:
+        return {
+            "datasets": _as_list(datasets),
+            "start_date": str(start_date),
+            "end_date": str(end_date),
+            "series": _as_list(series),
+            "categories": _as_list(categories),
+            "tickers": [t.upper() for t in _as_list(tickers)],
+        }
+
+    def estimate(
+        self,
+        datasets: str | Sequence[str],
+        start_date: str,
+        end_date: str,
+        *,
+        series: str | Iterable[str] | None = None,
+        categories: str | Iterable[str] | None = None,
+        tickers: str | Iterable[str] | None = None,
+    ) -> dict[str, Any]:
+        """Files, rows, and bytes for a selection, plus what your plan and allowance cover."""
+        return self._request(
+            "POST",
+            "/api/v1/requests/estimate",
+            body=self._selection(datasets, start_date, end_date, series, categories, tickers),
+        )
+
+    def files(
+        self,
+        datasets: str | Sequence[str],
+        start_date: str,
+        end_date: str,
+        *,
+        series: str | Iterable[str] | None = None,
+        categories: str | Iterable[str] | None = None,
+        tickers: str | Iterable[str] | None = None,
+        page_size: int = 500,
+    ) -> Iterator[dict[str, Any]]:
+        """Yield file entries (dataset, date, series, key, path, rows, bytes, sha256). No links, no quota.
+
+        ``tickers`` selects the series files that hold those markets; the files
+        themselves hold the whole series.
+        """
+        self._need_key()
+        sel = self._selection(datasets, start_date, end_date, series, categories, tickers)
+        cursor: str | None = None
+        while True:
+            page = self._request(
+                "GET",
+                "/api/v1/files",
+                params={
+                    "dataset": sel["datasets"],
+                    "start_date": sel["start_date"],
+                    "end_date": sel["end_date"],
+                    "series": sel["series"],
+                    "category": sel["categories"],
+                    "ticker": sel["tickers"],
+                    "cursor": cursor,
+                    "limit": page_size,
+                },
+            )
+            yield from page["files"]
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+    def links(self, keys: Sequence[str]) -> list[dict[str, Any]]:
+        """Signed links (valid one hour) for file keys. New files count toward your monthly GB."""
+        self._need_key()
+        out: list[dict[str, Any]] = []
+        for i in range(0, len(keys), _LINK_BATCH):
+            out.extend(self._request("POST", "/api/v1/files/links", body={"keys": list(keys[i : i + _LINK_BATCH])})["files"])
+        return out
+
+    def download(
+        self,
+        datasets: str | Sequence[str],
+        start_date: str,
+        end_date: str,
+        *,
+        series: str | Iterable[str] | None = None,
+        categories: str | Iterable[str] | None = None,
+        tickers: str | Iterable[str] | None = None,
+        dest: str | Path = "kalshieye-data",
+        progress: bool = False,
+    ) -> list[Path]:
+        """Download a selection into ``dest`` (lake layout), verify sha256, skip files already there."""
+        root = Path(dest)
+        entries = list(
+            self.files(datasets, start_date, end_date, series=series, categories=categories, tickers=tickers)
+        )
+        paths: list[Path] = []
+        need: list[dict[str, Any]] = []
+        for f in entries:
+            p = root / f["path"]
+            paths.append(p)
+            if not (p.is_file() and (not f.get("sha256") or _sha256(p) == f["sha256"])):
+                need.append(f)
+        for f in self.links([f["key"] for f in need]):
+            p = root / f["path"]
+            p.parent.mkdir(parents=True, exist_ok=True)
+            tmp = p.with_name(p.name + ".part")
+            self._fetch(f["url"], tmp)
+            if f.get("sha256") and _sha256(tmp) != f["sha256"]:
+                tmp.unlink()
+                raise ApiError(0, f"checksum mismatch: {f['path']}")
+            tmp.replace(p)
+            if progress:
+                print(f"{f['path']}  {f['bytes'] / 1e6:.1f} MB")
+        return paths
+
+    def load(
+        self,
+        dataset: str,
+        start_date: str,
+        end_date: str,
+        *,
+        series: str | Iterable[str] | None = None,
+        categories: str | Iterable[str] | None = None,
+        tickers: str | Iterable[str] | None = None,
+        dest: str | Path = "kalshieye-data",
+        engine: str = "pandas",
+    ):
+        """Download (if needed) and load one dataset: engine is "pandas", "polars", or "arrow".
+
+        With ``tickers``, only those markets' rows are kept.
+        """
+        if engine not in ("pandas", "polars", "arrow"):
+            raise ValueError("engine must be pandas, polars, or arrow")
+        want = sorted({t.upper() for t in _as_list(tickers)})
+        paths = self.download(
+            dataset, start_date, end_date, series=series, categories=categories, tickers=want or None, dest=dest
+        )
+        import pyarrow as pa
+        import pyarrow.compute as pc
+        import pyarrow.parquet as pq
+
+        tables = []
+        for p in paths:
+            t = pq.read_table(p)
+            if want and "ticker" in t.column_names:
+                col = t.column("ticker")
+                if pa.types.is_dictionary(col.type):
+                    col = col.cast(pa.string())
+                t = t.filter(pc.is_in(col, value_set=pa.array(want)))
+            tables.append(t)
+        table = pa.concat_tables(tables, promote_options="default") if tables else pa.table({})
+        if engine == "polars":
+            import polars as pl
+
+            return pl.from_arrow(table) if tables else pl.DataFrame()
+        return table if engine == "arrow" else table.to_pandas()
+
+    # ------------------------------------------------------------------ derived files
+
+    def csv(
+        self,
+        key: str,
+        *,
+        tickers: str | Iterable[str] | None = None,
+        dest: str | Path = "kalshieye-data",
+        wait: float = 600.0,
+    ) -> Path:
+        """A gzipped CSV copy of one file from ``files()``, optionally cut to ``tickers``."""
+        self._need_key()
+        body = {"key": key, "tickers": [t.upper() for t in _as_list(tickers)]}
+        out = self._poll(lambda: self._request("POST", "/api/v1/files/csv", body=body), wait=wait)
+        if out.get("status") != "ready":
+            raise ApiError(504, "CSV is still being built; call again later.")
+        f = out["file"]
+        rel = f["path"][: -len(".parquet")] if f["path"].endswith(".parquet") else f["path"]
+        suffix = ".tickers.csv.gz" if body["tickers"] else ".csv.gz"
+        return self._save(f, Path(dest) / (rel + suffix))
+
+    def bundle(self, event: str, *, dest: str | Path = "kalshieye-bundles", wait: float = 900.0) -> Path:
+        """Zip of one Kalshi event: book_l2, book_snap_1s, bbo, trades, spot (what your
+        plan includes), plus metadata.json and settlement.json."""
+        self._need_key()
+        eid = event.strip().upper()
+        out = self._poll(lambda: self._request("POST", f"/api/v1/events/{urllib.parse.quote(eid)}/bundle"), wait=wait)
+        if out.get("status") != "ready":
+            raise ApiError(504, "Bundle is still being built; call again later.")
+        return self._save(out["file"], Path(dest) / out["file"]["filename"])
+
+    def replay(self, ticker: str, *, date: str | None = None, wait: float = 300.0) -> dict[str, Any]:
+        """Top-10 book frames (1s, thinned to at most 3600) and trades for one market-day."""
+        self._need_key()
+        params = {"date": date} if date else None
+        path = f"/api/v1/markets/{urllib.parse.quote(ticker.strip().upper())}/replay"
+        out = self._poll(lambda: self._request("GET", path, params=params), wait=wait)
+        if out.get("status") != "ready":
+            raise ApiError(504, "Replay is still being prepared; call again later.")
+        return out
+
+    def create_s3_key(self, name: str = "default") -> dict[str, Any]:
+        """Create a read-only S3 key for syncing whole datasets (paid plans).
+
+        Returns endpoint, bucket, access_key_id, secret_access_key (shown once), and
+        ready-to-paste snippets for aws, rclone, DuckDB, and boto3.
+        """
+        self._need_key()
+        return self._request("POST", "/api/v1/files/keys", body={"name": name})
+
+    def s3_keys(self) -> dict[str, Any]:
+        """Your S3 keys, with last use and data counted per key."""
+        self._need_key()
+        return self._request("GET", "/api/v1/files/keys")
+
+    def revoke_s3_key(self, key_id: str) -> dict[str, Any]:
+        self._need_key()
+        return self._request("DELETE", f"/api/v1/files/keys/{urllib.parse.quote(key_id)}")
+
+    # ------------------------------------------------------------------ saved requests
+
+    def save_request(
+        self,
+        datasets: str | Sequence[str],
+        start_date: str,
+        end_date: str,
+        *,
+        series: str | Iterable[str] | None = None,
+        categories: str | Iterable[str] | None = None,
+        tickers: str | Iterable[str] | None = None,
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        self._need_key()
+        body = self._selection(datasets, start_date, end_date, series, categories, tickers)
+        if name:
+            body["name"] = name
+        return self._request("POST", "/api/v1/requests", body=body)
+
+    def requests(self, limit: int = 20) -> list[dict[str, Any]]:
+        self._need_key()
+        return self._request("GET", "/api/v1/requests", params={"limit": limit})["requests"]

kalshieye-0.2.1/kalshieye.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: kalshieye
+Version: 0.2.1
+Summary: Download Kalshi Eye flat files (order book, book snapshots, top of book, bars, trades, spot, markets, settlements) and load them into pandas or Polars.
+License-Expression: MIT
+Project-URL: Homepage, https://kalshieye.com
+Project-URL: Documentation, https://kalshieye.com/docs/bulk/
+Project-URL: Source, https://github.com/KalshiEye/kalshieye-python
+Keywords: kalshi,prediction markets,order book,market data,parquet
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == "pandas"
+Requires-Dist: pyarrow>=14; extra == "pandas"
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == "polars"
+Dynamic: license-file
+
+# kalshieye
+
+Python client for Kalshi Eye flat files: daily Parquet for the order book (`book_l2`), 1-second top-10 book snapshots (`book_snap_1s`), top of book (`bbo`), one-minute bars (`bbo_1m`), trades, crypto spot (`spot`), and the reference tables (`markets`, `settlements`, `series`, `incidents`).
+
+```bash
+pip install "kalshieye[pandas]"      # or kalshieye[polars], or plain kalshieye
+export KALSHIEYE_API_KEY=clab_...     # create one under API keys
+```
+
+```python
+from kalshieye import Client, replay_book
+
+kx = Client()
+kx.datasets()                                             # schemas, coverage, required plan
+kx.estimate(["bbo_1m", "trades"], "2026-10-12", "2026-10-18", series=["KXBTC*"])
+
+kx.download(["bbo_1m", "trades"], "2026-10-12", "2026-10-18",
+            series=["KXBTC*"], dest="data", progress=True)
+
+df = kx.load("bbo_1m", "2026-10-12", "2026-10-18", series="KXBTC15M")
+fills = kx.load("trades", "2026-10-12", "2026-10-12", tickers=["KXBTC15M-26OCT121545-45"])
+
+# Rebuild the book from book_l2 rows
+book = kx.load("book_l2", "2026-10-12", "2026-10-12", tickers=["KXBTC15M-26OCT121545-45"])
+for ts, ticker, bids, asks in replay_book(book):
+    ...
+
+# One event in one zip: book, snapshots, trades, spot, metadata.json, settlement.json
+kx.bundle("KXBTC15M-26OCT121545")
+
+# CSV.gz copy of a single file
+f = next(kx.files("trades", "2026-10-12", "2026-10-12", series="KXBTC15M"))
+kx.csv(f["key"])
+
+# S3 access (paid plans): a read-only key for aws s3 sync, rclone, DuckDB, boto3
+key = kx.create_s3_key("laptop")
+print(key["snippets"]["aws_cli"])
+```
+
+- Files land under `dest` in the lake layout (`bbo_1m/date=2026-10-12/series=KXBTC15M/...parquet`), so DuckDB, Polars, and Spark can read the folder as a hive-partitioned dataset. `spot` is partitioned by `asset=` instead of `series=`.
+- Every file is checked against its sha256. Files already on disk are skipped and do not count toward your monthly download allowance.
+- `series` accepts wildcards (`KXBTC*`). `categories` filters by archive category (`crypto`, `politics`, ...). `tickers` picks the series files holding those markets, and `load` keeps only their rows.
+- `bundle`, `csv`, and `replay` are built on the server the first time; the client waits for them.
+- Errors raise `kalshieye.ApiError`. Use `err.code` to tell plan limits (`plan_required`, `history_limited`, `download_quota`) apart.
+
+## Without an account
+
+`replay_book` works on any `book_l2` rows, including the free one-day sample on Hugging Face ([KalshiEye/kalshi-order-book-sample](https://huggingface.co/datasets/KalshiEye/kalshi-order-book-sample)), which DuckDB reads in place:
+
+```python
+# pip install "kalshieye[pandas]" duckdb
+import duckdb
+from kalshieye import replay_book
+
+# Bills vs Rams, YES if Buffalo wins: every book change up to 11 PM Eastern
+book = duckdb.sql("""
+  SELECT * FROM 'hf://datasets/KalshiEye/kalshi-order-book-sample/kalshieye-data/book_l2/*/series=KXNFLGAME/*.parquet'
+  WHERE ticker = 'KXNFLGAME-26OCT12BUFLAR-BUF'
+    AND ts_recv::TIMESTAMPTZ <= '2026-10-13 03:00:00+00'::TIMESTAMPTZ
+  ORDER BY ts_recv, seq
+""").df()
+
+*_, (ts, ticker, bids, asks) = replay_book(book, levels=3)
+print(bids)  # [(0.51, 155253.51), (0.5, 405328.0), (0.49, 15126.0)]
+print(asks)  # [(0.52, 960851.07), (0.53, 862817.41), (0.54, 113351.03)]
+```
+
+More runnable examples (a backtest, spreads and depth, calibration) are in [KalshiEye/kalshieye-examples](https://github.com/KalshiEye/kalshieye-examples). Every column is described in the [data dictionary](https://kalshieye.com/docs/datasets/).

kalshieye-0.2.1/kalshieye.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+kalshieye/__init__.py
+kalshieye/book.py
+kalshieye/client.py
+kalshieye.egg-info/PKG-INFO
+kalshieye.egg-info/SOURCES.txt
+kalshieye.egg-info/dependency_links.txt
+kalshieye.egg-info/requires.txt
+kalshieye.egg-info/top_level.txt
+tests/test_book.py

kalshieye-0.2.1/kalshieye.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kalshieye-0.2.1/kalshieye.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[pandas]
+pandas>=2.0
+pyarrow>=14
+
+[polars]
+polars>=0.20

kalshieye-0.2.1/kalshieye.egg-info/top_level.txt

@@ -0,0 +1 @@
+kalshieye

kalshieye-0.2.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kalshieye"
+version = "0.2.1"
+description = "Download Kalshi Eye flat files (order book, book snapshots, top of book, bars, trades, spot, markets, settlements) and load them into pandas or Polars."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["kalshi", "prediction markets", "order book", "market data", "parquet"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0", "pyarrow>=14"]
+polars = ["polars>=0.20"]
+
+[project.urls]
+Homepage = "https://kalshieye.com"
+Documentation = "https://kalshieye.com/docs/bulk/"
+Source = "https://github.com/KalshiEye/kalshieye-python"
+
+[tool.setuptools]
+packages = ["kalshieye"]

kalshieye-0.2.1/setup.cfg

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

kalshieye-0.2.1/tests/test_book.py

@@ -0,0 +1,50 @@
+from kalshieye import Book, replay_book
+
+
+def _row(ts, side, price, size, snapshot=False, ticker="T"):
+    return {"ts_recv": ts, "ticker": ticker, "is_snapshot": snapshot, "side": side, "price": price, "size": size}
+
+
+def test_snapshot_then_deltas():
+    rows = [
+        _row(0, "yes", 0.40, 100.0, snapshot=True),
+        _row(0, "no", 0.55, 50.0, snapshot=True),
+        _row(1, "yes", 0.41, 20.0),
+        _row(2, "yes", 0.40, -100.0),
+        _row(3, "no", 0.55, -10.5),
+    ]
+    states = list(replay_book(rows))
+    assert len(states) == 4  # one per message
+    _, ticker, bids, asks = states[-1]
+    assert ticker == "T"
+    assert bids == [(0.41, 20.0)]
+    assert asks == [(0.45, 39.5)]  # a NO bid at 0.55 is a YES ask at 0.45
+
+
+def test_snapshot_replaces_the_book():
+    book = Book()
+    book.apply(_row(0, "yes", 0.30, 5.0, snapshot=True))
+    book.apply(_row(1, "yes", 0.31, 5.0))
+    book.apply(_row(2, "yes", 0.20, 7.0, snapshot=True))
+    assert book.bids() == [(0.20, 7.0)]
+
+
+def test_empty_snapshot_clears_the_book():
+    book = Book()
+    book.apply(_row(0, "yes", 0.30, 5.0, snapshot=True))
+    book.apply(_row(1, None, None, None, snapshot=True))
+    assert book.best() == (None, None)
+
+
+def test_float_residue_does_not_leave_a_level():
+    # These sizes sum to exactly zero, but adding them as floats leaves about 1.4e-9.
+    sizes = [1121596.98, 1628450.55, 1595362.86, 1258899.31, -1569585.22, -4034724.48]
+    rows = [_row(0, "yes", 0.52, 10.0, snapshot=True), _row(0, "yes", 0.53, sizes[0], snapshot=True)]
+    rows += [_row(i, "yes", 0.53, size) for i, size in enumerate(sizes[1:], start=1)]
+    *_, (ts, ticker, bids, asks) = replay_book(rows)
+    assert bids == [(0.52, 10.0)]
+
+
+def test_filters_one_ticker():
+    rows = [_row(0, "yes", 0.30, 5.0, snapshot=True, ticker="A"), _row(0, "yes", 0.60, 9.0, snapshot=True, ticker="B")]
+    assert [s[1] for s in replay_book(rows, ticker="b")] == ["B"]