resolvedkit 0.1.0__tar.gz

resolvedkit-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

resolvedkit-0.1.0/DATA_LICENSE

@@ -0,0 +1,9 @@
+The sample dataset in src/resolvedkit/sample_data/ is © 2026 Elcara LLC-FZ (Resolved Markets)
+and licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0):
+https://creativecommons.org/licenses/by/4.0/
+
+Attribution: "Polymarket order-book data from Resolved Markets (https://resolvedmarkets.com)".
+
+It contains settled BTC 15-minute Polymarket markets, thinned to one snapshot per side per second and the
+top 20 price levels. The full archive (every snapshot, full depth, all categories) is available through
+the Resolved Markets API.

resolvedkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elcara LLC-FZ (Resolved Markets)
+
+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.

resolvedkit-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: resolvedkit
+Version: 0.1.0
+Summary: A Polymarket backtester that tests strategies against the real order book. Fills walk the L2 ladder, fees follow Polymarket's curve, positions settle at resolution.
+Project-URL: Homepage, https://github.com/resolvedmarkets/resolvedkit
+Project-URL: Data, https://resolvedmarkets.com
+Project-URL: Issues, https://github.com/resolvedmarkets/resolvedkit/issues
+Author-email: Resolved Markets <info@resolvedmarkets.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backtesting,orderbook,polymarket,polymarket-backtester,prediction-markets,quant,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: pyarrow>=14
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# resolvedkit: a Polymarket backtester
+
+**Backtest Polymarket strategies against the real order book.** Orders fill by walking the L2 ladder,
+fees follow Polymarket's taker-fee curve, orders land after a realistic delay, and positions settle at
+the market's actual resolution. It ships with sample data, so it runs straight after `pip install`, with
+no API key.
+
+![Same strategy backtested with mid-price fills and on the real order book](https://raw.githubusercontent.com/resolvedmarkets/resolvedkit/main/docs/mid-vs-book.png)
+
+Most prediction-market backtests fill at the mid price. That price is not one you can trade at: a
+market buy pays the ask, walks up the book when the size is larger than the best level, and pays a
+taker fee on top. On the bundled sample, the same strategy with the same fees returns **+29.5%** when
+filled at the mid and **+26.0%** when filled against the book. That gap is often an entire edge.
+
+```bash
+pip install resolvedkit
+resolvedkit run late_favorite --compare-mid
+```
+
+## What it models
+
+- **Book-walking fills.** Buys lift asks level by level and sells hit bids. A price limit caps the
+  walk, and partial fills are flagged when the book runs out. Mid-price fills exist only as an explicit
+  `fill_model="mid"`, to measure how much they overstate.
+- **Polymarket fees.** `shares × rate × p × (1 − p)` is charged per matched level, with the rate for
+  each category (crypto 0.07, sports 0.05, and so on).
+- **Latency.** An order fills against the book standing `latency_ms` after it was placed (250 ms by
+  default), not the book that triggered it.
+- **Settlement.** Shares still held at the end pay out the market's resolved price, 1 or 0 per share, or
+  a fraction for split outcomes. Unresolved markets are marked at the last mid and counted in
+  `unresolved_markets`.
+- **Placeholder books.** Freshly listed markets often show a 0.01 / 0.99 book before real quoting
+  starts. Orders against it are rejected rather than filled at 0.99.
+- **Metrics.** Results include PnL, return on money invested, fees, win rate, partial fills, average
+  slippage against the mid, and the Brier score of entry prices.
+
+## Two ways to write a strategy
+
+**JSON spec**, with no code, which also makes it easy for an AI agent to write one:
+
+```json
+{
+  "name": "Buy the favorite in the last 2 minutes, take 5 cents or stop at 10",
+  "entry": {"side": "favorite", "seconds_before_end": 120, "min_price": 0.6, "max_price": 0.9,
+            "usd": 250, "max_slippage": 0.02},
+  "exit": {"take_profit": 0.05, "stop_loss": 0.10}
+}
+```
+
+`side` is `UP`, `DOWN`, `favorite` or `underdog`. Without `exit`, the position is held to resolution.
+Save it as `my_strategy.json` and run `resolvedkit run my_strategy.json`. Two examples are
+bundled: `late_favorite` and `early_underdog_scalp`.
+
+**Python**, for anything else:
+
+```python
+from resolvedkit import UP, Backtester, Strategy, load_sample
+
+class DepthImbalance(Strategy):
+    def on_book(self, ctx, book):
+        if book.side != UP or ctx.state.get("entered") or not book.two_sided:
+            return
+        bid_depth = sum(l.size * l.price for l in book.bids[:5])
+        ask_depth = sum(l.size * l.price for l in book.asks[:5])
+        if 60 < ctx.seconds_to_end < 600 and bid_depth > 3 * ask_depth:
+            ctx.buy(UP, usd=100, max_price=book.best_ask + 0.02)
+            ctx.state["entered"] = True
+
+print(Backtester(load_sample(), DepthImbalance()).run().summary())
+```
+
+`on_book` is called for every snapshot of either outcome token, in time order. `ctx` provides:
+- `book(side)`, `position(side)`, `now` and `seconds_to_end`
+- `buy(side, usd, max_price)` and `sell(side, shares, min_price)`
+- `state`, a dict that resets for each market
+
+## Data
+
+| Source | Use |
+|---|---|
+| `load_sample()` | 18 settled BTC 15-minute markets, bundled (CC BY 4.0) |
+| `ResolvedMarketsAPI(crypto="BTC", timeframe="15m", limit=50)` | Historical Polymarket order books from [Resolved Markets](https://resolvedmarkets.com). A free API key covers recent crypto markets; paid plans add full history plus sports, weather, equities and economics. |
+| `ParquetSource("folder/")` | Your own data in the documented [two-file Parquet layout](https://github.com/resolvedmarkets/resolvedkit/blob/main/src/resolvedkit/data/parquet.py) |
+
+```bash
+export RESOLVED_MARKETS_API_KEY=rm_...   # free key: https://resolvedmarkets.com/api-keys
+resolvedkit run late_favorite --data api --crypto ETH --timeframe 5m --limit 50
+```
+
+The sample is thinned to one snapshot per side per second and the top 20 levels. The API serves every
+snapshot at full depth.
+
+## Honest limits
+
+- Rejected or partly filled orders are retried by the JSON rules on the next snapshot; in Python
+  strategies, check `ctx.pending_orders()` and your position yourself.
+- Your orders don't move the book: each fill walks the snapshot as recorded, and later snapshots don't
+  reflect your trades. For small size relative to depth this is close; for large size it's optimistic.
+- Resting (maker) orders aren't simulated yet, since queue position isn't in snapshot data. All fills
+  are taker fills.
+- 18 sample markets are enough to show the mechanics, not to prove a strategy. Run on hundreds.
+
+## Roadmap
+
+Kalshi fees and data adapter · maker orders with queue estimates · wallet-replay (copy-trading)
+backtests · an MCP server so agents can run backtests.
+
+## License
+
+Code: MIT. Sample data: CC BY 4.0, see [DATA_LICENSE](https://github.com/resolvedmarkets/resolvedkit/blob/main/DATA_LICENSE).

resolvedkit-0.1.0/README.md

@@ -0,0 +1,110 @@
+# resolvedkit: a Polymarket backtester
+
+**Backtest Polymarket strategies against the real order book.** Orders fill by walking the L2 ladder,
+fees follow Polymarket's taker-fee curve, orders land after a realistic delay, and positions settle at
+the market's actual resolution. It ships with sample data, so it runs straight after `pip install`, with
+no API key.
+
+![Same strategy backtested with mid-price fills and on the real order book](https://raw.githubusercontent.com/resolvedmarkets/resolvedkit/main/docs/mid-vs-book.png)
+
+Most prediction-market backtests fill at the mid price. That price is not one you can trade at: a
+market buy pays the ask, walks up the book when the size is larger than the best level, and pays a
+taker fee on top. On the bundled sample, the same strategy with the same fees returns **+29.5%** when
+filled at the mid and **+26.0%** when filled against the book. That gap is often an entire edge.
+
+```bash
+pip install resolvedkit
+resolvedkit run late_favorite --compare-mid
+```
+
+## What it models
+
+- **Book-walking fills.** Buys lift asks level by level and sells hit bids. A price limit caps the
+  walk, and partial fills are flagged when the book runs out. Mid-price fills exist only as an explicit
+  `fill_model="mid"`, to measure how much they overstate.
+- **Polymarket fees.** `shares × rate × p × (1 − p)` is charged per matched level, with the rate for
+  each category (crypto 0.07, sports 0.05, and so on).
+- **Latency.** An order fills against the book standing `latency_ms` after it was placed (250 ms by
+  default), not the book that triggered it.
+- **Settlement.** Shares still held at the end pay out the market's resolved price, 1 or 0 per share, or
+  a fraction for split outcomes. Unresolved markets are marked at the last mid and counted in
+  `unresolved_markets`.
+- **Placeholder books.** Freshly listed markets often show a 0.01 / 0.99 book before real quoting
+  starts. Orders against it are rejected rather than filled at 0.99.
+- **Metrics.** Results include PnL, return on money invested, fees, win rate, partial fills, average
+  slippage against the mid, and the Brier score of entry prices.
+
+## Two ways to write a strategy
+
+**JSON spec**, with no code, which also makes it easy for an AI agent to write one:
+
+```json
+{
+  "name": "Buy the favorite in the last 2 minutes, take 5 cents or stop at 10",
+  "entry": {"side": "favorite", "seconds_before_end": 120, "min_price": 0.6, "max_price": 0.9,
+            "usd": 250, "max_slippage": 0.02},
+  "exit": {"take_profit": 0.05, "stop_loss": 0.10}
+}
+```
+
+`side` is `UP`, `DOWN`, `favorite` or `underdog`. Without `exit`, the position is held to resolution.
+Save it as `my_strategy.json` and run `resolvedkit run my_strategy.json`. Two examples are
+bundled: `late_favorite` and `early_underdog_scalp`.
+
+**Python**, for anything else:
+
+```python
+from resolvedkit import UP, Backtester, Strategy, load_sample
+
+class DepthImbalance(Strategy):
+    def on_book(self, ctx, book):
+        if book.side != UP or ctx.state.get("entered") or not book.two_sided:
+            return
+        bid_depth = sum(l.size * l.price for l in book.bids[:5])
+        ask_depth = sum(l.size * l.price for l in book.asks[:5])
+        if 60 < ctx.seconds_to_end < 600 and bid_depth > 3 * ask_depth:
+            ctx.buy(UP, usd=100, max_price=book.best_ask + 0.02)
+            ctx.state["entered"] = True
+
+print(Backtester(load_sample(), DepthImbalance()).run().summary())
+```
+
+`on_book` is called for every snapshot of either outcome token, in time order. `ctx` provides:
+- `book(side)`, `position(side)`, `now` and `seconds_to_end`
+- `buy(side, usd, max_price)` and `sell(side, shares, min_price)`
+- `state`, a dict that resets for each market
+
+## Data
+
+| Source | Use |
+|---|---|
+| `load_sample()` | 18 settled BTC 15-minute markets, bundled (CC BY 4.0) |
+| `ResolvedMarketsAPI(crypto="BTC", timeframe="15m", limit=50)` | Historical Polymarket order books from [Resolved Markets](https://resolvedmarkets.com). A free API key covers recent crypto markets; paid plans add full history plus sports, weather, equities and economics. |
+| `ParquetSource("folder/")` | Your own data in the documented [two-file Parquet layout](https://github.com/resolvedmarkets/resolvedkit/blob/main/src/resolvedkit/data/parquet.py) |
+
+```bash
+export RESOLVED_MARKETS_API_KEY=rm_...   # free key: https://resolvedmarkets.com/api-keys
+resolvedkit run late_favorite --data api --crypto ETH --timeframe 5m --limit 50
+```
+
+The sample is thinned to one snapshot per side per second and the top 20 levels. The API serves every
+snapshot at full depth.
+
+## Honest limits
+
+- Rejected or partly filled orders are retried by the JSON rules on the next snapshot; in Python
+  strategies, check `ctx.pending_orders()` and your position yourself.
+- Your orders don't move the book: each fill walks the snapshot as recorded, and later snapshots don't
+  reflect your trades. For small size relative to depth this is close; for large size it's optimistic.
+- Resting (maker) orders aren't simulated yet, since queue position isn't in snapshot data. All fills
+  are taker fills.
+- 18 sample markets are enough to show the mechanics, not to prove a strategy. Run on hundreds.
+
+## Roadmap
+
+Kalshi fees and data adapter · maker orders with queue estimates · wallet-replay (copy-trading)
+backtests · an MCP server so agents can run backtests.
+
+## License
+
+Code: MIT. Sample data: CC BY 4.0, see [DATA_LICENSE](https://github.com/resolvedmarkets/resolvedkit/blob/main/DATA_LICENSE).

resolvedkit-0.1.0/examples/custom_strategy.py

@@ -0,0 +1,18 @@
+"""A strategy in Python: buy UP when its book shows 3x more bid depth than ask depth."""
+from resolvedkit import UP, Backtester, Strategy, load_sample
+
+
+class DepthImbalance(Strategy):
+    def on_book(self, ctx, book):
+        if book.side != UP or ctx.state.get("entered") or not book.two_sided:
+            return
+        bid_depth = sum(l.size * l.price for l in book.bids[:5])
+        ask_depth = sum(l.size * l.price for l in book.asks[:5])
+        if 60 < ctx.seconds_to_end < 600 and bid_depth > 3 * ask_depth:
+            ctx.buy(UP, usd=100, max_price=book.best_ask + 0.02)
+            ctx.state["entered"] = True
+
+
+results = Backtester(load_sample(), DepthImbalance(), latency_ms=250).run()
+for k, v in results.summary().items():
+    print(f"{k:<22} {v}")

resolvedkit-0.1.0/examples/mid_vs_book_chart.py

@@ -0,0 +1,40 @@
+"""Draw docs/mid-vs-book.png: the same strategy backtested with mid-price fills and on the real book."""
+import json
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+
+from resolvedkit import Backtester, RuleStrategy, load_sample
+
+HERE = Path(__file__).parent
+spec = json.loads((HERE.parent / "src" / "resolvedkit" / "specs" / "late_favorite.json").read_text())
+data = load_sample()
+
+
+def cumulative_return(results):
+    invested = pnl = 0.0
+    xs, ys = [], []
+    for i, m in enumerate(sorted(results.markets, key=lambda r: r.market.end_ts), 1):
+        invested += sum(f.notional for f in m.fills if f.action == "BUY")
+        pnl += m.pnl
+        xs.append(i)
+        ys.append(100 * pnl / invested if invested else 0.0)
+    return xs, ys
+
+
+fig, ax = plt.subplots(figsize=(8, 4.2), dpi=150)
+for model, style in (("mid", "--"), ("book", "-")):
+    res = Backtester(data, RuleStrategy(spec), fill_model=model).run()
+    xs, ys = cumulative_return(res)
+    label = "Filled at the mid price (what most backtests do)" if model == "mid" else "Filled by walking the real order book"
+    ax.plot(xs, ys, style, linewidth=2.2, label=f"{label}: {ys[-1]:+.1f}%")
+ax.set_title(f"Same strategy, same fees and 250 ms latency, two fill models\n{spec['name']} · {len(data.markets())} BTC 15-minute Polymarket markets", fontsize=10)
+ax.xaxis.get_major_locator().set_params(integer=True)
+ax.set_xlabel("Markets")
+ax.set_ylabel("Cumulative return on money invested (%)")
+ax.grid(alpha=0.3)
+ax.legend(fontsize=8, loc="lower right")
+fig.tight_layout()
+out = HERE.parent / "docs" / "mid-vs-book.png"
+fig.savefig(out)
+print("wrote", out)

resolvedkit-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "resolvedkit"
+version = "0.1.0"
+description = "A Polymarket backtester that tests strategies against the real order book. Fills walk the L2 ladder, fees follow Polymarket's curve, positions settle at resolution."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Resolved Markets", email = "info@resolvedmarkets.com" }]
+keywords = ["polymarket", "polymarket-backtester", "backtesting", "prediction-markets", "orderbook", "trading", "quant"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = ["pyarrow>=14", "requests>=2.31"]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7"]
+dev = ["pytest>=8", "matplotlib>=3.7"]
+
+[project.scripts]
+resolvedkit = "resolvedkit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/resolvedmarkets/resolvedkit"
+Data = "https://resolvedmarkets.com"
+Issues = "https://github.com/resolvedmarkets/resolvedkit/issues"
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

resolvedkit-0.1.0/scripts/build_sample.py

@@ -0,0 +1,22 @@
+"""Rebuild the bundled sample from the Resolved Markets API.
+
+    RESOLVED_MARKETS_API_KEY=... python scripts/build_sample.py [n_markets]
+
+Takes the most recent settled BTC 15-minute markets, one snapshot per side per second, top 20 levels.
+"""
+import sys
+from pathlib import Path
+
+from resolvedkit.data import ResolvedMarketsAPI, write_parquet
+
+N = int(sys.argv[1]) if len(sys.argv) > 1 else 20
+OUT = Path(__file__).resolve().parent.parent / "src" / "resolvedkit" / "sample_data"
+
+api = ResolvedMarketsAPI(crypto="BTC", timeframe="15m", limit=N, thin_ms=1000, depth=20)
+markets = [m for m in api.markets() if m.payout is not None]
+books = {}
+for i, m in enumerate(markets, 1):
+    books[m.market_id] = api.books(m.market_id)
+    print(f"{i}/{len(markets)} {m.question}: {len(books[m.market_id])} snapshots", flush=True)
+write_parquet(OUT, markets, books, depth=20)
+print("wrote", OUT, sum(f.stat().st_size for f in OUT.iterdir()) // 1024, "KiB")

resolvedkit-0.1.0/src/resolvedkit/__init__.py

@@ -0,0 +1,13 @@
+"""Backtest Polymarket strategies against the real order book."""
+from .data import ParquetSource, ResolvedMarketsAPI, load_sample, write_parquet
+from .engine import Backtester, Context, MarketResult, Strategy
+from .fees import taker_fee
+from .metrics import Results
+from .models import DOWN, UP, Book, Fill, Level, Market
+from .rules import RuleStrategy
+
+__version__ = "0.1.0"
+__all__ = [
+    "Backtester", "Book", "Context", "DOWN", "Fill", "Level", "Market", "MarketResult", "ParquetSource",
+    "ResolvedMarketsAPI", "Results", "RuleStrategy", "Strategy", "UP", "load_sample", "taker_fee", "write_parquet",
+]

resolvedkit-0.1.0/src/resolvedkit/cli.py

@@ -0,0 +1,85 @@
+"""resolvedkit run spec.json [--data sample|api|<folder>] [--compare-mid] [--json]"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .engine import Backtester
+from .rules import RuleStrategy
+
+
+def _source(args):
+    if args.data == "sample":
+        from .data import load_sample
+
+        return load_sample()
+    if args.data == "api":
+        from .data import ResolvedMarketsAPI
+
+        return ResolvedMarketsAPI(crypto=args.crypto, timeframe=args.timeframe, category=args.category,
+                                  since=args.since, before=args.before, limit=args.limit, thin_ms=args.thin_ms)
+    from .data import ParquetSource
+
+    return ParquetSource(args.data)
+
+
+def _spec_path(name: str):
+    """A path to a JSON spec, or the name of a bundled example such as `late_favorite`."""
+    from importlib.resources import files
+    from pathlib import Path
+
+    p = Path(name)
+    if p.exists():
+        return p
+    bundled = files("resolvedkit") / "specs" / f"{p.stem}.json"
+    if bundled.is_file():
+        return bundled
+    examples = sorted(x.name.removesuffix(".json") for x in (files("resolvedkit") / "specs").iterdir())
+    raise SystemExit(f"No spec file '{name}'. Bundled examples: {', '.join(examples)}")
+
+
+def _print(label: str, s: dict) -> None:
+    print(f"\n{label}")
+    for k, v in s.items():
+        print(f"  {k:<22} {v}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="resolvedkit", description="Backtest Polymarket strategies against the real order book.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    run = sub.add_parser("run", help="run a JSON strategy spec")
+    run.add_argument("spec", help="path to a JSON strategy spec, or a bundled example: late_favorite, early_underdog_scalp")
+    run.add_argument("--data", default="sample", help="'sample' (bundled, default), 'api' (Resolved Markets), or a Parquet folder")
+    run.add_argument("--latency-ms", type=int, default=250)
+    run.add_argument("--compare-mid", action="store_true", help="also run with mid-price fills and show the difference")
+    run.add_argument("--json", action="store_true", help="print results as JSON")
+    for flag in ("--crypto", "--timeframe", "--category", "--since", "--before"):
+        run.add_argument(flag, help="with --data api: filter markets like /v1/markets/history/recent")
+    run.add_argument("--limit", type=int, default=20, help="with --data api: number of markets")
+    run.add_argument("--thin-ms", type=int, default=None, help="with --data api: keep one snapshot per side per interval")
+    args = p.parse_args(argv)
+
+    spec = json.loads(_spec_path(args.spec).read_text())
+    data = _source(args)
+    markets = data.markets()
+    book = Backtester(data, RuleStrategy(spec), latency_ms=args.latency_ms).run(markets).summary()
+    out = {"strategy": spec.get("name", args.spec), "book": book}
+    if args.compare_mid:
+        out["mid"] = Backtester(data, RuleStrategy(spec), latency_ms=args.latency_ms, fill_model="mid").run(markets).summary()
+    if args.json:
+        json.dump(out, sys.stdout, indent=2)
+        print()
+        return 0
+    print(f"Strategy: {out['strategy']}  ({len(markets)} markets)")
+    _print("Fills against the real order book:", book)
+    if args.compare_mid:
+        _print("Same strategy with mid-price fills (unrealistic):", out["mid"])
+        rm, rb = out["mid"]["return_on_invested"], book["return_on_invested"]
+        if rm is not None and rb is not None:
+            print(f"\nReturn on money invested: {rm:+.1%} with mid-price fills vs {rb:+.1%} on the real book.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

resolvedkit-0.1.0/src/resolvedkit/data/__init__.py

@@ -0,0 +1,7 @@
+"""Data sources. Anything with `markets()` and `books(market_id)` can drive a backtest."""
+from .base import DataSource
+from .parquet import ParquetSource, write_parquet
+from .resolvedmarkets import ResolvedMarketsAPI
+from .sample import load_sample
+
+__all__ = ["DataSource", "ParquetSource", "ResolvedMarketsAPI", "load_sample", "write_parquet"]

resolvedkit-0.1.0/src/resolvedkit/data/base.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Protocol
+
+from ..models import Book, Market
+
+TIMEFRAME_MS = {"5m": 300_000, "15m": 900_000, "1h": 3_600_000, "4h": 14_400_000, "1d": 86_400_000}
+
+
+class DataSource(Protocol):
+    def markets(self) -> list[Market]:
+        """Markets to backtest over, oldest first."""
+        ...
+
+    def books(self, market_id: str) -> list[Book]:
+        """Every order-book snapshot for both outcome tokens of one market, in time order."""
+        ...
+
+
+def parse_ts(value: str | int | float) -> int:
+    """API timestamps are UTC strings like '2026-09-28 13:15:15.955'; return epoch ms."""
+    if isinstance(value, (int, float)):
+        return int(value)
+    dt = datetime.fromisoformat(value.replace("Z", "+00:00").replace(" ", "T"))
+    dt = dt.replace(tzinfo=timezone.utc) if dt.tzinfo is None else dt.astimezone(timezone.utc)
+    return int(dt.timestamp() * 1000)
+
+
+def thin(books: list[Book], every_ms: int) -> list[Book]:
+    """Keep the last snapshot per side in each `every_ms` bucket. Book state at bucket ends is exact."""
+    last: dict[tuple[str, int], Book] = {}
+    for b in books:
+        last[(b.side, b.ts // every_ms)] = b
+    return sorted(last.values(), key=lambda b: (b.ts, b.side))

resolvedkit-0.1.0/src/resolvedkit/data/parquet.py

@@ -0,0 +1,88 @@
+"""A local dataset: two Parquet files in one folder.
+
+markets.parquet  market_id, slug, question, category, timeframe, start_ts, end_ts,
+                 outcome_up, outcome_down, payout_up, payout_down   (payouts null if unresolved)
+books.parquet    market_id, ts (epoch ms UTC), side ("UP"/"DOWN"),
+                 bid_px, bid_sz, ask_px, ask_sz   (lists, best level first)
+
+Any source of Polymarket order books can be converted to this layout and backtested.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+from ..models import Book, Level, Market
+
+_MARKET_SCHEMA = pa.schema([
+    ("market_id", pa.string()), ("slug", pa.string()), ("question", pa.string()),
+    ("category", pa.string()), ("timeframe", pa.string()),
+    ("start_ts", pa.int64()), ("end_ts", pa.int64()),
+    ("outcome_up", pa.string()), ("outcome_down", pa.string()),
+    ("payout_up", pa.float64()), ("payout_down", pa.float64()),
+])
+_BOOK_SCHEMA = pa.schema([
+    ("market_id", pa.string()), ("ts", pa.int64()), ("side", pa.string()),
+    ("bid_px", pa.list_(pa.float64())), ("bid_sz", pa.list_(pa.float64())),
+    ("ask_px", pa.list_(pa.float64())), ("ask_sz", pa.list_(pa.float64())),
+])
+
+
+class ParquetSource:
+    def __init__(self, folder: str | Path):
+        self.folder = Path(folder)
+        self._books: dict[str, list[Book]] | None = None
+
+    def markets(self) -> list[Market]:
+        rows = pq.read_table(self.folder / "markets.parquet").to_pylist()
+        out = []
+        for r in rows:
+            payout = None
+            if r["payout_up"] is not None and r["payout_down"] is not None:
+                payout = (r["payout_up"], r["payout_down"])
+            out.append(Market(
+                market_id=r["market_id"], question=r["question"], category=r["category"],
+                end_ts=r["end_ts"], outcomes=(r["outcome_up"], r["outcome_down"]), payout=payout,
+                start_ts=r["start_ts"], slug=r["slug"], timeframe=r["timeframe"],
+            ))
+        return sorted(out, key=lambda m: m.end_ts)
+
+    def books(self, market_id: str) -> list[Book]:
+        if self._books is None:
+            grouped: dict[str, list[Book]] = defaultdict(list)
+            for r in pq.read_table(self.folder / "books.parquet").to_pylist():
+                grouped[r["market_id"]].append(Book(
+                    ts=r["ts"], side=r["side"],
+                    bids=tuple(Level(p, s) for p, s in zip(r["bid_px"], r["bid_sz"])),
+                    asks=tuple(Level(p, s) for p, s in zip(r["ask_px"], r["ask_sz"])),
+                ))
+            for v in grouped.values():
+                v.sort(key=lambda b: (b.ts, b.side))
+            self._books = dict(grouped)
+        return self._books.get(market_id, [])
+
+
+def write_parquet(folder: str | Path, markets: list[Market], books: dict[str, list[Book]], depth: int | None = None) -> None:
+    """Save markets and their books in the layout ParquetSource reads. `depth` keeps the top N levels."""
+    folder = Path(folder)
+    folder.mkdir(parents=True, exist_ok=True)
+    pq.write_table(pa.Table.from_pylist([{
+        "market_id": m.market_id, "slug": m.slug, "question": m.question, "category": m.category,
+        "timeframe": m.timeframe, "start_ts": m.start_ts, "end_ts": m.end_ts,
+        "outcome_up": m.outcomes[0], "outcome_down": m.outcomes[1],
+        "payout_up": m.payout[0] if m.payout else None, "payout_down": m.payout[1] if m.payout else None,
+    } for m in markets], schema=_MARKET_SCHEMA), folder / "markets.parquet", compression="zstd")
+    rows = []
+    for market_id, bs in books.items():
+        for b in bs:
+            bids = b.bids if depth is None else b.bids[:depth]
+            asks = b.asks if depth is None else b.asks[:depth]
+            rows.append({
+                "market_id": market_id, "ts": b.ts, "side": b.side,
+                "bid_px": [l.price for l in bids], "bid_sz": [l.size for l in bids],
+                "ask_px": [l.price for l in asks], "ask_sz": [l.size for l in asks],
+            })
+    pq.write_table(pa.Table.from_pylist(rows, schema=_BOOK_SCHEMA), folder / "books.parquet", compression="zstd")