@backtest Kit MCP README

# Casual — your repo holds only strategy files; docs auto-fetched into docs/lib/
npx @backtest-kit/cli --init --output backtest-kit-project
cd backtest-kit-project && npm install && npm start

# Full control — exchange/frames/risk/runner all editable in your project
npx -y @backtest-kit/sidekick my-trading-bot && cd my-trading-bot && npm start

# Docker — zero-downtime live trading
npx @backtest-kit/cli --docker && cd backtest-kit-docker
MODE=live SYMBOL=TRXUSDT STRATEGY_FILE=./content/feb_2026/feb_2026.strategy.ts docker-compose up -d

A whole strategy is three registrations and a run call. No bootstrap, no DI container to learn:

import ccxt from 'ccxt';
import { addExchangeSchema, addStrategySchema, addFrameSchema, Position,
         Backtest, listenSignalBacktest, listenDoneBacktest } from 'backtest-kit';

addExchangeSchema({
  exchangeName: 'binance',
  getCandles: async (symbol, interval, since, limit) => {
    const ex = new ccxt.binance();
    const ohlcv = await ex.fetchOHLCV(symbol, interval, since.getTime(), limit);
    return ohlcv.map(([timestamp, open, high, low, close, volume]) =>
      ({ timestamp, open, high, low, close, volume }));
  },
  formatPrice: (s, p) => p.toFixed(2), formatQuantity: (s, q) => q.toFixed(8),
});

addFrameSchema({ frameName: 'feb-2026', interval: '1m',
  startDate: new Date('2026-02-01'), endDate: new Date('2026-02-28') });

addStrategySchema({
  strategyName: 'my-strategy', interval: '15m',
  getSignal: async (symbol, when, currentPrice) => ({
    position: 'long',
    ...Position.bracket({ position: 'long', currentPrice, percentTakeProfit: 2, percentStopLoss: 1 }),
    minuteEstimatedTime: 60 * 24, cost: 100,
  }),
});

Backtest.background('BTCUSDT', { strategyName: 'my-strategy', exchangeName: 'binance', frameName: 'feb-2026' });
listenSignalBacktest(console.log);
listenDoneBacktest(async (e) => { await Backtest.dump(e.symbol, e.strategyName); });

Every request resolves "now" from the ambient context, aligns down to the interval boundary, and treats the pending candle as exclusive:

when        = current execution-context time   (AsyncLocalStorage)
stepMs      = interval duration                (1m → 60000)
alignedWhen = Math.floor(when / stepMs) * stepMs          // round down to boundary
since       = alignedWhen − limit * stepMs               // go back `limit` candles

• since is inclusive — first candle has timestamp === since.
• alignedWhen is exclusive — the candle covering [alignedWhen, alignedWhen+stepMs) is still open and is never returned.
• Range is the half-open [since, alignedWhen); exactly limit candles return; timestamps are since + i·stepMs.

getNextCandles() is backtest-only and throws in live mode — there is no future to look at when "now" is wall-clock. getRawCandles(limit?, sDate?, eDate?) supports flexible windows, all clamped to eDate ≤ when. Order books and aggregated trades use the same alignment (trades always to a 1-minute boundary). All boundaries are UTC: a 4h candle aligns to 00/04/08/12/16/20 UTC regardless of your local offset — so since values that look "uneven" in local time are exact in UTC. Because since is derived from the ambient when, multi-timeframe pulls inside one getSignal are automatically synchronized, and runtime and the persistent cache compute identical keys — deterministic, exact-timestamp retrieval.

getSignal: async (symbol) => {
  // No timestamps anywhere. Context flows even through Promise.all —
  // all four timeframes are pinned to the same tick automatically.
  const [c1h, c15m, c5m, c1m] = await Promise.all([
    getCandles(symbol, '1h', 24),
    getCandles(symbol, '15m', 48),
    getCandles(symbol, '5m', 60),
    getCandles(symbol, '1m', 60),
  ]);
}

The bias you can't introduce by hand is the bias you'll never debug in production.

// Backtest — a historical frame drives the clock
Backtest.background('BTCUSDT', { strategyName, exchangeName, frameName });

// Live — wall-clock drives the clock; the strategy file is untouched
Live.background('BTCUSDT', { strategyName, exchangeName });   // keys via .env
listenSignalLive(async (e) => { if (e.action === 'closed') await Live.dump(e.symbol, e.strategyName); });

// Paper — live prices, no real orders, identical path. Validate here before risking capital.

And one engine, two ways to consume it — pick by use case, not by capability:

// Event-driven (production bots, monitoring)
Backtest.background('BTCUSDT', config);
listenSignalBacktest(e => {/* … */});

// Async iterator (research, scripts, LLM agents)
for await (const event of Backtest.run('BTCUSDT', config)) { /* signal | progress | done */ }

This is the property the test suite exists to defend, and the line in the sand for the whole project: business logic is 100% synchronous across backtest and live. Signal validation is identical in both modes; immediate activation behaves identically; scheduled-signal logic is fully synchronized; TP / SL / timeout checks do not differ. The only divergence is infrastructural — how candles, order books, and time are sourced. validation.test.mjs, backtest.test.mjs, and callbacks.test.mjs pin this behavior; event.test.mjs pins the live path against the same expectations. If the two ever drift, a test goes red before you do.

Recovery is structural, not a feature you remember to enable. PersistBase does atomic write-to-temp + rename, repairs corrupted files, and verifies integrity in waitForInit(). Fifteen per-domain Persist*Instance classes cover everything that can change: Signal, State, Session, Candle, Risk, Partial, Breakeven, Schedule, Recent, Notification, Log, Measure, Interval, Memory. Concrete scenarios that resolve cleanly:

• Process killed during order placement → internal state unchanged, retried next tick.
• Network failure during an exchange call → automatic retry on the next tick.
• Power loss during a save → recovery from the last atomic write.
• OOM → graceful shutdown with state preserved.

listenSignalLive(async (event) => {
  if (event.action === 'closed') {
    await Live.dump(event.symbol, event.strategyName);   // atomic snapshot to disk
    await Partial.dump(event.symbol, event.strategyName);
  }
  if (event.action === 'scheduled' || event.action === 'cancelled') {
    await Schedule.dump(event.symbol, event.strategyName);
  }
});

Each state exposes only the data that is meaningful in that state, so the wrong access never type-checks:

listenSignal((event) => {
  switch (event.action) {
    case 'idle':      /* no signal — only monitoring fields exist */            break;
    case 'scheduled': /* waiting for entry price — has priceOpen, scheduledAt */ break;
    case 'opened':    /* just filled — entry data, no closeReason yet */         break;
    case 'active':    /* live position — pnl, peakProfit, maxDrawdown */         break;
    case 'closed':    /* exited — closeReason, final pnl; live fields gone */     break;
  }
});

Before any signal reaches the engine it passes a validation pipeline: TP/SL prices positive, relationship correct (TP > entry > SL long, inverse short), risk/reward ≥ your minimum, timestamps not in the future, interval-throttling respected. Invalid signals are rejected or logged — never executed.

The discriminated-union result types (IStrategyTickResultWaiting / …Opened / …Closed / …Scheduled / …Cancelled) are enforced end-to-end: ClientStrategy.tick()/backtest(), StrategyCoreService, the persistence layer, and every notification contract (SignalOpenedNotification, SignalClosedNotification, SignalCancelledNotification, SignalScheduledNotification) carry the lifecycle state explicitly. validation.test.mjs exercises valid long/short, inverted TP/SL, negative prices, and future timestamps; backtest.test.mjs walks every close reason (take_profit, stop_loss, time_expired).

The reusable core: place → poll to fill → on timeout cancel, market-out any partial fill, restore TP/SL so the position is never left naked, then throw so the engine retries.

async function createLimitOrderAndWait(exchange, symbol, side, qty, price, restore?) {
  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);
    if ((await exchange.fetchOrder(order.id, symbol)).status === 'closed') return; // filled
  }

  await exchange.cancelOrder(order.id, symbol);
  await sleep(CANCEL_SETTLE_MS);                       // let the exchange settle before reading

  const filledQty = (await exchange.fetchOrder(order.id, symbol)).filled ?? 0;
  if (filledQty > 0) {                                 // roll the partial fill back to clean state
    await exchange.createOrder(symbol, 'market', side === 'buy' ? 'sell' : 'buy', filledQty);
  }
  if (restore) { /* re-place TP + stop-loss on the remaining position so it is never unprotected */ }

  throw new Error('not filled in time — partial fill rolled back, backtest-kit will retry');
}

A hook wires it to position open. Signal open/close are routed automatically by an internal event bus the moment Broker.enable() is called — no manual wiring. The other mutations are intercepted explicitly before their state change:

Broker.useBrokerAdapter(class implements IBroker {
  async waitForInit() { await getExchange(); }

  async onOrderOpenCommit({ symbol, cost, priceOpen, priceTakeProfit, priceStopLoss }) {
    const ex = await getExchange();
    const qty = truncateQty(ex, symbol, cost / priceOpen);
    await createLimitOrderAndWait(ex, symbol, 'buy', qty, priceOpen);   // entry
    try {                                                                // protect immediately
      await ex.createOrder(symbol, 'limit', 'sell', qty, priceTakeProfit);
      await createStopLossOrder(ex, symbol, qty, priceStopLoss);
    } catch (err) { await ex.createOrder(symbol, 'market', 'sell', qty); throw err; }
  }
  // onOrderCloseCommit · onPartialProfitCommit · onPartialLossCommit
  // onTrailingStopCommit · onTrailingTakeCommit · onBreakevenCommit · onAverageBuyCommit
});
Broker.enable();

Complete, production-grade Spot (stop_loss_limit, balance truncation, dust/notional guards) and Futures (reduceOnly, hedge-mode positionSide, setLeverage, ghost-position guards) adapters — every hook, every edge case — ship verbatim in the docs. The CLI can also dry-fire any single hook against your live adapter for verification before you wait hours for a real signal:

npx @backtest-kit/cli --brokerdebug --commit signal-open --symbol BTCUSDT

effectivePrice = Σcost / Σ(cost / price)          // cost-weighted harmonic mean

Each partial stores costBasisAtClose (the running dollar basis before it fired); a partial sell does not change the effective price of the coins still held. Final PnL is a dollar-weighted sum across every partial (each at its own effective price) plus the remainder, with slippage and per-leg fees:

weight[i]        = (percent[i]/100 × costBasisAtClose[i]) / totalInvested
totalWeightedPnl = Σ weight[i]·pnl[i] + remainingWeight·pnlRemaining
pnlPercentage    = totalWeightedPnl − fees       // open fee once + per-partial + final close
pnlCost          = pnlPercentage / 100 × totalInvested

Worked example — LONG @1000, 4 accepted DCA + 1 rejected, 3 partials, close @1200 — reconciles two independent ways to +17.9%:

0.075·(+15.00) + 0.135·(−7.98) + 0.316·(+12.91) + 0.474·(+29.04) ≈ +17.89%
coin cross-check:  (34.50 + 49.69 + 142.72 + 244.67 − 400) / 400 ≈ +17.90% ✓
entry #5 @980 REJECTED — 980 > effective entry ≈929.92  (the guard firing)

A complete DCA-ladder strategy — open once, average on overlap-free dips up to 10 rungs, close at target — is about thirty lines, and the dangerous math is all inside the engine:

import { addStrategySchema, listenActivePing, Position,
         commitAverageBuy, commitClosePending,
         getPositionEntries, getPositionEntryOverlap, getPositionPnlPercent } from 'backtest-kit';

addStrategySchema({
  strategyName: 'apr_2026_strategy',
  getSignal: async (symbol, when, currentPrice) => ({
    position: 'long',
    ...Position.moonbag({ position: 'long', currentPrice, percentStopLoss: 25 }),
    minuteEstimatedTime: Infinity, cost: 100,
  }),
});

listenActivePing(async ({ symbol, currentPrice }) => {                       // the ladder
  if ((await getPositionEntries(symbol)).length >= 10) return;
  if (await getPositionEntryOverlap(symbol, currentPrice, { upperPercent: 5, lowerPercent: 1 })) return;
  await commitAverageBuy(symbol, 100);                                        // rejected if it averages up
});

listenActivePing(async ({ symbol }) => {                                     // exit on blended target
  if (await getPositionPnlPercent(symbol) < 3) return;
  await commitClosePending(symbol, { id: 'unknown', note: '# closed by target pnl' });
});

Every order primitive is here, each with per-entry PnL, peak-profit and max-drawdown tracking: market/limit entries, TP/SL/OCO exits, grid with auto-cancel, partial profit/loss levels, trailing take/stop (absorbed only when they tighten in your favour, computed from the original distance to avoid drift), breakeven (moves the stop to entry once profit clears fees+slippage), stop-limit entries, DCA, and time-attack / infinite-hold.

addRiskSchema({
  riskName: 'demo',
  validations: [
    ({ pendingSignal, currentPrice }) => {                              // TP ≥ 1%
      const { priceOpen = currentPrice, priceTakeProfit, position } = pendingSignal;
      const tp = position === 'long'
        ? ((priceTakeProfit - priceOpen) / priceOpen) * 100
        : ((priceOpen - priceTakeProfit) / priceOpen) * 100;
      if (tp < 1) throw new Error(`TP too close: ${tp.toFixed(2)}%`);
    },
    ({ pendingSignal, currentPrice }) => {                              // R/R ≥ 2:1
      const { priceOpen = currentPrice, priceTakeProfit, priceStopLoss, position } = pendingSignal;
      const reward = position === 'long' ? priceTakeProfit - priceOpen : priceOpen - priceTakeProfit;
      const risk   = position === 'long' ? priceOpen - priceStopLoss : priceStopLoss - priceOpen;
      if (reward / risk < 2) throw new Error('Poor R/R ratio');
    },
  ],
});

listenRisk(async (event) => { await Risk.dump(event.symbol, event.strategyName); }); // every rejection, logged

ClientRisk tracks every open position across the portfolio; multiple strategies can share one profile for holistic exposure. checkSignalAndReserve is the thread-safe variant — after a successful reserve you must addSignal (finalize) or removeSignal (cancel) so reservations never go stale. A real LLM-gated portfolio improved from +52.22% → +68.90% PNL, Sharpe +0.309 → +0.512, win-rate 68% → 82% simply by letting a local model veto 6 signals — 4 of them losers.

Measured on a commodity laptop (HP Victus, i5-13420H, 16 GB DDR4, NVMe SSD), 9 symbols in parallel, one Node process:

Why it's fast: single-process concurrency (no IPC, no fork), an in-memory activity registry (Lookup) tracking every in-flight workload, a cooperative event-loop hand-off (Candle.spinLock) so parallel symbols advance round-robin instead of one hogging the CPU, Redis O(1) candle lookups, atomic findOneAndUpdate upserts (no read-modify-write), and --cache pre-warming so the inner loop never blocks on HTTP.

In live mode the bottleneck moves from CPU to the exchange — and that is where the shared cache earns its keep. Every symbol pulls candles, order books, and trades through one deduplicated layer, so nine strategies asking for the same BTCUSDT 1m candle issue one request, not nine. Hand-written per-bot code with no cache hammers the REST endpoint until the exchange rate-limits it; here the dedup + Redis O(1) layer keeps request volume flat as you add symbols, so rate limits stay off your back instead of throttling the desk. The ×700 / ×6,300 figures are CPU-bound backtest replay; live throughput is paced by the exchange, but the request layer is built so that pacing is the exchange's published limit, not self-inflicted spam.

import { Backtest, warmCandles } from 'backtest-kit';

for (const symbol of ['BTCUSDT','ETHUSDT','SOLUSDT','BNBUSDT','XRPUSDT']) {
  await warmCandles({ exchangeName: 'binance', interval: '1m', symbol,
    from: new Date('2026-02-01T00:00:00Z'), to: new Date('2026-02-28T23:59:59Z') });
  Backtest.background(symbol, { strategyName, exchangeName: 'binance', frameName: 'feb-2026' });
}

npx @backtest-kit/cli --backtest --entry ./content/multi-symbol.ts   # CLI defers symbol selection to your file

// config/setup.config.ts — loaded once before any persistence call
import { setup } from '@backtest-kit/mongo';
setup();   // reads CC_MONGO_CONNECTION_STRING / CC_REDIS_* from env, or pass explicitly

Fifteen adapters, each with a unique compound index (Signal → symbol+strategyName+exchangeName, Candle → symbol+interval+timestamp, Memory → signalId+bucketName+memoryId, …). Candle records are immutable ($setOnInsert, first write wins); Measure/Interval/Memory use soft delete (removed flag) for an audit trail. Reads go Redis-first for the Mongo _id, then findById — two O(1) ops; a miss falls back to an indexed findOne and backfills. Writes are one findOneAndUpdate({ upsert:true, new:true }) round-trip, so the unique index rejects concurrent duplicates at the storage engine and a write-then-read always sees fresh data. Signal-affecting adapters store the simulation when, so look-ahead protection is enforceable even inside the database.

read signal (BTCUSDT, my_strategy, binance)
  ├─ Redis GET → hit  → Mongo findById(_id)            ← O(1) + O(1)
  └─ Redis GET → miss → Mongo findOne(filter) → Redis SET → return

The default file adapter is already crash-safe (atomic temp+rename, repair on restart) — you get durability before you ever add a database.

• Pooled Sharpe (v10.2.0+): per-trade returns are pooled across all symbols into one sample, then Sharpe is computed on that distribution — replacing the trade-count-weighted average of ratios, which inflates when one symbol is great and another negative. The header reads Pooled Sharpe, not Portfolio Sharpe, with a Markowitz disclaimer so it's never mistaken for covariance-based optimization.
• Bessel's correction (N−1) for unbiased variance — no risk underestimation on small samples.
• Compounded equity curve for Max Drawdown / Calmar / Recovery Factor — no double-counting of percentage returns.
• Geometric annualization for expected yearly returns — accounts for volatility drag (a 50% loss needs a 100% gain to recover).
• Canonical Sortino (1991) with downside deviation over N_total.
• Float-artifact guard: identical-return series produce stddev ≈1e-17; an STDDEV_EPSILON guard returns N/A instead of a fake Sharpe of 10,000,000. Gates of ≥10 signals and ≥14 calendar days gate publication.

Dashboard revenue is dollar-true: pnlCost = pnlPercentage/100 × pnlEntries, summed across closed signals per window (Today / Yesterday / 7d / 31d), anchored to the run end in backtest and Date.now() live.

import { Cron, Backtest } from 'backtest-kit';

Cron.register({ name: 'tg-parser', interval: '1h',                                 // global, hourly
  handler: async ({ when }) => { await parseTelegramSignals(when); } });

Cron.register({ name: 'funding', interval: '1h', symbols: ['BTCUSDT','ETHUSDT'],   // per-symbol fan-out
  handler: async ({ symbol, when }) => { await fetchFundingRate(symbol, when); } });

Cron.register({ name: 'warm-cache',                                                // fire-once, global
  handler: async () => { await warmupCache(); } });

Cron.enable();   // wire to engine lifecycle once; every tick is forwarded automatically

enable() merges four lifecycle subjects (beforeStart, idlePing, activePing, schedulePing) into one serial queue via singlerun; each tick is base-aligned to the minute. Coordination keys ${name}:${alignedMs}:${symbol?}:g${generation} give mutex semantics — parallel backtests on the same boundary share one in-flight promise (first opens the slot, others await). Fire-once marks record only on success, so a failed handler retries; the generation suffix isolates re-registrations from late writes.

Pine Script — v5/v6, 60+ indicators, 1:1 syntax, look-ahead-safe (@backtest-kit/pinets):

import { File, getSignal } from '@backtest-kit/pinets';
const signal = await getSignal(File.fromPath('strategy.pine'),
  { symbol: 'BTCUSDT', timeframe: '5m', limit: 100 });   // plots: Signal/Close/StopLoss/TakeProfit/EstimatedTime

50+ indicators across 1m/15m/30m/1h + order book, as LLM-ready Markdown, in one call (@backtest-kit/signals):

import { commitHistorySetup } from '@backtest-kit/signals';
await commitHistorySetup('BTCUSDT', messages);   // order book + candles + indicators, cached per TTL

Typed DAG of computations, resolved in topological order with Promise.all parallelism, serializable to a DB (@backtest-kit/graph):

import { sourceNode, outputNode, resolve } from '@backtest-kit/graph';
const higher = sourceNode(async (symbol) => extract(await run(File.fromPath('timeframe_4h.pine'), { symbol, timeframe: '4h', limit: 100 }), { allowLong: 'AllowLong', allowShort: 'AllowShort', noTrades: 'NoTrades' }));
const lower  = sourceNode(async (symbol) => extract(await run(File.fromPath('timeframe_15m.pine'), { symbol, timeframe: '15m', limit: 100 }), { position: 'Signal', priceOpen: 'Close', priceTakeProfit: 'TakeProfit', priceStopLoss: 'StopLoss' }));
const mtf = outputNode(([h, l]) => {                          // combine; null when timeframes disagree
  if (h.noTrades || l.position === 0) return null;
  if (h.allowShort && l.position === 1) return null;
  if (h.allowLong  && l.position === -1) return null;
  return toSignalDto(randomString(), l, null);
}, higher, lower);
addStrategySchema({ strategyName: 'mtf', interval: '5m', getSignal: () => resolve(mtf) });

Python via WASM (WASI) runs ta-lib/pandas/scikit-learn indicators in the Node event loop with no IPC. And zero-dependency TS ports of the math behind vectorbt — see See also.

import { deepseek } from '@backtest-kit/ollama';
addStrategy({
  strategyName: 'llm-signal', interval: '5m',
  // swap deepseek() → claude() / gpt5() / ollama() with no other change
  getSignal: deepseek(getSignal, 'deepseek-chat', process.env.DEEPSEEK_API_KEY),
});

Providers: OpenAI, Claude, DeepSeek, Grok, Mistral, Perplexity, Cohere, Alibaba, Hugging Face, Ollama (local), GLM-4. Structured output is enforced with Zod / JSON schema via addOutline (auto-retry on malformed output, custom rules like "SL must be below entry for LONG"); token rotation accepts a key array; prompts live in config/prompt/*.cjs and are memoized to kill redundant backtest API calls. The full LLM strategy — fetch multi-timeframe candles, ask the model, dump the reasoning, return a validated signal:

import { v4 as uuid } from 'uuid';
import { addStrategySchema, getCandles, dumpAgentAnswer, dumpRecord } from 'backtest-kit';
import { json } from './utils/json.mjs';
import { getMessages } from './utils/messages.mjs';

addStrategySchema({
  strategyName: 'llm-strategy', interval: '5m', riskName: 'demo',
  getSignal: async (symbol) => {
    const messages = await getMessages(symbol, {
      candles1h:  await getCandles(symbol, '1h', 24),
      candles15m: await getCandles(symbol, '15m', 48),
      candles5m:  await getCandles(symbol, '5m', 60),
      candles1m:  await getCandles(symbol, '1m', 60),
    });
    const resultId = uuid();
    const signal = await json(messages);                              // LLM → structured signal
    await dumpAgentAnswer({ dumpId: 'position-context', bucketName: 'mtf', messages, description: 'agent reasoning' });
    await dumpRecord({ dumpId: 'position-entry', bucketName: 'mtf', record: signal, description: 'signal params' });
    return { ...signal, id: resultId };
  },
});

Memory adapters persist LLM reasoning per signal (BM25 search, soft delete); dumpAgentAnswer archives the full conversation — roles, reasoning, tool calls — attached to the signal, so an opaque model decision becomes a debuggable record.

getSignal declares what to open; the listeners declare how the position behaves once alive — a DCA ladder, a profit target, and an error sink, three independent reactions to the same event stream, no shared loop, no manual bookkeeping:

import {
  addStrategySchema, listenActivePing, listenError, Log, Position,
  commitAverageBuy, commitClosePending,
  getPositionEntries, getPositionEntryOverlap, getPositionPnlPercent,
} from "backtest-kit";
import { errorData, getErrorMessage, str } from "functools-kit";

const HARD_STOP = 25, TARGET_PROFIT = 3, STEP = 100, MAX_STEPS = 10;

// render: given "now", declare the position to open (or null to stay flat)
addStrategySchema({
  strategyName: "apr_2026_strategy",
  getSignal: async (symbol, when, currentPrice) => ({
    position: "long",
    ...Position.moonbag({ position: "long", currentPrice, percentStopLoss: HARD_STOP }),
    minuteEstimatedTime: Infinity, cost: STEP,
  }),
});

// effect: average into dips, up to 10 overlap-free rungs (averaging up is rejected for you)
listenActivePing(async ({ symbol, currentPrice }) => {
  if ((await getPositionEntries(symbol)).length >= MAX_STEPS) return;
  if (await getPositionEntryOverlap(symbol, currentPrice, { upperPercent: 5, lowerPercent: 1 })) return;
  await commitAverageBuy(symbol, STEP);
});

// effect: close the whole position once blended PnL clears the target
listenActivePing(async ({ symbol, data }) => {
  if (await getPositionPnlPercent(symbol) < TARGET_PROFIT) return;
  Log.info("position closed due to the target pnl reached", { symbol, data });
  await commitClosePending(symbol, { id: "unknown", note: str.newline("# Closed by target pnl") });
});

// effect: a single place for anything that goes wrong
listenError((error) => Log.debug("error", { error: errorData(error), message: getErrorMessage(error) }));

The full reactive surface — subscribe to any point in a position's life and the engine fires it in order, queued, never overlapping: listenSignal / listenSignalBacktest / listenSignalLive (lifecycle), listenActivePing (per-minute while a position is live), listenSchedulePing / listenIdlePing, listenPartialProfit / listenPartialLoss, listenBreakevenAvailable, listenHighestProfit, listenMaxDrawdown, listenRisk (rejections), listenError / listenExit, listenDone*, plus *Once filtered variants for one-shot reactions. You compose behavior by adding handlers, not by editing a loop.

The five guarantees that make the surface fool-proof, each enforced by the engine rather than by convention:

1. Ambient temporal context — no currentDate/timestamp parameter exists to forget; the engine resolves "now" from AsyncLocalStorage and blocks future data at the adapter level.
2. Type-safe state machine — idle → scheduled → pending → opened → active → closed as discriminated unions; calling a close on an already-closed signal, or editing an active trade's entry, is a compile error.
3. Guarded DCA — commitAverageBuy rejects any call that would worsen the harmonic-mean effective entry; you cannot accidentally average up.
4. Transactional broker commits (the "no-try-catch" rule) — the adapter intercepts every mutation before internal state changes; an exchange throw rolls back and retries on the next tick, so you never hand-write rollback.
5. Automatic signal validation — TP/SL soundness, R/R minimum, and interval throttling are checked before a signal reaches execution; invalid signals are logged or rejected, never run.

Because the loop belongs to the engine, the same declarations run identically in backtest and live — the reactive model is the reason "same code, both modes" is structurally true, not just aspirational.

• Liquidity Harvesting (Sharpe 1.14) — a Telegram channel published SHORT signals with ~0.375:1 R/R and 106% deposit at risk at 25× leverage, mathematically guaranteed to lose; a volume spike appeared 15 min before every post and the TP step multipliers were identical across signals — an algorithm. Inverting it turned −5.05% → +8.58%, profit factor 0.56 → 7.31. The edge was the bot crowd, not the indicators.
• Crowd Liquidity — 462 TradingView ideas, 167 authors, and a falling knife of a month (BTC −20.4%). Following the raw crowd lost −24.23%; the framework's Simulator entity grid-searched the author ban rule itself (minimum track × minimum hit rate among 3,456 points) and kept 5 authors of 167. Trading any post of those five: 10 trades, 90% WR, +19.80% — the whitelist artifact is generated by scripts/simulator.mjs, not curated by hand. Stated caveat: trained and traded on the same month; the July out-of-sample is the open question.
• AI News Sentiment held SHORT through nearly all of a −16.4% month, flipped to LONG on the recovery bounce, and flipped back on geopolitical news — +16.99% where buy-and-hold lost 16%.
• DCA Ladders show the trade-off honestly: high % return on deployed capital, but absolute fiat risk grows with rungs (Mar: −$104.93 on a 10-rung position; theoretical max −$2,500 if a non-reverting trend hits the 25% hard stop with all rungs filled). The README states the downside, not just the upside.

Every example documents price context, trade log, equity curve, and risk analysis — and several ship a --noDCA / single-entry variant so you can see exactly what the position management bought you.

• 🇬🇧 English — ~1.5B speakers. Backtest Kit is a TypeScript engine where the strategy you test on history is byte-for-byte the one that trades live — only the clock changes. It removes the failure modes that kill bots (look-ahead bias, crash corruption, silent order rejects, averaging up) at the API level, then adds first-class DCA, partial closes, portfolio risk, and AI/Pine signals on top.

• 🇨🇳 中文 — ~1.1B speakers. Backtest Kit 是一个 TypeScript 引擎：在历史数据上回测的策略代码，与实盘运行的代码逐字节一致，唯一区别只是时钟来源。它在 API 层面消除了让交易机器人崩溃的隐患（未来函数、崩溃损坏、静默拒单、越买越亏），并内置分批建仓、部分平仓、组合风控以及 AI/Pine 信号。

• 🇮🇳 हिन्दी — ~600M speakers. Backtest Kit एक TypeScript इंजन है जिसमें इतिहास पर परखा गया कोड ही बिना बदलाव के लाइव ट्रेड करता है — केवल घड़ी बदलती है। यह बॉट को बर्बाद करने वाली गलतियाँ (लुक-अहेड बायस, क्रैश करप्शन, चुपचाप ऑर्डर रिजेक्ट, ऊपर औसत करना) API स्तर पर ही रोकता है, और ऊपर से DCA, आंशिक क्लोज़, पोर्टफोलियो जोखिम व AI/Pine सिग्नल देता है।

• 🇪🇸 Español — ~560M speakers. Backtest Kit es un motor TypeScript donde la estrategia que pruebas con datos históricos es, byte a byte, la que opera en vivo — solo cambia el reloj. Elimina en la propia API los fallos que arruinan bots (sesgo look-ahead, corrupción por caídas, rechazos silenciosos de órdenes, promediar al alza) y suma DCA, cierres parciales, riesgo de cartera y señales de IA/Pine.

• 🇧🇷 Português — ~260M speakers. Backtest Kit é um motor TypeScript em que a estratégia testada no histórico é, byte a byte, a mesma que opera ao vivo — só o relógio muda. Ele elimina no próprio API os erros que matam bots (viés look-ahead, corrupção por falha, rejeição silenciosa de ordens, preço médio para cima) e ainda oferece DCA, fechamentos parciais, risco de carteira e sinais de IA/Pine.

• 🇷🇺 Русский — ~255M speakers. Backtest Kit — TypeScript-движок, где стратегия, проверенная на истории, побайтово совпадает с той, что торгует вживую: меняются только часы. Он устраняет на уровне API ошибки, губящие ботов (заглядывание в будущее, порча состояния при сбое, тихий отказ ордера, усреднение вверх), и добавляет полноценный DCA, частичные закрытия, портфельный риск и сигналы от AI/Pine.

• 🇹🇷 Türkçe — ~90M speakers. Backtest Kit, geçmiş veride test ettiğiniz stratejinin canlıda bayt bayt aynısını çalıştıran bir TypeScript motorudur — yalnızca saat değişir. Botları çökerten hataları (look-ahead yanlılığı, çökme bozulması, sessiz emir reddi, yukarı ortalama) API düzeyinde ortadan kaldırır; üstüne DCA, kısmi kapanışlar, portföy riski ve AI/Pine sinyalleri ekler.

Tag exchange orders with clientOrderId = signalId, and at attempt > 0 query the prior order by that id before re-sending — if it filled, confirm the open instead of buying again (don't rely on catching "duplicate": Binance's guard only covers open orders, an instantly-filled one won't dup). The counter is pre-armed into persistence before each attempt, so attempt > 0 holds even across a crash mid-attempt (see CC_ORDER_OPEN_RETRY_ATTEMPTS); rejected closes retry up to CC_ORDER_CLOSE_RETRY_ATTEMPTS and then force-close the engine state with the original reason; failed checks are tolerated for CC_ORDER_CHECK_RETRY_ATTEMPTS consecutive ticks instead of killing a live position on the first blip. When the network truly won't let the engine work, it exits loudly (listenExit) rather than churning forever. Your adapter states intent by throwing one of three typed errors — anything untyped is treated as transient.

• 🌩️ OrderTransientError — "temporary failure, retry me" (timeout, 5xx, rate limit, lost response). Pure declarative sugar: any plain Error behaves identically, the framework never pattern-matches this class. Opens retry identity-stably with the same signalId, closes retry next tick, checks keep the order alive — each bounded by its CC_ORDER_*_RETRY_ATTEMPTS config (default 5, 0 = legacy behavior). Exhausting the budget is the one path that signals a fatal exit. OrderTransientError.fromError(e) wraps a caught error while keeping its message.

• ⛔ OrderRejectedError — terminal business refusal, for the gates (onOrderOpenCommit / onOrderCloseCommit): "the exchange definitively said no — retrying is pointless" (min-notional, delisted symbol, no counterparty). An open is dropped at once without arming the retry; a close force-closes the engine state immediately with the original reason — the close lifecycle event still reaches the adapter so the real position can be reconciled. No fatal exit: a business outcome keeps the process alive. Thrown from a check instead, it is a protocol violation and intentionally degrades to transient.

• 🗑️ OrderDeletedError — confirmed order-not-found, for the checks (onOrderActiveCheck / onOrderScheduleCheck): "the exchange reports no order under this id" (cancelled manually, liquidated externally). Acts terminally at once, bypassing the tolerance counter: an open position closes with reason , a resting order cancels with reason . A order is not a deleted order — confirm fills via / / so the close carries its true reason. Thrown from a gate instead, it degrades to transient.

• ✅ State machine under rejections (gates, throttle rollbacks, terminal drops, stopStrategy race)
• ✅ Deferred commands, Live × Backtest
• ✅ Broker: 8-stage lifecycle routing, gates, backtest silence, enable/disable, commit* layer
• ✅ Position commands + interleaved DCA × partial exits
• ✅ Context-free surface (62 bare calls)
• ✅ Crash recovery of every deferred flag + commit queue
• ✅ SHORT mirror of the key paths
• ✅ Timeouts, Once-listeners, action gate, Infinity holds, whipsaw restore, shared-risk contention, cancellation stats
• ✅ Order events: types, emission/silence per mode
• ✅ Look-ahead bias protection: candle alignment, pending-candle exclusion, getNextCandles throwing in live
• ✅ Signal validation: inverted TP/SL, negative/NaN/Infinity prices, future timestamps, micro-profit eaten by fees, excessive lifetime
• ✅ Full lifecycle and every close reason: take_profit, stop_loss, time_expired, user close, external "closed"
• ✅ Scheduled signals: price/wick activation, pre-activation SL cancellation, timeout, frame-end, immediate activation
• ✅ Money-safety edges: SL-before-activation, TP-vs-SL priority on a single candle, extreme volatility, exchange errors surfaced not swallowed
• ✅ Signal queues: sequences of mixed outcomes, winning/losing streaks, deterministic-id retry vs whipsaw block
• ✅ Infinity holds: chunked candle processing across frame boundaries, close-at-boundary edge cases
• ✅ PnL math: 0.1% fees + 0.1% slippage, cost-basis snapshots, partial-close weighting, DCA harmonic effective price
• ✅ Partial profit/loss: dollar-exact closes on the remaining cost basis, 100%-of-remaining epsilon cap
• ✅ Trailing stop/take: percentage-point shifts from ORIGINAL levels, absorption, intrusion protection
• ✅ Breakeven: threshold math over fees+slippage, trailing upgrade paths, zero-risk exits landing exactly on entry
• ✅ Risk schemas: reservation/release accounting, rejection callbacks, shared risk maps across strategies
• ✅ Position sizing: fixed/percent/Kelly calculators, min/max caps ordering
• ✅ Persistence: atomic writes, JSON adapters, restore after restart (pending, scheduled, deferred flags, commit queue), context-mismatch skips, Infinity round-trip
• ✅ Candle cache: hit/miss keys, interval separation, adapter call counting
• ✅ Event-listener system: every listen*/listen*Once channel, queued async processing, unsubscribe
• ✅ Actions: schema validation (discouraged-method redirects), handler/callback routing, risk rejection hooks
• ✅ Reports and markdown: column renderers, null-vs-zero semantics, closed-history merging, schedule activation/cancellation rates