📚 Quant Backtester — API Reference

Path thay thế khi cần tốc độ (vectorized signal pre-compute). Chạy nhanh 5-10x so với onBar nhưng giới hạn về linh hoạt (không có position state trong loop). Đa số chiến lược dùng onBar là đủ — chỉ chọn evaluateBatch khi sweep nhiều params hoặc backtest dataset lớn.

Define function evaluateBatch(bars, ctx) { ... } thay onBar. Trả array Array(bars.length) — mỗi element là null (skip bar) hoặc object output dưới đây. Đọc indicator full-array qua ctx.array("name").

Output schema

Reverse-via-limit semantic

long_condition/short_condition = "đặt order theo hướng đó", KHÔNG phải "close position cũ ngay" (match sàn thật). Khi đang trong position ngược + signal flip:

Muốn force exit không đợi fill → dùng close_long/close_short.

3 pattern phổ biến

function evaluateBatch(bars, ctx) {
  const atr = ctx.array("atr");
  const hh20 = ctx.array("hh20");
  const ll20 = ctx.array("ll20");
  const outputs = new Array(bars.length).fill(null);

  for (let t = 20; t < bars.length; t++) {
    const a = atr[t];
    if (!(a > 0)) continue;
    const c = bars.close[t];
    const out = {};

    if (bars.high[t] >= hh20[t - 1]) {
      out.long_condition = true;
      out.entry_long = 0;                  // market — breakout đã xảy ra
      out.sl_long = ll20[t - 1] - 2 * a;
      out.cancel_short = true;
    }
    if (bars.low[t] <= ll20[t - 1]) {
      out.short_condition = true;
      out.entry_short = 0;
      out.sl_short = hh20[t - 1] + 2 * a;
      out.cancel_long = true;
    }
    if (Object.keys(out).length) outputs[t] = out;
  }
  return outputs;
}

// Vào limit BELOW current close khi long, đợi pullback xuống.
// Reverse signal → đặt limit ở opposite, KHÔNG đóng ngay.
if (bars.high[t] >= hh20[t - 1]) {
  out.long_condition = true;
  out.entry_long = c - a;                 // limit dưới close 1 ATR
  out.sl_long = ll20[t - 1] - 2 * a;
}
if (bars.low[t] <= ll20[t - 1]) {
  out.short_condition = true;
  out.entry_short = c + a;                // limit trên close 1 ATR
  out.sl_short = hh20[t - 1] + 2 * a;
}

// Trail SL chỉ khi structure đổi (Donchian low mới cao hơn). Skip default.
const dc_low = ctx.array("dc_l");
if (dc_low[t] > dc_low[t - 1]) {
  out.trailing_long = dc_low[t] - a;
  out.trailing_long_condition = true;     // bắt buộc bool=true mới apply
}
// Force exit khi price cross regime threshold
if (bars.close[t] < ctx.array("sma200")[t]) {
  out.close_long = true;
}

Fast mode limitations

Các API scalar-at-current-bar không work trong evaluateBatch (vì uses curIdx → return value tại last bar, không per-loop-t):

• ctx.ta.* ad-hoc per-bar → dùng ctx.declare + ctx.array("name")[t] thay
• ctx.htf() multi-TF → dùng ctx.htf_array(tf, funcName, params) trả LTF-mapped Float64Array
• ctx.regime(), ctx.size_vol_target(), ctx.set_triple_barrier() → no Fast equivalent (use onBar)
• ctx.position() inline state → no Fast equivalent. Workaround: track via heuristic close-vs-mean hoặc dùng output schema flow (engine guard).

Gotchas

• Conflict same bar: cả long_condition và short_condition cùng true → engine xử lý cả 2 (place 2 order). Strategy tự resolve trước nếu không muốn.
• Pending TTL: limit/stop hết hạn sau 5 bars (pendingTTL config). Re-emit signal mỗi bar để refresh hoặc cancel_X chủ động.
• Trailing strict: cần CẢ trailing_long (number) AND trailing_long_condition: true. Thiếu 1 trong 2 → skip.
• Trailing only-tighten: engine không auto-monotonic. Nếu strategy emit raw level mỗi bar (vd trailing_long = ll[t]), SL có thể loosen khi structure đi ngược. Track last_emitted state để guard.
• Dual-signal flip: emit cả long_condition và short_condition mỗi bar khi đang có position → opposite limit fill = reverse-via-netting. Mean-reversion strategies cần emit 1 hướng/bar (heuristic close-vs-mean).
• SL gate sizing: risk-based sizing cần sl_X. Không có SL → size=0. Dùng size_override nếu skip.
• Warmup: skip bars đầu (continue hoặc emit null) đến khi indicator dài nhất ready.