backtest-kit 1.11.8 → 1.11.9

package/build/index.cjs

@@ -422,6 +422,13 @@ const GLOBAL_CONFIG = {
      * Default: 10 minutes
      */
     CC_ORDER_BOOK_TIME_OFFSET_MINUTES: 10,
+    /**
+     * Maximum depth levels for order book fetching.
+     * Specifies how many price levels to fetch from both bids and asks.
+     *
+     * Default: 20 levels
+     */
+    CC_ORDER_BOOK_MAX_DEPTH_LEVELS: 1000,
 };
 const DEFAULT_CONFIG = Object.freeze({ ...GLOBAL_CONFIG });
 
@@ -891,17 +898,23 @@ class ClientExchange {
     /**
      * Fetches order book for a trading pair.
      *
+     * Calculates time range based on execution context time (when) and
+     * CC_ORDER_BOOK_TIME_OFFSET_MINUTES, then delegates to the exchange
+     * schema implementation which may use or ignore the time range.
+     *
      * @param symbol - Trading pair symbol
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
      * @returns Promise resolving to order book data
      * @throws Error if getOrderBook is not implemented
      */
-    async getOrderBook(symbol) {
+    async getOrderBook(symbol, depth = GLOBAL_CONFIG.CC_ORDER_BOOK_MAX_DEPTH_LEVELS) {
         this.params.logger.debug("ClientExchange getOrderBook", {
             symbol,
+            depth,
         });
         const to = new Date(this.params.execution.context.when.getTime());
         const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * 60 * 1000);
-        return await this.params.getOrderBook(symbol, from, to);
+        return await this.params.getOrderBook(symbol, depth, from, to);
     }
 }
 
@@ -929,8 +942,13 @@ const DEFAULT_FORMAT_PRICE_FN$1 = async (_symbol, price) => {
 /**
  * Default implementation for getOrderBook.
  * Throws an error indicating the method is not implemented.
+ *
+ * @param _symbol - Trading pair symbol (unused)
+ * @param _depth - Maximum depth levels (unused)
+ * @param _from - Start of time range (unused - can be ignored in live implementations)
+ * @param _to - End of time range (unused - can be ignored in live implementations)
  */
-const DEFAULT_GET_ORDER_BOOK_FN$1 = async (_symbol, _from, _to) => {
+const DEFAULT_GET_ORDER_BOOK_FN$1 = async (_symbol, _depth, _from, _to) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
 /**
@@ -1071,15 +1089,19 @@ class ExchangeConnectionService {
          * Fetches order book for a trading pair using configured exchange.
          *
          * Routes to exchange determined by methodContextService.context.exchangeName.
+         * The ClientExchange will calculate time range and pass it to the schema
+         * implementation, which may use (backtest) or ignore (live) the parameters.
          *
          * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          */
-        this.getOrderBook = async (symbol) => {
+        this.getOrderBook = async (symbol, depth) => {
             this.loggerService.log("exchangeConnectionService getOrderBook", {
                 symbol,
+                depth,
             });
-            return await this.getExchange(this.methodContextService.context.exchangeName).getOrderBook(symbol);
+            return await this.getExchange(this.methodContextService.context.exchangeName).getOrderBook(symbol, depth);
         };
     }
 }
@@ -7466,23 +7488,29 @@ class ExchangeCoreService {
         /**
          * Fetches order book with execution context.
          *
+         * Sets up execution context with the provided when/backtest parameters.
+         * The exchange implementation will receive time range parameters but may
+         * choose to use them (backtest) or ignore them (live).
+         *
          * @param symbol - Trading pair symbol
          * @param when - Timestamp for context
          * @param backtest - Whether running in backtest mode
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          */
-        this.getOrderBook = async (symbol, when, backtest) => {
+        this.getOrderBook = async (symbol, when, backtest, depth) => {
             this.loggerService.log("exchangeCoreService getOrderBook", {
                 symbol,
                 when,
                 backtest,
+                depth,
             });
             if (!MethodContextService.hasContext()) {
                 throw new Error("exchangeCoreService getOrderBook requires a method context");
             }
             await this.validate(this.methodContextService.context.exchangeName);
             return await ExecutionContextService.runInContext(async () => {
-                return await this.exchangeConnectionService.getOrderBook(symbol);
+                return await this.exchangeConnectionService.getOrderBook(symbol, depth);
             }, {
                 symbol,
                 when,
@@ -21351,6 +21379,7 @@ const FORMAT_QUANTITY_METHOD_NAME = "exchange.formatQuantity";
 const GET_DATE_METHOD_NAME = "exchange.getDate";
 const GET_MODE_METHOD_NAME = "exchange.getMode";
 const HAS_TRADE_CONTEXT_METHOD_NAME = "exchange.hasTradeContext";
+const GET_ORDER_BOOK_METHOD_NAME = "exchange.getOrderBook";
 /**
  * Checks if trade context is active (execution and method contexts).
  *
@@ -21531,6 +21560,41 @@ async function getMode() {
     const { backtest: bt$1 } = bt.executionContextService.context;
     return bt$1 ? "backtest" : "live";
 }
+/**
+ * Fetches order book for a trading pair from the registered exchange.
+ *
+ * Uses current execution context to determine timing. The underlying exchange
+ * implementation receives time range parameters but may use them (backtest)
+ * or ignore them (live trading).
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
+ * @returns Promise resolving to order book data
+ * @throws Error if execution or method context is missing
+ *
+ * @example
+ * ```typescript
+ * const orderBook = await getOrderBook("BTCUSDT");
+ * console.log(orderBook.bids); // [{ price: "50000.00", quantity: "0.5" }, ...]
+ * console.log(orderBook.asks); // [{ price: "50001.00", quantity: "0.3" }, ...]
+ *
+ * // Fetch deeper order book
+ * const deepBook = await getOrderBook("BTCUSDT", 100);
+ * ```
+ */
+async function getOrderBook(symbol, depth) {
+    bt.loggerService.info(GET_ORDER_BOOK_METHOD_NAME, {
+        symbol,
+        depth,
+    });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getOrderBook requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getOrderBook requires a method context");
+    }
+    return await bt.exchangeConnectionService.getOrderBook(symbol, depth);
+}
 
 const STOP_METHOD_NAME = "strategy.stop";
 const CANCEL_METHOD_NAME = "strategy.cancel";
@@ -27131,8 +27195,13 @@ const DEFAULT_FORMAT_PRICE_FN = async (_symbol, price) => {
 /**
  * Default implementation for getOrderBook.
  * Throws an error indicating the method is not implemented.
+ *
+ * @param _symbol - Trading pair symbol (unused)
+ * @param _depth - Maximum depth levels (unused)
+ * @param _from - Start of time range (unused - can be ignored in live implementations)
+ * @param _to - End of time range (unused - can be ignored in live implementations)
  */
-const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _from, _to) => {
+const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _depth, _from, _to) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
 const INTERVAL_MINUTES$1 = {
@@ -27343,7 +27412,12 @@ class ExchangeInstance {
         /**
          * Fetch order book for a trading pair.
          *
+         * Calculates time range using CC_ORDER_BOOK_TIME_OFFSET_MINUTES (default 10 minutes)
+         * and passes it to the exchange schema implementation. The implementation may use
+         * the time range (backtest) or ignore it (live trading).
+         *
          * @param symbol - Trading pair symbol
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          * @throws Error if getOrderBook is not implemented
          *
@@ -27352,16 +27426,18 @@ class ExchangeInstance {
          * const instance = new ExchangeInstance("binance");
          * const orderBook = await instance.getOrderBook("BTCUSDT");
          * console.log(orderBook.bids); // [{ price: "50000.00", quantity: "0.5" }, ...]
+         * const deepOrderBook = await instance.getOrderBook("BTCUSDT", 100);
          * ```
          */
-        this.getOrderBook = async (symbol) => {
+        this.getOrderBook = async (symbol, depth = GLOBAL_CONFIG.CC_ORDER_BOOK_MAX_DEPTH_LEVELS) => {
             bt.loggerService.info(EXCHANGE_METHOD_NAME_GET_ORDER_BOOK, {
                 exchangeName: this.exchangeName,
                 symbol,
+                depth,
             });
             const to = new Date(Date.now());
             const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * 60 * 1000);
-            return await this._methods.getOrderBook(symbol, from, to);
+            return await this._methods.getOrderBook(symbol, depth, from, to);
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);
@@ -27453,14 +27529,19 @@ class ExchangeUtils {
         /**
          * Fetch order book for a trading pair.
          *
+         * Delegates to ExchangeInstance which calculates time range and passes it
+         * to the exchange schema implementation. The from/to parameters may be used
+         * (backtest) or ignored (live) depending on the implementation.
+         *
          * @param symbol - Trading pair symbol
          * @param context - Execution context with exchange name
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          */
-        this.getOrderBook = async (symbol, context) => {
+        this.getOrderBook = async (symbol, context, depth = GLOBAL_CONFIG.CC_ORDER_BOOK_MAX_DEPTH_LEVELS) => {
             bt.exchangeValidationService.validate(context.exchangeName, EXCHANGE_METHOD_NAME_GET_ORDER_BOOK);
             const instance = this._getInstance(context.exchangeName);
-            return await instance.getOrderBook(symbol);
+            return await instance.getOrderBook(symbol, depth);
         };
     }
 }
@@ -28455,6 +28536,7 @@ exports.getDate = getDate;
 exports.getDefaultColumns = getDefaultColumns;
 exports.getDefaultConfig = getDefaultConfig;
 exports.getMode = getMode;
+exports.getOrderBook = getOrderBook;
 exports.hasTradeContext = hasTradeContext;
 exports.lib = backtest;
 exports.listExchanges = listExchanges;

package/build/index.mjs

@@ -402,6 +402,13 @@ const GLOBAL_CONFIG = {
      * Default: 10 minutes
      */
     CC_ORDER_BOOK_TIME_OFFSET_MINUTES: 10,
+    /**
+     * Maximum depth levels for order book fetching.
+     * Specifies how many price levels to fetch from both bids and asks.
+     *
+     * Default: 20 levels
+     */
+    CC_ORDER_BOOK_MAX_DEPTH_LEVELS: 1000,
 };
 const DEFAULT_CONFIG = Object.freeze({ ...GLOBAL_CONFIG });
 
@@ -871,17 +878,23 @@ class ClientExchange {
     /**
      * Fetches order book for a trading pair.
      *
+     * Calculates time range based on execution context time (when) and
+     * CC_ORDER_BOOK_TIME_OFFSET_MINUTES, then delegates to the exchange
+     * schema implementation which may use or ignore the time range.
+     *
      * @param symbol - Trading pair symbol
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
      * @returns Promise resolving to order book data
      * @throws Error if getOrderBook is not implemented
      */
-    async getOrderBook(symbol) {
+    async getOrderBook(symbol, depth = GLOBAL_CONFIG.CC_ORDER_BOOK_MAX_DEPTH_LEVELS) {
         this.params.logger.debug("ClientExchange getOrderBook", {
             symbol,
+            depth,
         });
         const to = new Date(this.params.execution.context.when.getTime());
         const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * 60 * 1000);
-        return await this.params.getOrderBook(symbol, from, to);
+        return await this.params.getOrderBook(symbol, depth, from, to);
     }
 }
 
@@ -909,8 +922,13 @@ const DEFAULT_FORMAT_PRICE_FN$1 = async (_symbol, price) => {
 /**
  * Default implementation for getOrderBook.
  * Throws an error indicating the method is not implemented.
+ *
+ * @param _symbol - Trading pair symbol (unused)
+ * @param _depth - Maximum depth levels (unused)
+ * @param _from - Start of time range (unused - can be ignored in live implementations)
+ * @param _to - End of time range (unused - can be ignored in live implementations)
  */
-const DEFAULT_GET_ORDER_BOOK_FN$1 = async (_symbol, _from, _to) => {
+const DEFAULT_GET_ORDER_BOOK_FN$1 = async (_symbol, _depth, _from, _to) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
 /**
@@ -1051,15 +1069,19 @@ class ExchangeConnectionService {
          * Fetches order book for a trading pair using configured exchange.
          *
          * Routes to exchange determined by methodContextService.context.exchangeName.
+         * The ClientExchange will calculate time range and pass it to the schema
+         * implementation, which may use (backtest) or ignore (live) the parameters.
          *
          * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          */
-        this.getOrderBook = async (symbol) => {
+        this.getOrderBook = async (symbol, depth) => {
             this.loggerService.log("exchangeConnectionService getOrderBook", {
                 symbol,
+                depth,
             });
-            return await this.getExchange(this.methodContextService.context.exchangeName).getOrderBook(symbol);
+            return await this.getExchange(this.methodContextService.context.exchangeName).getOrderBook(symbol, depth);
         };
     }
 }
@@ -7446,23 +7468,29 @@ class ExchangeCoreService {
         /**
          * Fetches order book with execution context.
          *
+         * Sets up execution context with the provided when/backtest parameters.
+         * The exchange implementation will receive time range parameters but may
+         * choose to use them (backtest) or ignore them (live).
+         *
          * @param symbol - Trading pair symbol
          * @param when - Timestamp for context
          * @param backtest - Whether running in backtest mode
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          */
-        this.getOrderBook = async (symbol, when, backtest) => {
+        this.getOrderBook = async (symbol, when, backtest, depth) => {
             this.loggerService.log("exchangeCoreService getOrderBook", {
                 symbol,
                 when,
                 backtest,
+                depth,
             });
             if (!MethodContextService.hasContext()) {
                 throw new Error("exchangeCoreService getOrderBook requires a method context");
             }
             await this.validate(this.methodContextService.context.exchangeName);
             return await ExecutionContextService.runInContext(async () => {
-                return await this.exchangeConnectionService.getOrderBook(symbol);
+                return await this.exchangeConnectionService.getOrderBook(symbol, depth);
             }, {
                 symbol,
                 when,
@@ -21331,6 +21359,7 @@ const FORMAT_QUANTITY_METHOD_NAME = "exchange.formatQuantity";
 const GET_DATE_METHOD_NAME = "exchange.getDate";
 const GET_MODE_METHOD_NAME = "exchange.getMode";
 const HAS_TRADE_CONTEXT_METHOD_NAME = "exchange.hasTradeContext";
+const GET_ORDER_BOOK_METHOD_NAME = "exchange.getOrderBook";
 /**
  * Checks if trade context is active (execution and method contexts).
  *
@@ -21511,6 +21540,41 @@ async function getMode() {
     const { backtest: bt$1 } = bt.executionContextService.context;
     return bt$1 ? "backtest" : "live";
 }
+/**
+ * Fetches order book for a trading pair from the registered exchange.
+ *
+ * Uses current execution context to determine timing. The underlying exchange
+ * implementation receives time range parameters but may use them (backtest)
+ * or ignore them (live trading).
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
+ * @returns Promise resolving to order book data
+ * @throws Error if execution or method context is missing
+ *
+ * @example
+ * ```typescript
+ * const orderBook = await getOrderBook("BTCUSDT");
+ * console.log(orderBook.bids); // [{ price: "50000.00", quantity: "0.5" }, ...]
+ * console.log(orderBook.asks); // [{ price: "50001.00", quantity: "0.3" }, ...]
+ *
+ * // Fetch deeper order book
+ * const deepBook = await getOrderBook("BTCUSDT", 100);
+ * ```
+ */
+async function getOrderBook(symbol, depth) {
+    bt.loggerService.info(GET_ORDER_BOOK_METHOD_NAME, {
+        symbol,
+        depth,
+    });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getOrderBook requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getOrderBook requires a method context");
+    }
+    return await bt.exchangeConnectionService.getOrderBook(symbol, depth);
+}
 
 const STOP_METHOD_NAME = "strategy.stop";
 const CANCEL_METHOD_NAME = "strategy.cancel";
@@ -27111,8 +27175,13 @@ const DEFAULT_FORMAT_PRICE_FN = async (_symbol, price) => {
 /**
  * Default implementation for getOrderBook.
  * Throws an error indicating the method is not implemented.
+ *
+ * @param _symbol - Trading pair symbol (unused)
+ * @param _depth - Maximum depth levels (unused)
+ * @param _from - Start of time range (unused - can be ignored in live implementations)
+ * @param _to - End of time range (unused - can be ignored in live implementations)
  */
-const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _from, _to) => {
+const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _depth, _from, _to) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
 const INTERVAL_MINUTES$1 = {
@@ -27323,7 +27392,12 @@ class ExchangeInstance {
         /**
          * Fetch order book for a trading pair.
          *
+         * Calculates time range using CC_ORDER_BOOK_TIME_OFFSET_MINUTES (default 10 minutes)
+         * and passes it to the exchange schema implementation. The implementation may use
+         * the time range (backtest) or ignore it (live trading).
+         *
          * @param symbol - Trading pair symbol
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          * @throws Error if getOrderBook is not implemented
          *
@@ -27332,16 +27406,18 @@ class ExchangeInstance {
          * const instance = new ExchangeInstance("binance");
          * const orderBook = await instance.getOrderBook("BTCUSDT");
          * console.log(orderBook.bids); // [{ price: "50000.00", quantity: "0.5" }, ...]
+         * const deepOrderBook = await instance.getOrderBook("BTCUSDT", 100);
          * ```
          */
-        this.getOrderBook = async (symbol) => {
+        this.getOrderBook = async (symbol, depth = GLOBAL_CONFIG.CC_ORDER_BOOK_MAX_DEPTH_LEVELS) => {
             bt.loggerService.info(EXCHANGE_METHOD_NAME_GET_ORDER_BOOK, {
                 exchangeName: this.exchangeName,
                 symbol,
+                depth,
             });
             const to = new Date(Date.now());
             const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * 60 * 1000);
-            return await this._methods.getOrderBook(symbol, from, to);
+            return await this._methods.getOrderBook(symbol, depth, from, to);
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);
@@ -27433,14 +27509,19 @@ class ExchangeUtils {
         /**
          * Fetch order book for a trading pair.
          *
+         * Delegates to ExchangeInstance which calculates time range and passes it
+         * to the exchange schema implementation. The from/to parameters may be used
+         * (backtest) or ignored (live) depending on the implementation.
+         *
          * @param symbol - Trading pair symbol
          * @param context - Execution context with exchange name
+         * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
          * @returns Promise resolving to order book data
          */
-        this.getOrderBook = async (symbol, context) => {
+        this.getOrderBook = async (symbol, context, depth = GLOBAL_CONFIG.CC_ORDER_BOOK_MAX_DEPTH_LEVELS) => {
             bt.exchangeValidationService.validate(context.exchangeName, EXCHANGE_METHOD_NAME_GET_ORDER_BOOK);
             const instance = this._getInstance(context.exchangeName);
-            return await instance.getOrderBook(symbol);
+            return await instance.getOrderBook(symbol, depth);
         };
     }
 }
@@ -28386,4 +28467,4 @@ class BreakevenUtils {
  */
 const Breakeven = new BreakevenUtils();
 
-export { Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, Optimizer, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, breakeven, cancel, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenBreakeven, listenBreakevenOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, partialLoss, partialProfit, setColumns, setConfig, setLogger, stop, trailingStop, trailingTake, validate };
+export { Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, Optimizer, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, breakeven, cancel, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, getOrderBook, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenBreakeven, listenBreakevenOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, partialLoss, partialProfit, setColumns, setConfig, setLogger, stop, trailingStop, trailingTake, validate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "1.11.8",
+  "version": "1.11.9",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -460,7 +460,7 @@ interface IExchangeParams extends IExchangeSchema {
     /** Format price according to exchange precision rules (required, defaults applied) */
     formatPrice: (symbol: string, price: number) => Promise<string>;
     /** Fetch order book for a trading pair (required, defaults applied) */
-    getOrderBook: (symbol: string, from: Date, to: Date) => Promise<IOrderBookData>;
+    getOrderBook: (symbol: string, depth: number, from: Date, to: Date) => Promise<IOrderBookData>;
 }
 /**
  * Optional callbacks for exchange data events.
@@ -514,11 +514,25 @@ interface IExchangeSchema {
      * Optional. If not provided, throws an error when called.
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param from - Start of time range for order book snapshot
-     * @param to - End of time range for order book snapshot
+     * @param depth - Maximum depth levels for both bids and asks (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
+     * @param from - Start of time range (used in backtest for historical data, can be ignored in live)
+     * @param to - End of time range (used in backtest for historical data, can be ignored in live)
      * @returns Promise resolving to order book data
+     *
+     * @example
+     * ```typescript
+     * // Backtest implementation: returns historical order book for the time range
+     * const backtestOrderBook = async (symbol: string, depth: number, from: Date, to: Date) => {
+     *   return await database.getOrderBookSnapshot(symbol, depth, from, to);
+     * };
+     *
+     * // Live implementation: ignores from/to and returns current snapshot
+     * const liveOrderBook = async (symbol: string, depth: number, _from: Date, _to: Date) => {
+     *   return await exchange.fetchOrderBook(symbol, depth);
+     * };
+     * ```
      */
-    getOrderBook?: (symbol: string, from: Date, to: Date) => Promise<IOrderBookData>;
+    getOrderBook?: (symbol: string, depth: number, from: Date, to: Date) => Promise<IOrderBookData>;
     /** Optional lifecycle event callbacks (onCandleData) */
     callbacks?: Partial<IExchangeCallbacks>;
 }
@@ -575,9 +589,10 @@ interface IExchange {
      * Fetch order book for a trading pair.
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
      * @returns Promise resolving to order book data
      */
-    getOrderBook: (symbol: string) => Promise<IOrderBookData>;
+    getOrderBook: (symbol: string, depth?: number) => Promise<IOrderBookData>;
 }
 /**
  * Unique exchange identifier.
@@ -2124,6 +2139,13 @@ declare const GLOBAL_CONFIG: {
      * Default: 10 minutes
      */
     CC_ORDER_BOOK_TIME_OFFSET_MINUTES: number;
+    /**
+     * Maximum depth levels for order book fetching.
+     * Specifies how many price levels to fetch from both bids and asks.
+     *
+     * Default: 20 levels
+     */
+    CC_ORDER_BOOK_MAX_DEPTH_LEVELS: number;
 };
 /**
  * Type for global configuration object.
@@ -2227,6 +2249,7 @@ declare function getConfig(): {
     CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
     CC_BREAKEVEN_THRESHOLD: number;
     CC_ORDER_BOOK_TIME_OFFSET_MINUTES: number;
+    CC_ORDER_BOOK_MAX_DEPTH_LEVELS: number;
 };
 /**
  * Retrieves the default configuration object for the framework.
@@ -2260,6 +2283,7 @@ declare function getDefaultConfig(): Readonly<{
     CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
     CC_BREAKEVEN_THRESHOLD: number;
     CC_ORDER_BOOK_TIME_OFFSET_MINUTES: number;
+    CC_ORDER_BOOK_MAX_DEPTH_LEVELS: number;
 }>;
 /**
  * Sets custom column configurations for markdown report generation.
@@ -5360,6 +5384,29 @@ declare function getDate(): Promise<Date>;
  * ```
  */
 declare function getMode(): Promise<"backtest" | "live">;
+/**
+ * Fetches order book for a trading pair from the registered exchange.
+ *
+ * Uses current execution context to determine timing. The underlying exchange
+ * implementation receives time range parameters but may use them (backtest)
+ * or ignore them (live trading).
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
+ * @returns Promise resolving to order book data
+ * @throws Error if execution or method context is missing
+ *
+ * @example
+ * ```typescript
+ * const orderBook = await getOrderBook("BTCUSDT");
+ * console.log(orderBook.bids); // [{ price: "50000.00", quantity: "0.5" }, ...]
+ * console.log(orderBook.asks); // [{ price: "50001.00", quantity: "0.3" }, ...]
+ *
+ * // Fetch deeper order book
+ * const deepBook = await getOrderBook("BTCUSDT", 100);
+ * ```
+ */
+declare function getOrderBook(symbol: string, depth?: number): Promise<IOrderBookData>;
 
 /**
  * Dumps signal data and LLM conversation history to markdown files.
@@ -11138,13 +11185,18 @@ declare class ExchangeUtils {
     /**
      * Fetch order book for a trading pair.
      *
+     * Delegates to ExchangeInstance which calculates time range and passes it
+     * to the exchange schema implementation. The from/to parameters may be used
+     * (backtest) or ignored (live) depending on the implementation.
+     *
      * @param symbol - Trading pair symbol
      * @param context - Execution context with exchange name
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
      * @returns Promise resolving to order book data
      */
     getOrderBook: (symbol: string, context: {
         exchangeName: ExchangeName;
-    }) => Promise<IOrderBookData>;
+    }, depth?: number) => Promise<IOrderBookData>;
 }
 /**
  * Singleton instance of ExchangeUtils for convenient exchange operations.
@@ -12057,11 +12109,16 @@ declare class ClientExchange implements IExchange {
     /**
      * Fetches order book for a trading pair.
      *
+     * Calculates time range based on execution context time (when) and
+     * CC_ORDER_BOOK_TIME_OFFSET_MINUTES, then delegates to the exchange
+     * schema implementation which may use or ignore the time range.
+     *
      * @param symbol - Trading pair symbol
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
      * @returns Promise resolving to order book data
      * @throws Error if getOrderBook is not implemented
      */
-    getOrderBook(symbol: string): Promise<IOrderBookData>;
+    getOrderBook(symbol: string, depth?: number): Promise<IOrderBookData>;
 }
 
 /**
@@ -12158,11 +12215,14 @@ declare class ExchangeConnectionService implements IExchange {
      * Fetches order book for a trading pair using configured exchange.
      *
      * Routes to exchange determined by methodContextService.context.exchangeName.
+     * The ClientExchange will calculate time range and pass it to the schema
+     * implementation, which may use (backtest) or ignore (live) the parameters.
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
      * @returns Promise resolving to order book data
      */
-    getOrderBook: (symbol: string) => Promise<IOrderBookData>;
+    getOrderBook: (symbol: string, depth?: number) => Promise<IOrderBookData>;
 }
 
 /**
@@ -13222,12 +13282,17 @@ declare class ExchangeCoreService implements TExchange {
     /**
      * Fetches order book with execution context.
      *
+     * Sets up execution context with the provided when/backtest parameters.
+     * The exchange implementation will receive time range parameters but may
+     * choose to use them (backtest) or ignore them (live).
+     *
      * @param symbol - Trading pair symbol
      * @param when - Timestamp for context
      * @param backtest - Whether running in backtest mode
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
      * @returns Promise resolving to order book data
      */
-    getOrderBook: (symbol: string, when: Date, backtest: boolean) => Promise<IOrderBookData>;
+    getOrderBook: (symbol: string, when: Date, backtest: boolean, depth?: number) => Promise<IOrderBookData>;
 }
 
 /**
@@ -16194,4 +16259,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type BacktestDoneNotification, type BacktestStatisticsModel, type BootstrapNotification, Breakeven, type BreakevenContract, type BreakevenData, Cache, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IBidData, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IOrderBookData, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveDoneNotification, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, type MessageModel, type MessageRole, MethodContextService, type MetricStats, Notification, type NotificationModel, Optimizer, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossContract, type PartialLossNotification, type PartialProfitContract, type PartialProfitNotification, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, type PingContract, PositionSize, type ProgressBacktestContract, type ProgressBacktestNotification, type ProgressOptimizerContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, type TMarkdownBase, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TickEvent, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, breakeven, cancel, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenBreakeven, listenBreakevenOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, partialLoss, partialProfit, setColumns, setConfig, setLogger, stop, trailingStop, trailingTake, validate };
+export { Backtest, type BacktestDoneNotification, type BacktestStatisticsModel, type BootstrapNotification, Breakeven, type BreakevenContract, type BreakevenData, Cache, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IBidData, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IOrderBookData, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveDoneNotification, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, type MessageModel, type MessageRole, MethodContextService, type MetricStats, Notification, type NotificationModel, Optimizer, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossContract, type PartialLossNotification, type PartialProfitContract, type PartialProfitNotification, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, type PingContract, PositionSize, type ProgressBacktestContract, type ProgressBacktestNotification, type ProgressOptimizerContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, type TMarkdownBase, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TickEvent, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, breakeven, cancel, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, getOrderBook, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenBreakeven, listenBreakevenOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, partialLoss, partialProfit, setColumns, setConfig, setLogger, stop, trailingStop, trailingTake, validate };