Class BrokerBase

Base class for custom broker adapter implementations.

Provides default no-op implementations for all IBroker methods that log events. Extend this class to implement a real exchange adapter for:

  • Placing and canceling limit/market orders
  • Updating stop-loss and take-profit levels on exchange
  • Tracking position state in an external system
  • Sending trade notifications (Telegram, Discord, Email)
  • Recording trades to a database or analytics service

Key features:

  • All methods have default implementations (no need to override unused methods)
  • Automatic logging of all events via bt.loggerService
  • Implements the full IBroker interface
  • makeExtendable applied for correct subclass instantiation

Lifecycle:

  1. Constructor called (no arguments)
  2. waitForInit() called once for async initialization (e.g. exchange login)
  3. Event methods called as strategy executes
  4. No explicit dispose — clean up in waitForInit teardown or externally

Event flow (called only in live mode, skipped in backtest):

  • onSignalOpenCommit — new position opened
  • onSignalCloseCommit — position closed (SL/TP hit or manual close)
  • onPartialProfitCommit — partial close at profit executed
  • onPartialLossCommit — partial close at loss executed
  • onTrailingStopCommit — trailing stop-loss updated
  • onTrailingTakeCommit — trailing take-profit updated
  • onBreakevenCommit — stop-loss moved to entry price
  • onAverageBuyCommit — new DCA entry added to position

Example

import { BrokerBase, Broker } from "backtest-kit";

// Extend BrokerBase and override only needed methods
class BinanceBroker extends BrokerBase {
  private client: BinanceClient | null = null;

  async waitForInit() {
    super.waitForInit(); // Call parent for logging
    this.client = new BinanceClient(process.env.API_KEY, process.env.SECRET);
    await this.client.connect();
  }

  async onSignalOpenCommit(payload: BrokerSignalOpenPayload) {
    super.onSignalOpenCommit(payload); // Call parent for logging
    await this.client!.placeOrder({
      symbol: payload.symbol,
      side: payload.position === "long" ? "BUY" : "SELL",
      quantity: payload.cost / payload.priceOpen,
    });
  }

  async onSignalCloseCommit(payload: BrokerSignalClosePayload) {
    super.onSignalCloseCommit(payload); // Call parent for logging
    await this.client!.closePosition(payload.symbol);
  }
}

// Register the adapter
Broker.useBrokerAdapter(BinanceBroker);
Broker.enable();

Example

// Minimal implementation — only handle opens and closes
class NotifyBroker extends BrokerBase {
  async onSignalOpenCommit(payload: BrokerSignalOpenPayload) {
    await sendTelegram(`Opened ${payload.position} on ${payload.symbol}`);
  }

  async onSignalCloseCommit(payload: BrokerSignalClosePayload) {
    const pnl = payload.pnl.profit - payload.pnl.loss;
    await sendTelegram(`Closed ${payload.symbol}: PnL $${pnl.toFixed(2)}`);
  }
}

Implements

Constructors

constructor

Methods

onAverageBuyCommit onBreakevenCommit onOrderCheck onPartialLossCommit onPartialProfitCommit onSignalActivePing onSignalCloseCommit onSignalIdlePing onSignalOpenCommit onSignalPendingClose onSignalPendingOpen onSignalScheduleCancelled onSignalScheduleOpen onSignalSchedulePing onTrailingStopCommit onTrailingTakeCommit waitForInit

Constructors

constructor

Methods

onAverageBuyCommit

  • onAverageBuyCommit(payload: BrokerAverageBuyPayload): Promise<void>

    Called when a new DCA entry is added to the active position.

    Triggered explicitly after all validations pass, before strategyCoreService.averageBuy(). currentPrice is the market price at which the new averaging entry is placed. cost is the dollar amount of the new DCA entry.

    Default implementation: Logs average buy event.

    Parameters

    Returns Promise<void>

    Example

    async onAverageBuyCommit(payload: BrokerAverageBuyPayload) {
      super.onAverageBuyCommit(payload); // Keep parent logging
      await this.exchange.placeMarketOrder({
        symbol: payload.symbol,
        side: "BUY",
        quantity: payload.cost / payload.currentPrice,
      });
    }

onBreakevenCommit

  • onBreakevenCommit(payload: BrokerBreakevenPayload): Promise<void>

    Called when the stop-loss is moved to breakeven (entry price).

    Triggered explicitly after all validations pass, before strategyCoreService.breakeven(). newStopLossPrice equals effectivePriceOpen — the position's effective entry price. newTakeProfitPrice is unchanged by breakeven.

    Default implementation: Logs breakeven event.

    Parameters

    • payload: BrokerBreakevenPayload

      Breakeven details: symbol, currentPrice, newStopLossPrice, newTakeProfitPrice, context, backtest

    Returns Promise<void>

    Example

    async onBreakevenCommit(payload: BrokerBreakevenPayload) {
      super.onBreakevenCommit(payload); // Keep parent logging
      await this.exchange.updateStopLoss({
        symbol: payload.symbol,
        price: payload.newStopLossPrice, // = entry price
      });
    }

onOrderCheck

  • onOrderCheck(payload: BrokerSignalPendingPayload): Promise<void>

    Called on every live tick while a pending signal is monitored, BEFORE TP/SL/time evaluation.

    Override to query the exchange for the order by payload.signalId and THROW ONLY when it is definitively NOT FOUND by that id (filled, cancelled, or liquidated externally) — the framework then closes the position with closeReason "closed". The default implementation logs and returns normally, which keeps the position under normal TP/SL monitoring.

    CRITICAL: swallow transient/network errors (timeout, 5xx, rate limit, disconnect) — return normally instead of throwing. A thrown network error would wrongly close an open position; only a confirmed "order not found by id" response is a valid reason to throw.

    Manual wiring — EXCEPTION-BASED VARIANT: the throw-driven alternative to the imperative commit-function wiring in onSignalActivePing. See IBroker.onOrderCheck for the full comparison and example.

    Parameters

    Returns Promise<void>

onPartialLossCommit

  • onPartialLossCommit(payload: BrokerPartialLossPayload): Promise<void>

    Called when a partial close at loss is executed.

    Triggered explicitly from strategy.ts / Live.ts / Backtest.ts after all validations pass, before strategyCoreService.partialLoss(). If this method throws, the DI mutation is skipped. Use to partially close the position on the exchange at the loss level.

    Default implementation: Logs partial loss event.

    Parameters

    • payload: BrokerPartialLossPayload

      Partial loss details: symbol, percentToClose, cost (dollar value), currentPrice, context, backtest

    Returns Promise<void>

    Example

    async onPartialLossCommit(payload: BrokerPartialLossPayload) {
      super.onPartialLossCommit(payload); // Keep parent logging
      await this.exchange.reducePosition({
        symbol: payload.symbol,
        dollarAmount: payload.cost,
        price: payload.currentPrice,
      });
    }

onPartialProfitCommit

  • onPartialProfitCommit(payload: BrokerPartialProfitPayload): Promise<void>

    Called when a partial close at profit is executed.

    Triggered explicitly from strategy.ts / Live.ts / Backtest.ts after all validations pass, before strategyCoreService.partialProfit(). If this method throws, the DI mutation is skipped. Use to partially close the position on the exchange at the profit level.

    Default implementation: Logs partial profit event.

    Parameters

    • payload: BrokerPartialProfitPayload

      Partial profit details: symbol, percentToClose, cost (dollar value), currentPrice, context, backtest

    Returns Promise<void>

    Example

    async onPartialProfitCommit(payload: BrokerPartialProfitPayload) {
      super.onPartialProfitCommit(payload); // Keep parent logging
      await this.exchange.reducePosition({
        symbol: payload.symbol,
        dollarAmount: payload.cost,
        price: payload.currentPrice,
      });
    }

onSignalActivePing

  • onSignalActivePing(payload: BrokerActivePingPayload): Promise<void>

    Called on every live tick while a pending (open) signal is monitored.

    Purely informational mirror of the active-ping lifecycle — unlike onOrderCheck, a throw here does NOT close the position. Override to mirror live monitoring state into your own systems. The default implementation logs.

    Manual wiring — EVENT-BASED: this is the primary per-tick hook to drive an open position from real exchange state (commitCreateTakeProfit / commitCreateStopLoss / commitClosePending). See the IBroker.onSignalActivePing contract docs for the full guidance and example.

    Parameters

    Returns Promise<void>

onSignalCloseCommit

  • onSignalCloseCommit(payload: BrokerSignalClosePayload): Promise<void>

    Called when a position is being closed (SL/TP hit or manual close).

    Triggered automatically via syncSubject when a pending signal is closed. Use to place the exit order and record final PnL.

    Default implementation: Logs signal-close event.

    Manual wiring — EXCEPTION-BASED GATE: emitted BEFORE the framework mutates state, so a THROW here (e.g. exit order failed) SKIPS the close — the position stays open and the close retries next tick; return normally to let it close. Live-only (backtest short-circuits). See IBroker.onSignalCloseCommit for the full semantics.

    Parameters

    • payload: BrokerSignalClosePayload

      Signal close details: symbol, cost, position, currentPrice, pnl, totalEntries, totalPartials, context, backtest

    Returns Promise<void>

    Example

    async onSignalCloseCommit(payload: BrokerSignalClosePayload) {
      super.onSignalCloseCommit(payload); // Keep parent logging
      const ok = await this.exchange.closePosition(payload.symbol);
      if (!ok) {
        throw new Error(`Exit not filled for ${payload.symbol}`); // -> keep position open, retry next tick
      }
      await this.db.recordTrade({ symbol: payload.symbol, pnl: payload.pnl });
    }

onSignalIdlePing

  • onSignalIdlePing(payload: BrokerIdlePingPayload): Promise<void>

    Called on every live tick while the strategy is idle (no pending or scheduled signal).

    Purely informational. Override to track idle heartbeats. The default logs.

    Parameters

    Returns Promise<void>

onSignalOpenCommit

  • onSignalOpenCommit(payload: BrokerSignalOpenPayload): Promise<void>

    Called when a position is being opened (signal activated).

    Triggered automatically via syncSubject when a scheduled signal's priceOpen is hit. Use to place the actual entry order on the exchange.

    Default implementation: Logs signal-open event.

    Manual wiring — EXCEPTION-BASED GATE: emitted BEFORE the framework mutates state, so a THROW here (e.g. limit order rejected) rolls back the open — the pending signal returns to idle and retries next tick; return normally to let it open. Live-only (backtest short-circuits). See IBroker.onSignalOpenCommit for the full semantics.

    Parameters

    • payload: BrokerSignalOpenPayload

      Signal open details: symbol, cost, position, priceOpen, priceTakeProfit, priceStopLoss, context, backtest

    Returns Promise<void>

    Example

    async onSignalOpenCommit(payload: BrokerSignalOpenPayload) {
      super.onSignalOpenCommit(payload); // Keep parent logging
      const order = await this.exchange.placeMarketOrder({
        symbol: payload.symbol,
        side: payload.position === "long" ? "BUY" : "SELL",
        quantity: payload.cost / payload.priceOpen,
      });
      if (!order.filled) {
        throw new Error(`Entry not filled for ${payload.symbol}`); // -> roll back the open, retry next tick
      }
    }

onSignalPendingClose

  • onSignalPendingClose(payload: BrokerPendingClosePayload): Promise<void>

    Called when a pending position is closed (take_profit / stop_loss / time_expired / closed).

    Informational lifecycle hook. Override to mirror the close into your own systems. The default logs.

    Manual wiring — EVENT-BASED (outbound): the strategy already removed the pending signal — flatten the real position and cancel leftover TP/SL orders by payload.signalId. See IBroker.onSignalPendingClose.

    Parameters

    Returns Promise<void>

onSignalPendingOpen

  • onSignalPendingOpen(payload: BrokerPendingOpenPayload): Promise<void>

    Called when a pending position is opened (new signal / immediate / scheduled or user activation).

    Informational lifecycle hook. Override to mirror the open into your own systems. The default logs.

    Manual wiring — EVENT-BASED: fires ONCE at open — place entry + protective TP/SL orders (tag with payload.signalId), then drive per-tick from onSignalActivePing. See IBroker.onSignalPendingOpen.

    Parameters

    Returns Promise<void>

onSignalScheduleCancelled

onSignalScheduleOpen

  • onSignalScheduleOpen(payload: BrokerScheduleOpenPayload): Promise<void>

    Called when a new scheduled signal is created and starts waiting for priceOpen activation.

    The scheduled -> active transition is reported via onSignalOpenCommit, not here. Override to place a resting/limit order on the exchange. The default logs.

    Manual wiring — EVENT-BASED: fires ONCE at creation — place the real resting order (tag it with payload.signalId) and optionally commitActivateScheduled / commitCancelScheduled. See IBroker.onSignalScheduleOpen for full guidance and example.

    Parameters

    Returns Promise<void>

onSignalSchedulePing

  • onSignalSchedulePing(payload: BrokerSchedulePingPayload): Promise<void>

    Called on every live tick while a scheduled signal is monitored (waiting for priceOpen).

    Purely informational. Override to mirror scheduled-monitoring state. The default logs.

    Manual wiring — EVENT-BASED: per-tick hook to drive a scheduled (resting) order from real exchange state (commitActivateScheduled / commitCancelScheduled). See IBroker.onSignalSchedulePing for full guidance and example.

    Parameters

    Returns Promise<void>

onTrailingStopCommit

  • onTrailingStopCommit(payload: BrokerTrailingStopPayload): Promise<void>

    Called when the trailing stop-loss level is updated.

    Triggered explicitly after all validations pass, before strategyCoreService.trailingStop(). newStopLossPrice is the absolute SL price — use it to update the exchange order directly.

    Default implementation: Logs trailing stop event.

    Parameters

    • payload: BrokerTrailingStopPayload

      Trailing stop details: symbol, percentShift, currentPrice, newStopLossPrice, context, backtest

    Returns Promise<void>

    Example

    async onTrailingStopCommit(payload: BrokerTrailingStopPayload) {
      super.onTrailingStopCommit(payload); // Keep parent logging
      await this.exchange.updateStopLoss({
        symbol: payload.symbol,
        price: payload.newStopLossPrice,
      });
    }

onTrailingTakeCommit

  • onTrailingTakeCommit(payload: BrokerTrailingTakePayload): Promise<void>

    Called when the trailing take-profit level is updated.

    Triggered explicitly after all validations pass, before strategyCoreService.trailingTake(). newTakeProfitPrice is the absolute TP price — use it to update the exchange order directly.

    Default implementation: Logs trailing take event.

    Parameters

    • payload: BrokerTrailingTakePayload

      Trailing take details: symbol, percentShift, currentPrice, newTakeProfitPrice, context, backtest

    Returns Promise<void>

    Example

    async onTrailingTakeCommit(payload: BrokerTrailingTakePayload) {
      super.onTrailingTakeCommit(payload); // Keep parent logging
      await this.exchange.updateTakeProfit({
        symbol: payload.symbol,
        price: payload.newTakeProfitPrice,
      });
    }

waitForInit

  • waitForInit(): Promise<void>

    Performs async initialization before the broker starts receiving events.

    Called once by BrokerProxy via waitForInit() (singleshot) before the first event. Override to establish exchange connections, authenticate API clients, load configuration.

    Default implementation: Logs initialization event.

    Returns Promise<void>

    Example

    async waitForInit() {
      super.waitForInit(); // Keep parent logging
      this.exchange = new ExchangeClient(process.env.API_KEY);
      await this.exchange.authenticate();
    }

Settings

Member Visibility

On This Page

Constructors
Methods