backtest2live 0.2.0__tar.gz → 0.3.0__tar.gz

{backtest2live-0.2.0 → backtest2live-0.3.0}/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "backtest2live",
-      "description": "Check a backtest against what live execution would do, run locally. Convergence across a variant sweep (CONVERGED / ITERATE / KILL) with the numbers behind the verdict; fill-gap and more evaluators follow. Wraps the backtest2live CLI.",
+      "description": "Check a backtest against what live execution would do, run locally. Three checks: convergence across a variant sweep (CONVERGED / ITERATE / KILL), fill-gap for resting orders against a queue proxy, cost-gap for taker orders against the real book. Wraps the backtest2live CLI.",
       "source": "./plugins/backtest2live",
       "category": "data",
       "homepage": "https://github.com/martianmobile/backtest2live"

{backtest2live-0.2.0 → backtest2live-0.3.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [0.3.0](https://github.com/martianmobile/backtest2live/compare/v0.2.0...v0.3.0) (2026-10-15)
+
+
+### Bug Fixes
+
+* **fill-gap:** off-grid price guard trips on the share, not a single row ([#22](https://github.com/martianmobile/backtest2live/issues/22)) ([3de66dc](https://github.com/martianmobile/backtest2live/commit/3de66dc3466f813c9055b82421bde05f6e255da5)), closes [#21](https://github.com/martianmobile/backtest2live/issues/21)
+
+
+### Features
+
+* cost-gap evaluator — backtest taker orders re-priced on the real book ([#23](https://github.com/martianmobile/backtest2live/issues/23)) ([e5f9fb0](https://github.com/martianmobile/backtest2live/commit/e5f9fb05771ad35a9fe39ab7b5eea71906c191fb))
+
 # [0.2.0](https://github.com/martianmobile/backtest2live/compare/v0.1.0...v0.2.0) (2026-10-02)
 
 

{backtest2live-0.2.0 → backtest2live-0.3.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.5
 Name: backtest2live
-Version: 0.2.0
-Summary: Check a backtest against what live execution would do: convergence, fill-gap, and more, run locally.
+Version: 0.3.0
+Summary: Check a backtest against what live execution would do: convergence, fill-gap and cost-gap, run locally.
 Project-URL: Homepage, https://martianmobile.com
 Project-URL: Source, https://github.com/martianmobile/backtest2live
 Project-URL: Issues, https://github.com/martianmobile/backtest2live/issues
 Author-email: Martian Mobile <martin@martianmobile.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: backtest,execution,fill-rate,overfitting,quant,trading
+Keywords: backtest,execution,fill-rate,overfitting,quant,slippage,trading
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Intended Audience :: Science/Research
@@ -41,6 +41,7 @@ This is the public, MIT-licensed version of checks used in live crypto trading r
 |---------|--------|--------------|
 | **`bt2live convergence`** | shipped | Read a variant parameter sweep → measure dispersion, IS/OOS rank stability, and parameter-plateau structure → verdict: **CONVERGED / ITERATE / KILL**. |
 | **`bt2live fill-gap`** | shipped | Re-run your backtest's resting orders under a queue proxy on top-of-book and trades → your fill rate vs the proxy's: **CONSISTENT / OVERSTATED**. |
+| **`bt2live cost-gap`** | shipped | Re-price your backtest's taker orders (market, or limits that cross) on top-of-book at arrival, with latency → what they would have paid vs what the backtest booked: **CONSISTENT / OVERSTATED**. The check for bar-based backtests. |
 
 Roadmap: [ROADMAP.md](ROADMAP.md) and the [milestones](https://github.com/martianmobile/backtest2live/milestones).
 
@@ -104,7 +105,7 @@ CSV, one row per order. Column names are matched case-insensitively:
 | P&L | `pnl` | no |
 | id | `order_id` | no |
 
-Orders marketable at arrival are taker orders and are skipped. `--latency-ms` delays every order's arrival at the book.
+Orders marketable at arrival are taker orders: `fill-gap` skips them and `cost-gap` prices them. `--latency-ms` delays every order's arrival at the book.
 
 ### Market data
 
@@ -117,6 +118,33 @@ The touch rule is an upper bound: a resting order fills only if something trades
 
 ---
 
+## `cost-gap`: what would your taker orders have paid?
+
+A bar-based backtest fills every order at a bar price: the close, the open, or the mid. A real market order crosses the spread, eats whatever is displayed at the touch, and arrives some milliseconds after the book you saw. `cost-gap` re-prices each market order, and each limit that crosses the spread, against top-of-book at its arrival time and reports the cost against the price the backtest booked.
+
+```bash
+bt2live cost-gap examples/market_orders_btcusdt_2024-03-30.csv --venue binance-um --pair BTCUSDT
+```
+
+```
+## Verdict: REPORTED
+
+**Your backtest's 1,435 taker orders would have paid +0.01 bps on average
+(+0.01 bps median) against the price it booked.**
+```
+
+That example is a toy momentum strategy sending 0.1 BTC market orders every minute and booking the mid. On BTCUSDT perpetuals the half-spread is under 0.01 bps and the touch absorbs 0.1 BTC, so the mid-fill assumption holds there, and the report says so. The check bites on thinner pairs, larger sizes and slower paths: the latency table (0 / 5 / 20 / 100 ms) shows the slope, and the by-volatility table shows where it concentrates. With a `pnl` column the verdict is **OVERSTATED** when the cost removes more than `--tolerance` (default 25%) of the backtest's P&L; without one it is **REPORTED**. Exit code: `0` CONSISTENT or REPORTED, `1` OVERSTATED, `3` error.
+
+### Your order log
+
+Same columns as `fill-gap`, with three additions: `type` (`market`/`limit`), `price` for limits (a limit that crosses the touch is priced as a taker and capped at its limit; one that rests is counted and left to `fill-gap`), and `fill_price`, the price the backtest booked (without it, the mid at arrival is the baseline). A log with no `price` column is all market orders. A log with a `price` column but no `type` and no `fill_price` is read as a bar backtest's export: the price is the booked fill, every order is a market order, and the run says so.
+
+### What the book can and cannot see
+
+Top-of-book shows the touch and its displayed size, nothing behind it. Size beyond the touch is priced one tick worse per displayed-size slice, the least impact consistent with the feed, so the cost is a floor, not a measurement. Only your own live fills settle it.
+
+---
+
 ## `convergence`: has your variant sweep converged?
 
 Given one row per variant (parameters + metrics), it measures:

{backtest2live-0.2.0 → backtest2live-0.3.0}/README.md

@@ -16,6 +16,7 @@ This is the public, MIT-licensed version of checks used in live crypto trading r
 |---------|--------|--------------|
 | **`bt2live convergence`** | shipped | Read a variant parameter sweep → measure dispersion, IS/OOS rank stability, and parameter-plateau structure → verdict: **CONVERGED / ITERATE / KILL**. |
 | **`bt2live fill-gap`** | shipped | Re-run your backtest's resting orders under a queue proxy on top-of-book and trades → your fill rate vs the proxy's: **CONSISTENT / OVERSTATED**. |
+| **`bt2live cost-gap`** | shipped | Re-price your backtest's taker orders (market, or limits that cross) on top-of-book at arrival, with latency → what they would have paid vs what the backtest booked: **CONSISTENT / OVERSTATED**. The check for bar-based backtests. |
 
 Roadmap: [ROADMAP.md](ROADMAP.md) and the [milestones](https://github.com/martianmobile/backtest2live/milestones).
 
@@ -79,7 +80,7 @@ CSV, one row per order. Column names are matched case-insensitively:
 | P&L | `pnl` | no |
 | id | `order_id` | no |
 
-Orders marketable at arrival are taker orders and are skipped. `--latency-ms` delays every order's arrival at the book.
+Orders marketable at arrival are taker orders: `fill-gap` skips them and `cost-gap` prices them. `--latency-ms` delays every order's arrival at the book.
 
 ### Market data
 
@@ -92,6 +93,33 @@ The touch rule is an upper bound: a resting order fills only if something trades
 
 ---
 
+## `cost-gap`: what would your taker orders have paid?
+
+A bar-based backtest fills every order at a bar price: the close, the open, or the mid. A real market order crosses the spread, eats whatever is displayed at the touch, and arrives some milliseconds after the book you saw. `cost-gap` re-prices each market order, and each limit that crosses the spread, against top-of-book at its arrival time and reports the cost against the price the backtest booked.
+
+```bash
+bt2live cost-gap examples/market_orders_btcusdt_2024-03-30.csv --venue binance-um --pair BTCUSDT
+```
+
+```
+## Verdict: REPORTED
+
+**Your backtest's 1,435 taker orders would have paid +0.01 bps on average
+(+0.01 bps median) against the price it booked.**
+```
+
+That example is a toy momentum strategy sending 0.1 BTC market orders every minute and booking the mid. On BTCUSDT perpetuals the half-spread is under 0.01 bps and the touch absorbs 0.1 BTC, so the mid-fill assumption holds there, and the report says so. The check bites on thinner pairs, larger sizes and slower paths: the latency table (0 / 5 / 20 / 100 ms) shows the slope, and the by-volatility table shows where it concentrates. With a `pnl` column the verdict is **OVERSTATED** when the cost removes more than `--tolerance` (default 25%) of the backtest's P&L; without one it is **REPORTED**. Exit code: `0` CONSISTENT or REPORTED, `1` OVERSTATED, `3` error.
+
+### Your order log
+
+Same columns as `fill-gap`, with three additions: `type` (`market`/`limit`), `price` for limits (a limit that crosses the touch is priced as a taker and capped at its limit; one that rests is counted and left to `fill-gap`), and `fill_price`, the price the backtest booked (without it, the mid at arrival is the baseline). A log with no `price` column is all market orders. A log with a `price` column but no `type` and no `fill_price` is read as a bar backtest's export: the price is the booked fill, every order is a market order, and the run says so.
+
+### What the book can and cannot see
+
+Top-of-book shows the touch and its displayed size, nothing behind it. Size beyond the touch is priced one tick worse per displayed-size slice, the least impact consistent with the feed, so the cost is a floor, not a measurement. Only your own live fills settle it.
+
+---
+
 ## `convergence`: has your variant sweep converged?
 
 Given one row per variant (parameters + metrics), it measures:

{backtest2live-0.2.0 → backtest2live-0.3.0}/ROADMAP.md

@@ -11,12 +11,11 @@ Tracking: [milestones](https://github.com/martianmobile/backtest2live/milestones
 - **Tests + CI** — [#3](https://github.com/martianmobile/backtest2live/issues/3). pytest on Python 3.9–3.13; the core stays dependency-free.
 - **Release** — [#11](https://github.com/martianmobile/backtest2live/issues/11). Closing a milestone publishes the version to GitHub Releases and PyPI.
 
-## v0.3 — run the contract, check any engine, share the output (target mid-October 2026)
+## v0.3 — any backtest, any engine, shareable output (target mid-October 2026)
 
-Two ways in. A strategy written to the published `StrategyProtocol` contract (the format Validate accepts) runs locally with `bt2live run`. A backtest from any other engine connects through the order-log schema and its adapters.
+The toolkit checks artifacts a backtest already produces; the order-log schema is the connection to the strategy, whatever engine wrote it.
 
-- **`bt2live run`** — [#15](https://github.com/martianmobile/backtest2live/issues/15). Load a strategy package on the published contract, build its inputs from public data, simulate fills at both ends of the band (front of queue vs the `fill-gap` queue proxy) and taker fills through the published simulator. Emits order logs in the `fill-gap` schema and two equity curves.
-- **`cost-gap`** — [#16](https://github.com/martianmobile/backtest2live/issues/16). For bar-based backtests, which have no resting orders: each market order re-priced against the real book at its time, with latency. Spread, depth and latency cost vs the backtest's fill price.
+- **`cost-gap`** — [#16](https://github.com/martianmobile/backtest2live/issues/16), merged; ships in 0.3.0. For bar-based backtests, which have no resting orders: each market order re-priced against the real book at its time, with latency. Spread, depth and latency cost vs the backtest's fill price.
 - **Schema + engine adapters** — [#7](https://github.com/martianmobile/backtest2live/issues/7). One order-log and results schema; importers for Nautilus, LEAN, backtrader, vectorbt, freqtrade, so the export is one command.
 - **Tear sheet** — [#10](https://github.com/martianmobile/backtest2live/issues/10). One shareable performance artifact with a provenance label.
 - **MCP server** — [#8](https://github.com/martianmobile/backtest2live/issues/8). The checks, exposed to any AI assistant.
@@ -26,6 +25,7 @@ Two ways in. A strategy written to the published `StrategyProtocol` contract (th
 
 ## Later (directional)
 
+- **`bt2live run`** — [#15](https://github.com/martianmobile/backtest2live/issues/15), on demand. Run a strategy written to a published strategy contract locally, with fills at both ends of the band (front of queue vs the `fill-gap` queue proxy). Built when users ask for it.
 - **`robustness`** — outlier-trade drop test, bootstrap CIs on Sharpe, parameter-perturbation sensitivity.
 - **`walk-forward`** — multi-fold rolling/anchored stability of a chosen variant.
 - **`regime`** — performance by vol/trend regime; flags strategies that only work in one.