backtest-kit 3.8.1 → 4.0.1

package/README.md

@@ -46,6 +46,7 @@ npm install backtest-kit ccxt ollama uuid
 - 📊 **Reports & Metrics**: Auto Markdown reports with PNL, Sharpe Ratio, win rate, and more.
 - 🛡️ **Risk Management**: Custom rules for position limits, time windows, and multi-strategy coordination.
 - 🔌 **Pluggable**: Custom data sources (CCXT), persistence (file/Redis), and sizing calculators.
+- 🗃️ **Transactional Live Orders**: Broker adapter intercepts every trade mutation before internal state changes — exchange rejection rolls back the operation atomically.
 - 🧪 **Tested**: 350+ unit/integration tests for validation, recovery, and events.
 - 🔓 **Self hosted**: Zero dependency on third-party node_modules or platforms; run entirely in your own environment.
 
@@ -208,9 +209,9 @@ Customize via `setConfig()`:
 
 Backtest Kit is **not a data-processing library** - it is a **time execution engine**. Think of the engine as an **async stream of time**, where your strategy is evaluated step by step.
 
-### 💰 How PNL Works
+### 🔍 How PNL Works
 
-These three functions work together to manage a position dynamically. To reduce position linearity, the framework treats every DCA entry as a fixed **$100 unit** regardless of price — this flattens the effective entry curve and makes PNL weighting independent of position size.
+These three functions work together to dynamically manage the position. To reduce position linearity, by default, each DCA entry is formatted as a fixed **unit of $100**. This can be changed. No mathematical knowledge is required.
 
 **Public API:**
 - **`commitAverageBuy`** — adds a new DCA entry. For LONG, **only accepted when current price is below a new low**. Silently rejected otherwise. This prevents averaging up. Can be overridden using `setConfig`
@@ -317,6 +318,906 @@ These three functions work together to manage a position dynamically. To reduce
 
 **`priceOpen`** is the harmonic mean of all accepted DCA entries. After each partial close (`commitPartialProfit` or `commitPartialLoss`), the remaining cost basis is carried forward into the harmonic mean calculation for subsequent entries — so `priceOpen` shifts after every partial, which in turn changes whether the next `commitAverageBuy` call will be accepted.
 
+### 🔍 How Broker Transactional Integrity Works
+
+`Broker.useBrokerAdapter` connects a live exchange (ccxt, Binance, etc.) to the framework with transaction safety. Every commit method fires **before** the internal position state mutates. If the exchange rejects the order, the fill times out, or the network fails, the adapter throws, the mutation is skipped, and backtest-kit retries automatically on the next tick.
+
+<details>
+  <summary>
+    The code
+  </summary>
+
+**Spot**
+
+```typescript
+import ccxt from "ccxt";
+import { singleshot, sleep } from "functools-kit";
+import {
+  Broker,
+  IBroker,
+  BrokerSignalOpenPayload,
+  BrokerSignalClosePayload,
+  BrokerPartialProfitPayload,
+  BrokerPartialLossPayload,
+  BrokerTrailingStopPayload,
+  BrokerTrailingTakePayload,
+  BrokerBreakevenPayload,
+  BrokerAverageBuyPayload,
+} from "backtest-kit";
+
+const FILL_POLL_INTERVAL_MS = 10_000;
+const FILL_POLL_ATTEMPTS = 10;
+
+/**
+ * Sleep between cancelOrder and fetchBalance to allow Binance to settle the
+ * cancellation — reads immediately after cancel may return stale data.
+ */
+const CANCEL_SETTLE_MS = 2_000;
+
+/**
+ * Slippage buffer for stop_loss_limit on Spot — limit price is set slightly
+ * below stopPrice so the order fills even on a gap down instead of hanging.
+ */
+const STOP_LIMIT_SLIPPAGE = 0.995;
+
+const getSpotExchange = singleshot(async () => {
+  const exchange = new ccxt.binance({
+    apiKey: process.env.BINANCE_API_KEY,
+    secret: process.env.BINANCE_API_SECRET,
+    options: {
+      defaultType: "spot",
+      adjustForTimeDifference: true,
+      recvWindow: 60000,
+    },
+    enableRateLimit: true,
+  });
+  await exchange.loadMarkets();
+  return exchange;
+});
+
+/**
+ * Resolve base currency from market metadata — safe for all quote currencies (USDT, USDC, FDUSD, etc.)
+ */
+function getBase(exchange: ccxt.binance, symbol: string): string {
+  return exchange.markets[symbol].base;
+}
+
+/**
+ * Truncate qty to exchange precision, always rounding down.
+ * Prevents over-selling due to floating point drift from fetchBalance.
+ */
+function truncateQty(exchange: ccxt.binance, symbol: string, qty: number): number {
+  return parseFloat(exchange.amountToPrecision(symbol, qty, exchange.TRUNCATE));
+}
+
+/**
+ * Fetch current free balance for base currency of symbol.
+ */
+async function fetchFreeQty(exchange: ccxt.binance, symbol: string): Promise<number> {
+  const balance = await exchange.fetchBalance();
+  const base    = getBase(exchange, symbol);
+  return parseFloat(String(balance?.free?.[base] ?? 0));
+}
+
+/**
+ * Cancel all orders in parallel — allSettled so a single failure (already filled,
+ * network blip) does not leave remaining orders uncancelled.
+ */
+async function cancelAllOrders(exchange: ccxt.binance, orders: ccxt.Order[], symbol: string): Promise<void> {
+  await Promise.allSettled(orders.map((o) => exchange.cancelOrder(o.id, symbol)));
+}
+
+/**
+ * Place a stop_loss_limit sell order with a slippage buffer on the limit price.
+ * stop_loss_limit requires both stopPrice (trigger) and price (limit fill).
+ * Setting them equal risks non-fill on gap down — limit is offset by STOP_LIMIT_SLIPPAGE.
+ */
+async function createStopLossOrder(
+  exchange: ccxt.binance,
+  symbol: string,
+  qty: number,
+  stopPrice: number
+): Promise<void> {
+  const limitPrice = parseFloat(exchange.priceToPrecision(symbol, stopPrice * STOP_LIMIT_SLIPPAGE));
+  await exchange.createOrder(symbol, "stop_loss_limit", "sell", qty, limitPrice, { stopPrice });
+}
+
+/**
+ * Place a limit order and poll until filled (status === "closed").
+ * On timeout: cancel the order, settle, check partial fill and sell it via market,
+ * restore SL/TP on remaining position so it is never left unprotected, then throw.
+ */
+async function createLimitOrderAndWait(
+  exchange: ccxt.binance,
+  symbol: string,
+  side: "buy" | "sell",
+  qty: number,
+  price: number,
+  restore?: { tpPrice: number; slPrice: number }
+): Promise<void> {
+  const order = await exchange.createOrder(symbol, "limit", side, qty, price);
+
+  for (let i = 0; i < FILL_POLL_ATTEMPTS; i++) {
+    await sleep(FILL_POLL_INTERVAL_MS);
+    const status = await exchange.fetchOrder(order.id, symbol);
+    if (status.status === "closed") {
+      return;
+    }
+  }
+
+  await exchange.cancelOrder(order.id, symbol);
+
+  // Wait for Binance to settle the cancellation before reading filled qty
+  await sleep(CANCEL_SETTLE_MS);
+
+  const final     = await exchange.fetchOrder(order.id, symbol);
+  const filledQty = final.filled ?? 0;
+
+  if (filledQty > 0) {
+    // Sell partial fill via market to restore clean exchange state before backtest-kit retries
+    const rollbackSide = side === "buy" ? "sell" : "buy";
+    await exchange.createOrder(symbol, "market", rollbackSide, filledQty);
+  }
+
+  // Restore SL/TP on remaining position so it is not left unprotected during retry
+  if (restore) {
+    const remainingQty = truncateQty(exchange, symbol, await fetchFreeQty(exchange, symbol));
+    if (remainingQty > 0) {
+      await exchange.createOrder(symbol, "limit", "sell", remainingQty, restore.tpPrice);
+      await createStopLossOrder(exchange, symbol, remainingQty, restore.slPrice);
+    }
+  }
+
+  throw new Error(`Limit order ${order.id} [${side} ${qty} ${symbol} @ ${price}] not filled in time — partial fill rolled back, backtest-kit will retry`);
+}
+
+Broker.useBrokerAdapter(
+  class implements IBroker {
+
+    async waitForInit(): Promise<void> {
+      await getSpotExchange();
+    }
+
+    async onSignalOpenCommit(payload: BrokerSignalOpenPayload): Promise<void> {
+      const { symbol, cost, priceOpen, priceTakeProfit, priceStopLoss, position } = payload;
+
+      // Spot does not support short selling — reject immediately so backtest-kit skips the mutation
+      if (position === "short") {
+        throw new Error(`SpotBrokerAdapter: short position is not supported on spot (symbol=${symbol})`);
+      }
+
+      const exchange = await getSpotExchange();
+
+      const qty = truncateQty(exchange, symbol, cost / priceOpen);
+
+      // Guard: truncation may produce 0 if cost/price is below lot size
+      if (qty <= 0) {
+        throw new Error(`Computed qty is zero for ${symbol} — cost=${cost}, price=${priceOpen}`);
+      }
+
+      const openPrice = parseFloat(exchange.priceToPrecision(symbol, priceOpen));
+      const tpPrice   = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice   = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+
+      // Entry: no restore needed — position does not exist yet if entry times out
+      await createLimitOrderAndWait(exchange, symbol, "buy", qty, openPrice);
+
+      // Post-fill: if TP/SL placement fails, position is open and unprotected — close via market
+      try {
+        await exchange.createOrder(symbol, "limit", "sell", qty, tpPrice);
+        await createStopLossOrder(exchange, symbol, qty, slPrice);
+      } catch (err) {
+        await exchange.createOrder(symbol, "market", "sell", qty);
+        throw err;
+      }
+    }
+
+    async onSignalCloseCommit(payload: BrokerSignalClosePayload): Promise<void> {
+      const { symbol, currentPrice, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getSpotExchange();
+
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      const qty = truncateQty(exchange, symbol, await fetchFreeQty(exchange, symbol));
+
+      // Position already closed by SL/TP on exchange — nothing to do, commit succeeds
+      if (qty === 0) {
+        return;
+      }
+
+      const closePrice = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice    = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice    = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+
+      // Restore SL/TP if close times out so position is not left unprotected during retry
+      await createLimitOrderAndWait(exchange, symbol, "sell", qty, closePrice, { tpPrice, slPrice });
+    }
+
+    async onPartialProfitCommit(payload: BrokerPartialProfitPayload): Promise<void> {
+      const { symbol, percentToClose, currentPrice, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getSpotExchange();
+
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      const totalQty = await fetchFreeQty(exchange, symbol);
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (totalQty === 0) {
+        throw new Error(`PartialProfit skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const qty          = truncateQty(exchange, symbol, totalQty * (percentToClose / 100));
+      const remainingQty = truncateQty(exchange, symbol, totalQty - qty);
+      const closePrice   = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice      = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+
+      // Restore SL/TP on remaining qty if partial close times out so position is not left unprotected
+      await createLimitOrderAndWait(exchange, symbol, "sell", qty, closePrice, { tpPrice, slPrice });
+
+      // Restore SL/TP on remaining qty after successful partial close
+      if (remainingQty > 0) {
+        try {
+          await exchange.createOrder(symbol, "limit", "sell", remainingQty, tpPrice);
+          await createStopLossOrder(exchange, symbol, remainingQty, slPrice);
+        } catch (err) {
+          // Remaining position is unprotected — close via market
+          await exchange.createOrder(symbol, "market", "sell", remainingQty);
+          throw err;
+        }
+      }
+    }
+
+    async onPartialLossCommit(payload: BrokerPartialLossPayload): Promise<void> {
+      const { symbol, percentToClose, currentPrice, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getSpotExchange();
+
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      const totalQty = await fetchFreeQty(exchange, symbol);
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (totalQty === 0) {
+        throw new Error(`PartialLoss skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const qty          = truncateQty(exchange, symbol, totalQty * (percentToClose / 100));
+      const remainingQty = truncateQty(exchange, symbol, totalQty - qty);
+      const closePrice   = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice      = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+
+      // Restore SL/TP on remaining qty if partial close times out so position is not left unprotected
+      await createLimitOrderAndWait(exchange, symbol, "sell", qty, closePrice, { tpPrice, slPrice });
+
+      // Restore SL/TP on remaining qty after successful partial close
+      if (remainingQty > 0) {
+        try {
+          await exchange.createOrder(symbol, "limit", "sell", remainingQty, tpPrice);
+          await createStopLossOrder(exchange, symbol, remainingQty, slPrice);
+        } catch (err) {
+          // Remaining position is unprotected — close via market
+          await exchange.createOrder(symbol, "market", "sell", remainingQty);
+          throw err;
+        }
+      }
+    }
+
+    async onTrailingStopCommit(payload: BrokerTrailingStopPayload): Promise<void> {
+      const { symbol, newStopLossPrice } = payload;
+      const exchange = await getSpotExchange();
+
+      // Cancel existing SL order only — Spot has no reduceOnly, filter by side + type
+      const orders  = await exchange.fetchOpenOrders(symbol);
+      const slOrder = orders.find((o) =>
+        o.side === "sell" &&
+        ["stop_loss_limit", "stop", "STOP_LOSS_LIMIT"].includes(o.type ?? "")
+      ) ?? null;
+      if (slOrder) {
+        await exchange.cancelOrder(slOrder.id, symbol);
+        await sleep(CANCEL_SETTLE_MS);
+      }
+
+      const qty = truncateQty(exchange, symbol, await fetchFreeQty(exchange, symbol));
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (qty === 0) {
+        throw new Error(`TrailingStop skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const slPrice = parseFloat(exchange.priceToPrecision(symbol, newStopLossPrice));
+
+      await createStopLossOrder(exchange, symbol, qty, slPrice);
+    }
+
+    async onTrailingTakeCommit(payload: BrokerTrailingTakePayload): Promise<void> {
+      const { symbol, newTakeProfitPrice } = payload;
+      const exchange = await getSpotExchange();
+
+      // Cancel existing TP order only — Spot has no reduceOnly, filter by side + type
+      const orders  = await exchange.fetchOpenOrders(symbol);
+      const tpOrder = orders.find((o) =>
+        o.side === "sell" &&
+        ["limit", "LIMIT"].includes(o.type ?? "")
+      ) ?? null;
+      if (tpOrder) {
+        await exchange.cancelOrder(tpOrder.id, symbol);
+        await sleep(CANCEL_SETTLE_MS);
+      }
+
+      const qty = truncateQty(exchange, symbol, await fetchFreeQty(exchange, symbol));
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (qty === 0) {
+        throw new Error(`TrailingTake skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const tpPrice = parseFloat(exchange.priceToPrecision(symbol, newTakeProfitPrice));
+
+      await exchange.createOrder(symbol, "limit", "sell", qty, tpPrice);
+    }
+
+    async onBreakevenCommit(payload: BrokerBreakevenPayload): Promise<void> {
+      const { symbol, newStopLossPrice } = payload;
+      const exchange = await getSpotExchange();
+
+      // Cancel existing SL order only — Spot has no reduceOnly, filter by side + type
+      const orders  = await exchange.fetchOpenOrders(symbol);
+      const slOrder = orders.find((o) =>
+        o.side === "sell" &&
+        ["stop_loss_limit", "stop", "STOP_LOSS_LIMIT"].includes(o.type ?? "")
+      ) ?? null;
+      if (slOrder) {
+        await exchange.cancelOrder(slOrder.id, symbol);
+        await sleep(CANCEL_SETTLE_MS);
+      }
+
+      const qty = truncateQty(exchange, symbol, await fetchFreeQty(exchange, symbol));
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (qty === 0) {
+        throw new Error(`Breakeven skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const slPrice = parseFloat(exchange.priceToPrecision(symbol, newStopLossPrice));
+
+      await createStopLossOrder(exchange, symbol, qty, slPrice);
+    }
+
+    async onAverageBuyCommit(payload: BrokerAverageBuyPayload): Promise<void> {
+      const { symbol, currentPrice, cost, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getSpotExchange();
+
+      // Cancel existing SL/TP first — existing check must happen after cancel+settle
+      // to avoid race condition where SL/TP fills between the existence check and cancel
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      // Guard against DCA into a ghost position — checked after cancel so the snapshot is fresh
+      const existing    = await fetchFreeQty(exchange, symbol);
+      const minNotional = exchange.markets[symbol].limits?.cost?.min ?? 1;
+
+      // Compare notional value rather than raw qty — avoids float === 0 trap
+      // and correctly rejects dust balances left over from previous trades
+      if (existing * currentPrice < minNotional) {
+        throw new Error(`AverageBuy skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const qty = truncateQty(exchange, symbol, cost / currentPrice);
+
+      // Guard: truncation may produce 0 if cost/price is below lot size
+      if (qty <= 0) {
+        throw new Error(`Computed qty is zero for ${symbol} — cost=${cost}, price=${currentPrice}`);
+      }
+
+      const entryPrice = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice    = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice    = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+
+      // DCA entry: restore SL/TP on existing qty if times out so position is not left unprotected
+      await createLimitOrderAndWait(exchange, symbol, "buy", qty, entryPrice, { tpPrice, slPrice });
+
+      // Refetch balance after fill — existing snapshot is stale after cancel + fill
+      const totalQty = truncateQty(exchange, symbol, await fetchFreeQty(exchange, symbol));
+
+      // Recreate SL/TP on fresh total qty after successful fill
+      try {
+        await exchange.createOrder(symbol, "limit", "sell", totalQty, tpPrice);
+        await createStopLossOrder(exchange, symbol, totalQty, slPrice);
+      } catch (err) {
+        // Total position is unprotected — close via market
+        await exchange.createOrder(symbol, "market", "sell", totalQty);
+        throw err;
+      }
+    }
+  }
+);
+
+Broker.enable();
+```
+
+**Futures**
+
+```typescript
+import ccxt from "ccxt";
+import { singleshot, sleep } from "functools-kit";
+import {
+  Broker,
+  IBroker,
+  BrokerSignalOpenPayload,
+  BrokerSignalClosePayload,
+  BrokerPartialProfitPayload,
+  BrokerPartialLossPayload,
+  BrokerTrailingStopPayload,
+  BrokerTrailingTakePayload,
+  BrokerBreakevenPayload,
+  BrokerAverageBuyPayload,
+} from "backtest-kit";
+
+const FILL_POLL_INTERVAL_MS = 10_000;
+const FILL_POLL_ATTEMPTS = 10;
+
+/**
+ * Sleep between cancelOrder and fetchPositions to allow Binance to settle the
+ * cancellation — reads immediately after cancel may return stale data.
+ */
+const CANCEL_SETTLE_MS = 2_000;
+
+/**
+ * 3x leverage — conservative choice for $1000 total fiat.
+ * Enough to matter, not enough to liquidate on normal volatility.
+ * Applied per-symbol on first open via setLeverage.
+ */
+const FUTURES_LEVERAGE = 3;
+
+const getFuturesExchange = singleshot(async () => {
+  const exchange = new ccxt.binance({
+    apiKey: process.env.BINANCE_API_KEY,
+    secret: process.env.BINANCE_API_SECRET,
+    options: {
+      defaultType: "future",
+      adjustForTimeDifference: true,
+      recvWindow: 60000,
+    },
+    enableRateLimit: true,
+  });
+  await exchange.loadMarkets();
+  return exchange;
+});
+
+/**
+ * Truncate qty to exchange precision, always rounding down.
+ * Prevents over-selling due to floating point drift from fetchPositions.
+ */
+function truncateQty(exchange: ccxt.binance, symbol: string, qty: number): number {
+  return parseFloat(exchange.amountToPrecision(symbol, qty, exchange.TRUNCATE));
+}
+
+/**
+ * Resolve position for symbol filtered by side — safe in both one-way and hedge mode.
+ */
+function findPosition(positions: ccxt.Position[], symbol: string, side: "long" | "short") {
+  // Hedge mode: positions have explicit side field
+  const hedged = positions.find((p) => p.symbol === symbol && p.side === side);
+  if (hedged) {
+    return hedged;
+  }
+  // One-way mode: single position per symbol, side field may be undefined or mismatched
+  const pos = positions.find((p) => p.symbol === symbol) ?? null;
+  if (pos && pos.side && pos.side !== side) {
+    console.warn(`findPosition: expected side="${side}" but exchange returned side="${pos.side}" for ${symbol} — possible one-way/hedge mode mismatch`);
+  }
+  return pos;
+}
+
+/**
+ * Fetch current contracts qty for symbol/side.
+ */
+async function fetchContractsQty(
+  exchange: ccxt.binance,
+  symbol: string,
+  side: "long" | "short"
+): Promise<number> {
+  const positions = await exchange.fetchPositions([symbol]);
+  const pos       = findPosition(positions, symbol, side);
+  return Math.abs(parseFloat(String(pos?.contracts ?? 0)));
+}
+
+/**
+ * Cancel all orders in parallel — allSettled so a single failure (already filled,
+ * network blip) does not leave remaining orders uncancelled.
+ */
+async function cancelAllOrders(exchange: ccxt.binance, orders: ccxt.Order[], symbol: string): Promise<void> {
+  await Promise.allSettled(orders.map((o) => exchange.cancelOrder(o.id, symbol)));
+}
+
+/**
+ * Resolve Binance positionSide string from position direction.
+ * Required in hedge mode to correctly route orders; ignored in one-way mode.
+ */
+function toPositionSide(position: "long" | "short"): "LONG" | "SHORT" {
+  return position === "long" ? "LONG" : "SHORT";
+}
+
+/**
+ * Place a limit order and poll until filled (status === "closed").
+ * On timeout: cancel the order, settle, check partial fill and close it via market,
+ * restore SL/TP on remaining position so it is never left unprotected, then throw.
+ *
+ * positionSide is forwarded into rollback market order so hedge mode accounts
+ * correctly route the close without -4061 error.
+ */
+async function createLimitOrderAndWait(
+  exchange: ccxt.binance,
+  symbol: string,
+  side: "buy" | "sell",
+  qty: number,
+  price: number,
+  params: Record<string, unknown> = {},
+  restore?: { exitSide: "buy" | "sell"; tpPrice: number; slPrice: number; positionSide: "long" | "short" }
+): Promise<void> {
+  const order = await exchange.createOrder(symbol, "limit", side, qty, price, params);
+
+  for (let i = 0; i < FILL_POLL_ATTEMPTS; i++) {
+    await sleep(FILL_POLL_INTERVAL_MS);
+    const status = await exchange.fetchOrder(order.id, symbol);
+    if (status.status === "closed") {
+      return;
+    }
+  }
+
+  await exchange.cancelOrder(order.id, symbol);
+
+  // Wait for Binance to settle the cancellation before reading filled qty
+  await sleep(CANCEL_SETTLE_MS);
+
+  const final     = await exchange.fetchOrder(order.id, symbol);
+  const filledQty = final.filled ?? 0;
+
+  if (filledQty > 0) {
+    // Close partial fill via market — positionSide required in hedge mode (-4061 without it)
+    const rollbackSide        = side === "buy" ? "sell" : "buy";
+    const rollbackPositionSide = params.positionSide ?? (restore ? toPositionSide(restore.positionSide) : undefined);
+    await exchange.createOrder(symbol, "market", rollbackSide, filledQty, undefined, {
+      reduceOnly: true,
+      ...(rollbackPositionSide ? { positionSide: rollbackPositionSide } : {}),
+    });
+  }
+
+  // Restore SL/TP on remaining position so it is not left unprotected during retry
+  if (restore) {
+    const remainingQty = truncateQty(exchange, symbol, await fetchContractsQty(exchange, symbol, restore.positionSide));
+    if (remainingQty > 0) {
+      await exchange.createOrder(symbol, "limit", restore.exitSide, remainingQty, restore.tpPrice, { reduceOnly: true });
+      await exchange.createOrder(symbol, "stop_market", restore.exitSide, remainingQty, undefined, { stopPrice: restore.slPrice, reduceOnly: true });
+    }
+  }
+
+  throw new Error(`Limit order ${order.id} [${side} ${qty} ${symbol} @ ${price}] not filled in time — partial fill rolled back, backtest-kit will retry`);
+}
+
+Broker.useBrokerAdapter(
+  class implements IBroker {
+
+    async waitForInit(): Promise<void> {
+      await getFuturesExchange();
+    }
+
+    async onSignalOpenCommit(payload: BrokerSignalOpenPayload): Promise<void> {
+      const { symbol, cost, priceOpen, priceTakeProfit, priceStopLoss, position } = payload;
+      const exchange = await getFuturesExchange();
+
+      // Set leverage before entry — ensures consistent leverage regardless of previous session state
+      await exchange.setLeverage(FUTURES_LEVERAGE, symbol);
+
+      const qty = truncateQty(exchange, symbol, cost / priceOpen);
+
+      // Guard: truncation may produce 0 if cost/price is below lot size
+      if (qty <= 0) {
+        throw new Error(`Computed qty is zero for ${symbol} — cost=${cost}, price=${priceOpen}`);
+      }
+
+      const openPrice    = parseFloat(exchange.priceToPrecision(symbol, priceOpen));
+      const tpPrice      = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+      const entrySide    = position === "long" ? "buy"  : "sell";
+      const exitSide     = position === "long" ? "sell" : "buy";
+      // positionSide required in hedge mode (-4061 without it); ignored in one-way mode
+      const positionSide = toPositionSide(position);
+
+      // Entry: no restore needed — position does not exist yet if entry times out
+      await createLimitOrderAndWait(exchange, symbol, entrySide, qty, openPrice, { positionSide });
+
+      // Post-fill: if TP/SL placement fails, position is open and unprotected — close via market
+      try {
+        await exchange.createOrder(symbol, "limit", exitSide, qty, tpPrice, { reduceOnly: true, positionSide });
+        await exchange.createOrder(symbol, "stop_market", exitSide, qty, undefined, { stopPrice: slPrice, reduceOnly: true, positionSide });
+      } catch (err) {
+        await exchange.createOrder(symbol, "market", exitSide, qty, undefined, { reduceOnly: true, positionSide });
+        throw err;
+      }
+    }
+
+    async onSignalCloseCommit(payload: BrokerSignalClosePayload): Promise<void> {
+      const { symbol, position, currentPrice, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getFuturesExchange();
+
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      const qty      = truncateQty(exchange, symbol, await fetchContractsQty(exchange, symbol, position));
+      const exitSide = position === "long" ? "sell" : "buy";
+
+      // Position already closed by SL/TP on exchange — throw so backtest-kit can reconcile
+      // the close price via its own mechanism rather than assuming a successful manual close
+      if (qty === 0) {
+        throw new Error(`SignalClose skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const closePrice = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice    = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice    = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+
+      // reduceOnly: prevents accidental reversal if qty has drift vs real position
+      // Restore SL/TP if close times out so position is not left unprotected during retry
+      await createLimitOrderAndWait(
+        exchange, symbol, exitSide, qty, closePrice,
+        { reduceOnly: true },
+        { exitSide, tpPrice, slPrice, positionSide: position }
+      );
+    }
+
+    async onPartialProfitCommit(payload: BrokerPartialProfitPayload): Promise<void> {
+      const { symbol, percentToClose, currentPrice, position, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getFuturesExchange();
+
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      const totalQty = await fetchContractsQty(exchange, symbol, position);
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (totalQty === 0) {
+        throw new Error(`PartialProfit skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const qty          = truncateQty(exchange, symbol, totalQty * (percentToClose / 100));
+      const remainingQty = truncateQty(exchange, symbol, totalQty - qty);
+      const closePrice   = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice      = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+      const exitSide     = position === "long" ? "sell" : "buy";
+      const positionSide = toPositionSide(position);
+
+      // reduceOnly: prevents accidental reversal if qty has drift vs real position
+      // Restore SL/TP on remaining qty if partial close times out so position is not left unprotected
+      await createLimitOrderAndWait(
+        exchange, symbol, exitSide, qty, closePrice,
+        { reduceOnly: true },
+        { exitSide, tpPrice, slPrice, positionSide: position }
+      );
+
+      // Restore SL/TP on remaining qty after successful partial close
+      if (remainingQty > 0) {
+        try {
+          await exchange.createOrder(symbol, "limit", exitSide, remainingQty, tpPrice, { reduceOnly: true, positionSide });
+          await exchange.createOrder(symbol, "stop_market", exitSide, remainingQty, undefined, { stopPrice: slPrice, reduceOnly: true, positionSide });
+        } catch (err) {
+          // Remaining position is unprotected — close via market
+          await exchange.createOrder(symbol, "market", exitSide, remainingQty, undefined, { reduceOnly: true, positionSide });
+          throw err;
+        }
+      }
+    }
+
+    async onPartialLossCommit(payload: BrokerPartialLossPayload): Promise<void> {
+      const { symbol, percentToClose, currentPrice, position, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getFuturesExchange();
+
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      const totalQty = await fetchContractsQty(exchange, symbol, position);
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (totalQty === 0) {
+        throw new Error(`PartialLoss skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const qty          = truncateQty(exchange, symbol, totalQty * (percentToClose / 100));
+      const remainingQty = truncateQty(exchange, symbol, totalQty - qty);
+      const closePrice   = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice      = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+      const exitSide     = position === "long" ? "sell" : "buy";
+      const positionSide = toPositionSide(position);
+
+      // reduceOnly: prevents accidental reversal if qty has drift vs real position
+      // Restore SL/TP on remaining qty if partial close times out so position is not left unprotected
+      await createLimitOrderAndWait(
+        exchange, symbol, exitSide, qty, closePrice,
+        { reduceOnly: true },
+        { exitSide, tpPrice, slPrice, positionSide: position }
+      );
+
+      // Restore SL/TP on remaining qty after successful partial close
+      if (remainingQty > 0) {
+        try {
+          await exchange.createOrder(symbol, "limit", exitSide, remainingQty, tpPrice, { reduceOnly: true, positionSide });
+          await exchange.createOrder(symbol, "stop_market", exitSide, remainingQty, undefined, { stopPrice: slPrice, reduceOnly: true, positionSide });
+        } catch (err) {
+          // Remaining position is unprotected — close via market
+          await exchange.createOrder(symbol, "market", exitSide, remainingQty, undefined, { reduceOnly: true, positionSide });
+          throw err;
+        }
+      }
+    }
+
+    async onTrailingStopCommit(payload: BrokerTrailingStopPayload): Promise<void> {
+      const { symbol, newStopLossPrice, position } = payload;
+      const exchange = await getFuturesExchange();
+
+      // Cancel existing SL order only — filter by reduceOnly to avoid cancelling unrelated orders
+      const orders  = await exchange.fetchOpenOrders(symbol);
+      const slOrder = orders.find((o) =>
+        !!o.reduceOnly &&
+        ["stop_market", "stop", "STOP_MARKET"].includes(o.type ?? "")
+      ) ?? null;
+      if (slOrder) {
+        await exchange.cancelOrder(slOrder.id, symbol);
+        await sleep(CANCEL_SETTLE_MS);
+      }
+
+      const qty      = truncateQty(exchange, symbol, await fetchContractsQty(exchange, symbol, position));
+      const exitSide = position === "long" ? "sell" : "buy";
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (qty === 0) {
+        throw new Error(`TrailingStop skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, newStopLossPrice));
+      const positionSide = toPositionSide(position);
+
+      // positionSide required in hedge mode (-4061 without it); ignored in one-way mode
+      await exchange.createOrder(symbol, "stop_market", exitSide, qty, undefined, { stopPrice: slPrice, reduceOnly: true, positionSide });
+    }
+
+    async onTrailingTakeCommit(payload: BrokerTrailingTakePayload): Promise<void> {
+      const { symbol, newTakeProfitPrice, position } = payload;
+      const exchange = await getFuturesExchange();
+
+      // Cancel existing TP order only — filter by reduceOnly to avoid cancelling unrelated orders
+      const orders  = await exchange.fetchOpenOrders(symbol);
+      const tpOrder = orders.find((o) =>
+        !!o.reduceOnly &&
+        ["limit", "LIMIT"].includes(o.type ?? "")
+      ) ?? null;
+      if (tpOrder) {
+        await exchange.cancelOrder(tpOrder.id, symbol);
+        await sleep(CANCEL_SETTLE_MS);
+      }
+
+      const qty      = truncateQty(exchange, symbol, await fetchContractsQty(exchange, symbol, position));
+      const exitSide = position === "long" ? "sell" : "buy";
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (qty === 0) {
+        throw new Error(`TrailingTake skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const tpPrice      = parseFloat(exchange.priceToPrecision(symbol, newTakeProfitPrice));
+      const positionSide = toPositionSide(position);
+
+      // positionSide required in hedge mode (-4061 without it); ignored in one-way mode
+      await exchange.createOrder(symbol, "limit", exitSide, qty, tpPrice, { reduceOnly: true, positionSide });
+    }
+
+    async onBreakevenCommit(payload: BrokerBreakevenPayload): Promise<void> {
+      const { symbol, newStopLossPrice, position } = payload;
+      const exchange = await getFuturesExchange();
+
+      // Cancel existing SL order only — filter by reduceOnly to avoid cancelling unrelated orders
+      const orders  = await exchange.fetchOpenOrders(symbol);
+      const slOrder = orders.find((o) =>
+        !!o.reduceOnly &&
+        ["stop_market", "stop", "STOP_MARKET"].includes(o.type ?? "")
+      ) ?? null;
+      if (slOrder) {
+        await exchange.cancelOrder(slOrder.id, symbol);
+        await sleep(CANCEL_SETTLE_MS);
+      }
+
+      const qty      = truncateQty(exchange, symbol, await fetchContractsQty(exchange, symbol, position));
+      const exitSide = position === "long" ? "sell" : "buy";
+
+      // Position may have already been closed by SL/TP on exchange — skip gracefully
+      if (qty === 0) {
+        throw new Error(`Breakeven skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, newStopLossPrice));
+      const positionSide = toPositionSide(position);
+
+      // positionSide required in hedge mode (-4061 without it); ignored in one-way mode
+      await exchange.createOrder(symbol, "stop_market", exitSide, qty, undefined, { stopPrice: slPrice, reduceOnly: true, positionSide });
+    }
+
+    async onAverageBuyCommit(payload: BrokerAverageBuyPayload): Promise<void> {
+      const { symbol, currentPrice, cost, position, priceTakeProfit, priceStopLoss } = payload;
+      const exchange = await getFuturesExchange();
+
+      // Cancel existing SL/TP first — existing check must happen after cancel+settle
+      // to avoid race condition where SL/TP fills between the existence check and cancel
+      const openOrders = await exchange.fetchOpenOrders(symbol);
+      await cancelAllOrders(exchange, openOrders, symbol);
+      await sleep(CANCEL_SETTLE_MS);
+
+      // Guard against DCA into a ghost position — checked after cancel so the snapshot is fresh
+      const existing    = await fetchContractsQty(exchange, symbol, position);
+      const minNotional = exchange.markets[symbol].limits?.cost?.min ?? 1;
+
+      // Compare notional value rather than raw contracts — avoids float === 0 trap
+      // and correctly rejects dust positions left over from previous trades
+      if (existing * currentPrice < minNotional) {
+        throw new Error(`AverageBuy skipped: no open position for ${symbol} on exchange — SL/TP may have already been filled`);
+      }
+
+      const qty = truncateQty(exchange, symbol, cost / currentPrice);
+
+      // Guard: truncation may produce 0 if cost/price is below lot size
+      if (qty <= 0) {
+        throw new Error(`Computed qty is zero for ${symbol} — cost=${cost}, price=${currentPrice}`);
+      }
+
+      const entryPrice   = parseFloat(exchange.priceToPrecision(symbol, currentPrice));
+      const tpPrice      = parseFloat(exchange.priceToPrecision(symbol, priceTakeProfit));
+      const slPrice      = parseFloat(exchange.priceToPrecision(symbol, priceStopLoss));
+      // positionSide required in hedge mode to add to correct side; ignored in one-way mode
+      const positionSide = toPositionSide(position);
+      const entrySide    = position === "long" ? "buy"  : "sell";
+      const exitSide     = position === "long" ? "sell" : "buy";
+
+      // DCA entry: restore SL/TP on existing qty if times out so position is not left unprotected
+      await createLimitOrderAndWait(
+        exchange, symbol, entrySide, qty, entryPrice,
+        { positionSide },
+        { exitSide, tpPrice, slPrice, positionSide: position }
+      );
+
+      // Refetch contracts after fill — existing snapshot is stale after cancel + fill
+      const totalQty = truncateQty(exchange, symbol, await fetchContractsQty(exchange, symbol, position));
+
+      // Recreate SL/TP on fresh total qty after successful fill
+      try {
+        await exchange.createOrder(symbol, "limit", exitSide, totalQty, tpPrice, { reduceOnly: true, positionSide });
+        await exchange.createOrder(symbol, "stop_market", exitSide, totalQty, undefined, { stopPrice: slPrice, reduceOnly: true, positionSide });
+      } catch (err) {
+        // Total position is unprotected — close via market
+        await exchange.createOrder(symbol, "market", exitSide, totalQty, undefined, { reduceOnly: true, positionSide });
+        throw err;
+      }
+    }
+  }
+);
+
+Broker.enable();
+```
+
+</details>
+
+Signal open/close events are routed automatically via an internal event bus once `Broker.enable()` is called. **No manual wiring needed.** All other operations (`partialProfit`, `trailingStop`, `breakeven`, `averageBuy`) are intercepted explicitly before the corresponding state mutation.
+
 ### 🔍 How getCandles Works
 
 backtest-kit uses Node.js `AsyncLocalStorage` to automatically provide