binance-quant-engine 0.1.1__py3-none-any.whl

binance_quant_engine/execution/host.py

@@ -0,0 +1,65 @@
+"""Host interface for execution mixins.
+
+The live trading bot is composed from mixins (``BracketMixin`` etc.) that are
+mixed into a single ``Scalper`` class.  Each mixin needs to call methods that
+live on *sibling* mixins or on the composed host.  To type-check a mixin in
+isolation — without importing the concrete (and strategy-specific) host class —
+we declare the surface it relies on as a ``Protocol``.
+
+This is the strategy-agnostic slice of that interface: only the order-placement
+and bookkeeping members the bracket manager actually touches.  Concrete trailing
+parameters come from :class:`TrailConfig` rather than any proprietary strategy
+config, so the bracket logic is fully decoupled from alpha.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:  # pragma: no cover
+    from binance_quant_engine.strategy.protocol import TradingStrategy
+
+
+@dataclass(frozen=True)
+class TrailConfig:
+    """Trailing-stop geometry, expressed as fractions of entry price.
+
+    Attributes:
+        trail_distance: Callback distance the stop trails behind the peak
+            (e.g. ``0.005`` = 0.5%).  Binance requires callbackRate >= 0.5%.
+        trail_activate: Unrealised gain at which the trailing stop arms
+            (e.g. ``0.02`` = +2%).
+    """
+
+    trail_distance: float = 0.005
+    trail_activate: float = 0.02
+
+
+class ScalperProtocol(Protocol):
+    """Host surface used by :class:`BracketMixin` (strategy-agnostic)."""
+
+    # ── state ────────────────────────────────────────────────────────
+    paper_mode: bool
+    client: Any
+    discord: Any
+    strategy: "TradingStrategy"
+    trail_config: TrailConfig
+    _algo_api: Any
+
+    # ── exchange helpers (provided by other mixins) ──────────────────
+    def get_symbol_info(self, symbol: str) -> dict[str, Any]: ...
+    def _round_qty(self, qty: float, symbol: str) -> float: ...
+    def _save_state(self) -> None: ...
+
+    def _place_algo_order(self, *args: Any, **kwargs: Any) -> Any: ...
+    def _cancel_server_order(self, symbol: str, order_id: str, label: str = "order") -> bool: ...
+    def _cancel_server_stop_loss(self, symbol: str, order_id: str) -> bool: ...
+    def _verify_algo_order_active(self, algo_id: str, symbol: str) -> str | None: ...
+    def _place_trailing_stop_market(self, *args: Any, **kwargs: Any) -> Any: ...
+    def _cancel_trailing_stop_market(self, symbol: str, order_id: str) -> bool: ...
+    def _check_trail_order_status(self, symbol: str, order_id: str) -> dict[str, Any] | None: ...
+    def _check_order_filled(self, symbol: str, order_id: str) -> dict[str, Any] | None: ...
+    def _lookup_actual_fill(
+        self, symbol: str, expected_qty: str, order_type: str
+    ) -> dict[str, Any] | None: ...

binance_quant_engine/execution/utils.py

@@ -0,0 +1,46 @@
+"""Small, strategy-agnostic helpers shared across the execution layer.
+
+Kept separate from :mod:`brackets` so they can be unit-tested (and reused by
+a host application) without pulling in the full bracket-order state machine.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: Binance algo/conditional-order statuses that mean the order is no longer
+#: live and bookkeeping can stop tracking it. Centralized here so a status
+#: string Binance adds later only needs to be taught to one place.
+#:
+#: Includes both the US and UK spellings of "cancelled" — Binance's own API
+#: is inconsistent about which one a given endpoint returns.
+ALGO_ORDER_DEAD_STATUSES = frozenset(
+    {"CANCELLED", "CANCELED", "EXPIRED", "USER_CANCELLED", "ERROR", "REJECTED"}
+)
+
+
+def round_to_tick(price: float, tick_size: float, price_precision: int) -> float:
+    """Snap *price* to the symbol's tick grid.
+
+    Binance rejects (or silently misprices) an order whose price isn't an
+    exact multiple of the symbol's ``tickSize`` — a raw float division
+    (``price / tick_size``) almost never lands exactly on the grid because of
+    binary floating-point rounding. Round to the nearest tick first, then to
+    the symbol's quoted decimal precision, in that order.
+    """
+    if tick_size <= 0:
+        return round(price, price_precision)
+    return round(round(price / tick_size) * tick_size, price_precision)
+
+
+def to_api_symbol(symbol: str, position: dict[str, Any] | None = None) -> str:
+    """Strip a colon-suffixed compound key down to the bare Binance API symbol.
+
+    Two unrelated conventions both tack a suffix onto the symbol with ``:``,
+    and both need the same fix before a raw Binance REST call: a CCXT-style
+    ``BASE/QUOTE:SETTLE`` key (e.g. ``"BTC/USDT:USDT"``), and a Hedge Mode
+    position key (e.g. ``"BTCUSDT:LONG"``). *position*, if given, may carry an
+    already-resolved ``symbol`` field that takes precedence over *symbol*.
+    """
+    raw = (position or {}).get("symbol", symbol)
+    return raw.split(":")[0] if ":" in raw else raw

binance_quant_engine/mcp/__init__.py

@@ -0,0 +1 @@
+"""Optional MCP (Model Context Protocol) server — install with the ``mcp`` extra."""

binance_quant_engine/mcp/server.py

@@ -0,0 +1,115 @@
+"""MCP stdio server exposing the backtest engine to any MCP-compatible agent.
+
+Deliberately backtest-only. This process never touches an exchange account —
+there is no tool here that can place, modify, or cancel a live order. An
+agent can explore the engine's demo strategy, run its own parameter sweeps,
+and backtest its own OHLC data, but "let an LLM trade my account" is not a
+capability this server offers. Live execution (:mod:`binance_quant_engine.execution`)
+is a library you wire into your own bot; it is intentionally not MCP-reachable.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import math
+from dataclasses import replace
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+
+from binance_quant_engine.backtest.vectorized import run_backtest
+from binance_quant_engine.data.klines import synth_ohlcv
+from binance_quant_engine.strategy.demo_squeeze import SqueezeConfig, SqueezeStrategy
+
+mcp = MCPServer("binance-quant-engine")
+
+
+def _finite(x: float) -> float:
+    """JSON has no representation for inf/nan; MCP transport is JSON."""
+    return x if math.isfinite(x) else 0.0
+
+
+def _summary_json(result: Any) -> dict[str, float]:
+    return {k: _finite(float(v)) for k, v in result.summary().items()}
+
+
+@mcp.tool()
+def run_demo_backtest(
+    n_bars: int = 2000,
+    seed: int = 7,
+    bb_period: int = 20,
+    bb_std: float = 2.0,
+    squeeze_pct: float = 0.25,
+    stop_loss: float = 0.02,
+    take_profit: float = 0.04,
+) -> dict[str, Any]:
+    """Backtest the bundled Bollinger-squeeze demo strategy on synthetic OHLC.
+
+    Zero setup, no API keys, no data file — useful for confirming the engine
+    works and for exploring how the demo strategy's parameters move its
+    metrics. Not a real alpha; see the README before reading any number here
+    as investment advice.
+    """
+    high, low, close = synth_ohlcv(n=n_bars, seed=seed)
+    config = SqueezeConfig(
+        bb_period=bb_period,
+        bb_std=bb_std,
+        squeeze_pct=squeeze_pct,
+        stop_loss=stop_loss,
+        take_profit=take_profit,
+    )
+    result = run_backtest(SqueezeStrategy(config), high, low, close)
+    return {"summary": _summary_json(result), "config": config.__dict__}
+
+
+@mcp.tool()
+def backtest_csv(csv_text: str, config_overrides: dict[str, float] | None = None) -> dict[str, Any]:
+    """Backtest the demo squeeze strategy against caller-supplied OHLC data.
+
+    Args:
+        csv_text: CSV content (not a path — this process has no filesystem
+            access to the caller's machine) with ``high``, ``low``, ``close``
+            columns, case-insensitive.
+        config_overrides: Optional subset of :class:`SqueezeConfig` fields to
+            override (e.g. ``{"stop_loss": 0.015}``).
+    """
+    reader = csv.DictReader(io.StringIO(csv_text))
+    rows = list(reader)
+    if not rows:
+        raise ValueError("csv_text has no data rows")
+    cols = {c.lower(): c for c in rows[0]}
+    for required in ("high", "low", "close"):
+        if required not in cols:
+            raise ValueError(f"csv_text is missing a '{required}' column")
+
+    high = [float(r[cols["high"]]) for r in rows]
+    low = [float(r[cols["low"]]) for r in rows]
+    close = [float(r[cols["close"]]) for r in rows]
+
+    config = SqueezeConfig()
+    if config_overrides:
+        config = replace(config, **config_overrides)
+
+    result = run_backtest(SqueezeStrategy(config), high, low, close)
+    return {"summary": _summary_json(result), "n_bars": len(close), "config": config.__dict__}
+
+
+@mcp.tool()
+def describe_strategy_protocol() -> str:
+    """Return the docstring of the TradingStrategy protocol.
+
+    Read this before implementing a custom strategy — it's the exact
+    interface :func:`run_backtest` (and the live engine) drives.
+    """
+    from binance_quant_engine.strategy.protocol import TradingStrategy
+
+    return TradingStrategy.__doc__ or ""
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

binance_quant_engine/strategy/__init__.py

@@ -0,0 +1 @@
+"""Trading strategies (interface + reference demo)."""

binance_quant_engine/strategy/demo_squeeze.py

@@ -0,0 +1,183 @@
+"""Demo strategy — Bollinger Band squeeze mean-reversion.
+
+A deliberately simple, **public-domain** strategy that exists to exercise the
+engine end to end, not to make money.  It implements the
+:class:`~binance_quant_engine.strategy.protocol.TradingStrategy` contract so the backtester
+and the live scalper can both drive it without modification.
+
+Idea (textbook):
+    * A *squeeze* is a low-volatility regime — Bollinger Band width sits in the
+      bottom decile of its recent range.  Such compression often precedes
+      expansion.
+    * During a squeeze we fade extremes: a close below the lower band is a long
+      (mean-reversion up), a close above the upper band is a short.
+    * Each position carries a fixed stop-loss, take-profit, and an optional
+      trailing stop once it moves into profit.
+
+Discipline:
+    Every indicator reads only *completed* bars (the arrays passed in exclude
+    the in-progress candle).  No future data touches a signal — see
+    :mod:`binance_quant_engine.backtest.vectorized` for how the engine enforces this.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class SqueezeConfig:
+    """Strategy parameters (transparent, public defaults)."""
+
+    bb_period: int = 20            # Bollinger Band lookback
+    bb_std: float = 2.0           # band width in standard deviations
+    squeeze_lookback: int = 100    # window for the band-width percentile
+    squeeze_pct: float = 0.25      # "squeeze" if width <= this percentile
+    atr_period: int = 14
+    stop_loss: float = 0.02        # 2% hard stop
+    take_profit: float = 0.04      # 4% target
+    trail_distance: float = 0.01   # trail 1% behind peak once armed
+    trail_activate: float = 0.02   # arm the trail at +2% unrealised
+
+
+def _sma(x: np.ndarray, n: int) -> float:
+    return float(np.mean(x[-n:]))
+
+
+def _atr_pct(high: np.ndarray, low: np.ndarray, close: np.ndarray, n: int) -> float:
+    """ATR as a fraction of the last close (Wilder true range, simple mean)."""
+    if len(close) < n + 1:
+        return 0.0
+    tr = np.maximum.reduce([
+        high[-n:] - low[-n:],
+        np.abs(high[-n:] - close[-n - 1 : -1]),
+        np.abs(low[-n:] - close[-n - 1 : -1]),
+    ])
+    last = close[-1]
+    return float(np.mean(tr) / last) if last else 0.0
+
+
+class SqueezeStrategy:
+    """Reference implementation of :class:`TradingStrategy`."""
+
+    def __init__(self, config: SqueezeConfig | None = None) -> None:
+        self.config = config or SqueezeConfig()
+        self._positions: dict[str, dict] = {}
+        self._highs: dict[str, np.ndarray] = {}
+        self._lows: dict[str, np.ndarray] = {}
+        self._atr_pct: dict[str, float] = {}
+
+    # ── position book ────────────────────────────────────────────────
+
+    @property
+    def active_positions(self) -> dict[str, dict]:
+        return {k: dict(v) for k, v in self._positions.items()}
+
+    def has_position(self, symbol: str) -> bool:
+        return symbol in self._positions
+
+    # ── data feed ────────────────────────────────────────────────────
+
+    def update_market_data(
+        self, symbol: str, high: np.ndarray, low: np.ndarray, close: np.ndarray
+    ) -> None:
+        self._highs[symbol] = np.asarray(high, dtype=float)
+        self._lows[symbol] = np.asarray(low, dtype=float)
+        self._atr_pct[symbol] = _atr_pct(
+            self._highs[symbol], self._lows[symbol],
+            np.asarray(close, dtype=float), self.config.atr_period,
+        )
+
+    # ── signal ───────────────────────────────────────────────────────
+
+    def _band_width(self, close: np.ndarray) -> np.ndarray:
+        """Rolling Bollinger band width (upper-lower) / mid, per bar."""
+        c = self.config
+        n = c.bb_period
+        widths = np.full(len(close), np.nan)
+        for i in range(n, len(close) + 1):
+            window = close[i - n : i]
+            mid = window.mean()
+            sd = window.std()
+            if mid:
+                widths[i - 1] = (2 * c.bb_std * sd) / mid
+        return widths
+
+    def on_bar(self, symbol: str, close: np.ndarray) -> int:
+        c = self.config
+        close = np.asarray(close, dtype=float)
+        if len(close) < max(c.bb_period, c.squeeze_lookback):
+            return 0
+
+        widths = self._band_width(close)
+        cur_width = widths[-1]
+        ref = widths[-c.squeeze_lookback :]
+        ref = ref[~np.isnan(ref)]
+        if np.isnan(cur_width) or len(ref) < c.squeeze_lookback // 2:
+            return 0
+
+        # In a squeeze? (band width in the bottom `squeeze_pct` of recent range)
+        threshold = np.quantile(ref, c.squeeze_pct)
+        if cur_width > threshold:
+            return 0
+
+        mid = _sma(close, c.bb_period)
+        sd = float(close[-c.bb_period :].std())
+        upper, lower = mid + c.bb_std * sd, mid - c.bb_std * sd
+        price = close[-1]
+        if price < lower:
+            return 1   # fade the downside extreme
+        if price > upper:
+            return -1  # fade the upside extreme
+        return 0
+
+    def get_last_atr_pct(self, symbol: str) -> float:
+        return self._atr_pct.get(symbol, 0.0)
+
+    # ── lifecycle ────────────────────────────────────────────────────
+
+    def open_position(
+        self, symbol: str, signal: int, entry_price: float, atr_pct: float
+    ) -> None:
+        self._positions[symbol] = {
+            "signal": signal,
+            "entry_price": entry_price,
+            "atr_pct": atr_pct,
+            "peak_gain": 0.0,
+            "trail_active": False,
+        }
+
+    def update_position(
+        self,
+        symbol: str,
+        price: float,
+        high: float | None = None,
+        low: float | None = None,
+    ) -> str | None:
+        pos = self._positions.get(symbol)
+        if pos is None:
+            return None
+        c = self.config
+        direction = pos["signal"]
+        entry = pos["entry_price"]
+        # Unrealised gain in the position's favour.
+        gain = direction * (price - entry) / entry
+
+        if gain <= -c.stop_loss:
+            return "stop_loss"
+        if gain >= c.take_profit:
+            return "take_profit"
+
+        # Trailing stop: arm at +trail_activate, then exit if we give back
+        # trail_distance from the peak.
+        pos["peak_gain"] = max(pos["peak_gain"], gain)
+        if pos["peak_gain"] >= c.trail_activate:
+            pos["trail_active"] = True
+        if pos["trail_active"] and gain <= pos["peak_gain"] - c.trail_distance:
+            return "trailing_stop"
+        return None
+
+    def close_position(self, symbol: str) -> dict | None:
+        return self._positions.pop(symbol, None)

binance_quant_engine/strategy/protocol.py

@@ -0,0 +1,95 @@
+"""Strategy protocol — the formal contract every strategy must satisfy.
+
+The engine (backtester and live scalper alike) only ever talks to a strategy
+through this interface, never to a concrete class.  That decoupling is what lets
+the *same* engine run any strategy: a strategy is just an object that ingests
+bars, emits signals, and tracks its own open positions and exit conditions.
+
+Implemented via :pep:`544` structural subtyping — a strategy needs no base
+class, only these methods.  ``@runtime_checkable`` allows ``isinstance`` checks
+in tests.  The bundled :class:`~binance_quant_engine.strategy.demo_squeeze.SqueezeStrategy`
+is a reference implementation on public, textbook logic.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+
+@runtime_checkable
+class TradingStrategy(Protocol):
+    """Interface for a stateful trading strategy.
+
+    Signal convention (returned by :meth:`on_bar`):
+        ``-1`` short · ``0`` flat/no-signal · ``1`` long.
+
+    Per-bar flow driven by the engine:
+        1. :meth:`update_market_data` — feed the latest OHLCV window.
+        2. :meth:`on_bar` — emit a signal for a symbol.
+        3. :meth:`open_position` / :meth:`update_position` — lifecycle.
+    """
+
+    # ── position book ────────────────────────────────────────────────
+
+    @property
+    def active_positions(self) -> dict[str, dict]:
+        """Snapshot of open positions keyed by symbol."""
+        ...
+
+    def has_position(self, symbol: str) -> bool:
+        """Whether a position is currently open for *symbol*."""
+        ...
+
+    # ── data feed ────────────────────────────────────────────────────
+
+    def update_market_data(
+        self,
+        symbol: str,
+        high: np.ndarray,
+        low: np.ndarray,
+        close: np.ndarray,
+    ) -> None:
+        """Store the latest OHLC arrays for *symbol* before :meth:`on_bar`."""
+        ...
+
+    # ── signal generation ────────────────────────────────────────────
+
+    def on_bar(self, symbol: str, close: np.ndarray) -> int:
+        """Return a signal (``-1`` / ``0`` / ``1``) for the latest bar."""
+        ...
+
+    def get_last_atr_pct(self, symbol: str) -> float:
+        """Return the most recent ATR as a fraction of price (for sizing)."""
+        ...
+
+    # ── position lifecycle ───────────────────────────────────────────
+
+    def open_position(
+        self,
+        symbol: str,
+        signal: int,
+        entry_price: float,
+        atr_pct: float,
+    ) -> None:
+        """Record a newly opened position."""
+        ...
+
+    def update_position(
+        self,
+        symbol: str,
+        price: float,
+        high: float | None = None,
+        low: float | None = None,
+    ) -> str | None:
+        """Evaluate exit conditions for an open position.
+
+        Returns an exit-reason string (e.g. ``"stop_loss"``, ``"take_profit"``,
+        ``"trailing_stop"``) or ``None`` to keep the position open.
+        """
+        ...
+
+    def close_position(self, symbol: str) -> dict | None:
+        """Remove and return the position record, or ``None`` if absent."""
+        ...

binance_quant_engine-0.1.1.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: binance-quant-engine
+Version: 0.1.1
+Summary: Strategy-agnostic Binance USDT-M futures backtest & execution engine — no-look-ahead, backtest/live parity, optional MCP server
+Project-URL: Homepage, https://pypi.org/project/binance-quant-engine/
+Project-URL: Repository, https://github.com/younghwan91/binance-quant-engine
+Author-email: Younghwan Chae <chyohw97@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: algo-trading,backtest,binance,execution,futures,mcp,quant,trading
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: mcp>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-binance>=1.0.29; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: live
+Requires-Dist: python-binance>=1.0.29; extra == 'live'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Binance Quant Engine ⚙️
+
+[![CI](https://github.com/younghwan91/binance-quant-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/younghwan91/binance-quant-engine/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/binance-quant-engine.svg)](https://pypi.org/project/binance-quant-engine/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-younghwan--chae-0A66C2?logo=linkedin&logoColor=white)](https://www.linkedin.com/in/younghwan-chae/)
+
+**A strategy-agnostic Binance USDT-M futures backtest & execution engine.** Backtest and live trading run through the *same* strategy code, so a look-ahead bug can't exist in one and not the other — and an [MCP server](#mcp-server-let-an-agent-run-your-backtests) lets any MCP-compatible agent run backtests without writing a line of Python.
+
+Extracted from the infra layer of a real, currently-running Binance USDT-M futures bot — the alpha (strategy, parameters, live P&L) stays private; what's public is the part every retail algo trader rebuilds badly at least once: a backtester that can't cheat, and an execution layer that survives Binance's actual API quirks. The bundled demo strategy is textbook logic (Bollinger squeeze); it exists to exercise the engine end to end, not to make you money.
+
+> This repository supersedes `quantbox-engine`, which is no longer maintained. If you have that repo cloned, switch to this one.
+
+## Why not just write your own backtest loop?
+
+Because the failure modes here are the ones that quietly wreck a real account, not the ones a unit test catches:
+
+| Problem | What usually happens | What this engine does |
+|---|---|---|
+| Look-ahead bias | A signal computed over a full array accidentally sees future bars | The backtester physically hands the strategy only `close[: t + 1]` each step — there is no future in the array to peek at ([enforced by test](tests/test_backtest.py)) |
+| Backtest/live divergence | Backtest logic gets "ported" to the live bot and drifts | One `TradingStrategy` object, same method calls, same order, in both paths |
+| Binance tick-size rejection | A price a float-division away from the tick grid gets silently rejected or mispriced | [`round_to_tick`](src/binance_quant_engine/execution/utils.py) snaps every stop/limit/activation price to the symbol's grid before it leaves the process |
+| Dead-man's switch | Bot crashes → open position has no stop-loss | SL/TP/trailing stops are placed **on Binance's Algo Order API**, so the exchange — not your process — enforces the exit |
+
+## Quick start
+
+```bash
+pip install binance-quant-engine
+# or: uv add binance-quant-engine
+
+bqe-backtest --demo      # backtest the bundled demo strategy on synthetic data
+```
+
+![Demo backtest run](docs/images/demo-backtest.png)
+
+> ⚠️ The numbers above are from a **demo strategy on synthetic data**. They prove the engine runs; they say nothing about profitability.
+
+## Backtest your own data
+
+```python
+from binance_quant_engine.backtest.vectorized import run_backtest
+from binance_quant_engine.data.klines import load_csv
+from binance_quant_engine.strategy.demo_squeeze import SqueezeStrategy
+
+high, low, close = load_csv("BTCUSDT_1h.csv")   # columns: high,low,close
+result = run_backtest(SqueezeStrategy(), high, low, close, fee=0.0004, slippage=0.0002)
+print(result.summary())
+# {'n_trades': ..., 'total_return': ..., 'win_rate': ..., 'profit_factor': ..., 'max_drawdown': ...}
+```
+
+Bring your own strategy by implementing [`TradingStrategy`](src/binance_quant_engine/strategy/protocol.py) — a `typing.Protocol`, no base class required. Wiring it into live execution: [docs/USAGE.md](docs/USAGE.md).
+
+## MCP server — let an agent run your backtests
+
+```bash
+pip install "binance-quant-engine[mcp]"
+binance-quant-engine-mcp   # stdio MCP server
+```
+
+Exposes `run_demo_backtest`, `backtest_csv`, and `describe_strategy_protocol` to any MCP client (Claude Code, Claude Desktop, etc.) — point an agent at a CSV of OHLC data and it can backtest a strategy idea in the same turn, no local Python environment required on the agent's side.
+
+**This is deliberately backtest-only.** Nothing under `execution/` (order placement, cancellation, bracket management) is reachable through the MCP server — there is no tool call that can touch a live Binance order. If you want an agent that also *trades*, that's a decision you wire yourself, explicitly, outside this server.
+
+## Design
+
+| Design choice | How |
+|---|---|
+| **No-look-ahead by construction** | The backtester hands the strategy `close[:t+1]` (bars completed as of now) every step — there's no future in the array to see. |
+| **Backtest = live, same code** | The same `TradingStrategy` object is driven by the backtester and the live bot, in the same call order. No reimplementation gap. |
+| **Pluggable strategy** | The engine only ever talks to a strategy through [`TradingStrategy`](src/binance_quant_engine/strategy/protocol.py) (PEP 544). No inheritance required. |
+| **Costs are net, not gross** | Taker fee + slippage charged on both entry and exit legs. |
+| **Server-side exits** | SL/TP/trailing stops live on Binance's Algo Order API — the exchange enforces them even if your process dies. ([brackets.py](src/binance_quant_engine/execution/brackets.py)) |
+| **Tick-safe prices** | Every price sent to the exchange is snapped to the symbol's tick grid first ([utils.py](src/binance_quant_engine/execution/utils.py)) — a category of Binance rejection this engine doesn't have. |
+
+## Structure
+
+**Decide** (strategy) / **measure** (backtest) / **execute** (live) are kept apart and meet only at `TradingStrategy`.
+
+```mermaid
+flowchart LR
+    subgraph Data["binance_quant_engine/data/"]
+        CSV[("OHLCV CSV\nload_csv()")]
+        SYN[["synth_ohlcv()\nsynthetic data"]]
+        CACHE["cache.py\nmemory + gzip cache"]
+    end
+
+    subgraph Decide["binance_quant_engine/strategy/ — decide"]
+        PROTO{{"TradingStrategy\n(PEP 544 protocol)"}}
+        SQZ["demo_squeeze.py\nSqueezeStrategy"]
+        PROTO -.implements.-> SQZ
+    end
+
+    CSV --> BT
+    SYN --> BT
+    CACHE -.caches.-> CSV
+
+    subgraph Measure["binance_quant_engine/backtest/ — measure"]
+        BT["vectorized.run_backtest()\nhands close[:t+1] only\n(no look-ahead)"]
+        RES["BacktestResult\ntrades · equity curve · MDD"]
+        BT --> RES
+    end
+
+    BT <-->|"update_market_data / on_bar\nopen·update·close_position"| PROTO
+
+    subgraph Execute["binance_quant_engine/execution/ — execute (.[live])"]
+        HOST["host.py\nScalperProtocol (live bot host)"]
+        BRACKET["brackets.py\nBracketMixin — SL/TP/trailing"]
+        UTIL["utils.py\nround_to_tick · dead-status set"]
+        ALGO["algo_api.py\nAlgoApiClient"]
+        HOST --> BRACKET --> ALGO
+        BRACKET -.-> UTIL
+    end
+
+    subgraph MCP["binance_quant_engine/mcp/ — optional (.[mcp])"]
+        SRV["server.py\nrun_demo_backtest · backtest_csv"]
+    end
+    BT -.callable via.-> SRV
+
+    PROTO ==same interface\n(backtest = live)==> HOST
+    ALGO --> BINANCE[("Binance USDT-M\nFutures Algo Order API")]
+```
+
+- How to plug in a strategy and wire up live execution → [docs/USAGE.md](docs/USAGE.md)
+- Design rationale for no-look-ahead, backtest/live parity, and the cost model → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+
+## License
+
+MIT
+
+---
+
+Bugs and questions → [Issues](https://github.com/younghwan91/binance-quant-engine/issues).
+
+**Younghwan Chae** · [GitHub @younghwan91](https://github.com/younghwan91) · [LinkedIn](https://www.linkedin.com/in/younghwan-chae/) — other open-source quant projects (Korean equities, US equities, crypto) are on the [profile page](https://github.com/younghwan91).