backtest-kit 2.1.2 → 2.1.3

package/build/index.mjs

@@ -1646,6 +1646,7 @@ class PersistCandleUtils {
  */
 const PersistCandleAdapter = new PersistCandleUtils();
 
+const MS_PER_MINUTE$1 = 60000;
 const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
@@ -1791,7 +1792,7 @@ const WRITE_CANDLES_CACHE_FN$1 = trycatch(queued(async (candles, dto, self) => {
 const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$4[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * 60 * 1000;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$1;
     // Try to read from cache first
     const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
     if (cachedCandles !== null) {
@@ -1897,7 +1898,7 @@ class ClientExchange {
         if (!adjust) {
             throw new Error(`ClientExchange unknown time adjust for interval=${interval}`);
         }
-        const since = new Date(this.params.execution.context.when.getTime() - adjust * 60 * 1000);
+        const since = new Date(this.params.execution.context.when.getTime() - adjust * MS_PER_MINUTE$1);
         let allData = [];
         // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
         if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
@@ -1910,7 +1911,7 @@ class ClientExchange {
                 remaining -= chunkLimit;
                 if (remaining > 0) {
                     // Move currentSince forward by the number of candles fetched
-                    currentSince = new Date(currentSince.getTime() + chunkLimit * step * 60 * 1000);
+                    currentSince = new Date(currentSince.getTime() + chunkLimit * step * MS_PER_MINUTE$1);
                 }
             }
         }
@@ -1957,7 +1958,7 @@ class ClientExchange {
         const now = Date.now();
         // Вычисляем конечное время запроса
         const step = INTERVAL_MINUTES$4[interval];
-        const endTime = since.getTime() + limit * step * 60 * 1000;
+        const endTime = since.getTime() + limit * step * MS_PER_MINUTE$1;
         // Проверяем что запрошенный период не заходит за Date.now()
         if (endTime > now) {
             return [];
@@ -1974,7 +1975,7 @@ class ClientExchange {
                 remaining -= chunkLimit;
                 if (remaining > 0) {
                     // Move currentSince forward by the number of candles fetched
-                    currentSince = new Date(currentSince.getTime() + chunkLimit * step * 60 * 1000);
+                    currentSince = new Date(currentSince.getTime() + chunkLimit * step * MS_PER_MINUTE$1);
                 }
             }
         }
@@ -2069,22 +2070,19 @@ class ClientExchange {
     /**
      * Fetches raw candles with flexible date/limit parameters.
      *
-     * Compatibility layer that:
-     * - RAW MODE (sDate + eDate + limit): fetches exactly as specified, NO look-ahead bias protection
-     * - Other modes: respects execution context and prevents look-ahead bias
+     * All modes respect execution context and prevent look-ahead bias.
      *
      * Parameter combinations:
-     * 1. sDate + eDate + limit: RAW MODE - fetches exactly as specified, no validation against when
-     * 2. sDate + eDate: calculates limit from date range, validates endTimestamp <= when
-     * 3. eDate + limit: calculates sDate backward, validates endTimestamp <= when
-     * 4. sDate + limit: fetches forward, validates endTimestamp <= when
+     * 1. sDate + eDate + limit: fetches with explicit parameters, validates eDate <= when
+     * 2. sDate + eDate: calculates limit from date range, validates eDate <= when
+     * 3. eDate + limit: calculates sDate backward, validates eDate <= when
+     * 4. sDate + limit: fetches forward, validates calculated endTimestamp <= when
      * 5. Only limit: uses execution.context.when as reference (backward)
      *
      * Edge cases:
      * - If calculated limit is 0 or negative: throws error
      * - If sDate >= eDate: throws error
-     * - If startTimestamp >= endTimestamp: throws error
-     * - If endTimestamp > when (non-RAW modes only): throws error to prevent look-ahead bias
+     * - If eDate > when: throws error to prevent look-ahead bias
      *
      * @param symbol - Trading pair symbol
      * @param interval - Candle interval
@@ -2103,73 +2101,75 @@ class ClientExchange {
             eDate,
         });
         const step = INTERVAL_MINUTES$4[interval];
-        const stepMs = step * 60 * 1000;
-        const when = this.params.execution.context.when.getTime();
-        let startTimestamp;
-        let endTimestamp;
-        let candleLimit;
-        let isRawMode = false;
-        // Case 1: sDate + eDate + limit - RAW MODE (no look-ahead bias protection)
-        if (sDate !== undefined &&
-            eDate !== undefined &&
-            limit !== undefined) {
-            isRawMode = true;
+        if (!step) {
+            throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
+        }
+        const whenTimestamp = this.params.execution.context.when.getTime();
+        let sinceTimestamp;
+        let untilTimestamp;
+        let calculatedLimit;
+        // Case 1: all three parameters provided
+        if (sDate !== undefined && eDate !== undefined && limit !== undefined) {
             if (sDate >= eDate) {
-                throw new Error(`ClientExchange getRawCandles: sDate (${sDate}) must be less than eDate (${eDate})`);
+                throw new Error(`ClientExchange getRawCandles: sDate (${sDate}) must be < eDate (${eDate})`);
+            }
+            if (eDate > whenTimestamp) {
+                throw new Error(`ClientExchange getRawCandles: eDate (${eDate}) exceeds execution context when (${whenTimestamp}). Look-ahead bias protection.`);
             }
-            startTimestamp = sDate;
-            endTimestamp = eDate;
-            candleLimit = limit;
+            sinceTimestamp = sDate;
+            untilTimestamp = eDate;
+            calculatedLimit = limit;
         }
-        // Case 2: sDate + eDate - calculate limit, respect backtest context
+        // Case 2: sDate + eDate (no limit) - calculate limit from date range
         else if (sDate !== undefined && eDate !== undefined && limit === undefined) {
             if (sDate >= eDate) {
-                throw new Error(`ClientExchange getRawCandles: sDate (${sDate}) must be less than eDate (${eDate})`);
-            }
-            startTimestamp = sDate;
-            endTimestamp = eDate;
-            const rangeDuration = endTimestamp - startTimestamp;
-            candleLimit = Math.floor(rangeDuration / stepMs);
-            if (candleLimit <= 0) {
-                throw new Error(`ClientExchange getRawCandles: calculated limit is ${candleLimit} for range [${sDate}, ${eDate}]`);
-            }
-        }
-        // Case 3: eDate + limit - calculate sDate backward, respect backtest context
-        else if (eDate !== undefined && limit !== undefined && sDate === undefined) {
-            endTimestamp = eDate;
-            startTimestamp = eDate - limit * stepMs;
-            candleLimit = limit;
-        }
-        // Case 4: sDate + limit - fetch forward, respect backtest context
-        else if (sDate !== undefined && limit !== undefined && eDate === undefined) {
-            startTimestamp = sDate;
-            endTimestamp = sDate + limit * stepMs;
-            candleLimit = limit;
-        }
-        // Case 5: Only limit - use execution context (backward from when)
-        else if (limit !== undefined && sDate === undefined && eDate === undefined) {
-            endTimestamp = when;
-            startTimestamp = when - limit * stepMs;
-            candleLimit = limit;
-        }
-        // Invalid combination
-        else {
-            throw new Error(`ClientExchange getRawCandles: invalid parameter combination. Must provide either (limit), (eDate+limit), (sDate+limit), (sDate+eDate), or (sDate+eDate+limit)`);
+                throw new Error(`ClientExchange getRawCandles: sDate (${sDate}) must be < eDate (${eDate})`);
+            }
+            if (eDate > whenTimestamp) {
+                throw new Error(`ClientExchange getRawCandles: eDate (${eDate}) exceeds execution context when (${whenTimestamp}). Look-ahead bias protection.`);
+            }
+            sinceTimestamp = sDate;
+            untilTimestamp = eDate;
+            calculatedLimit = Math.ceil((eDate - sDate) / (step * MS_PER_MINUTE$1));
+            if (calculatedLimit <= 0) {
+                throw new Error(`ClientExchange getRawCandles: calculated limit is ${calculatedLimit}, must be > 0`);
+            }
+        }
+        // Case 3: eDate + limit (no sDate) - calculate sDate backward from eDate
+        else if (sDate === undefined && eDate !== undefined && limit !== undefined) {
+            if (eDate > whenTimestamp) {
+                throw new Error(`ClientExchange getRawCandles: eDate (${eDate}) exceeds execution context when (${whenTimestamp}). Look-ahead bias protection.`);
+            }
+            untilTimestamp = eDate;
+            sinceTimestamp = eDate - limit * step * MS_PER_MINUTE$1;
+            calculatedLimit = limit;
         }
-        // Validate timestamps
-        if (startTimestamp >= endTimestamp) {
-            throw new Error(`ClientExchange getRawCandles: startTimestamp (${startTimestamp}) >= endTimestamp (${endTimestamp})`);
+        // Case 4: sDate + limit (no eDate) - calculate eDate forward from sDate
+        else if (sDate !== undefined && eDate === undefined && limit !== undefined) {
+            sinceTimestamp = sDate;
+            untilTimestamp = sDate + limit * step * MS_PER_MINUTE$1;
+            if (untilTimestamp > whenTimestamp) {
+                throw new Error(`ClientExchange getRawCandles: calculated endTimestamp (${untilTimestamp}) exceeds execution context when (${whenTimestamp}). Look-ahead bias protection.`);
+            }
+            calculatedLimit = limit;
+        }
+        // Case 5: Only limit - use execution.context.when as reference (backward like getCandles)
+        else if (sDate === undefined && eDate === undefined && limit !== undefined) {
+            untilTimestamp = whenTimestamp;
+            sinceTimestamp = whenTimestamp - limit * step * MS_PER_MINUTE$1;
+            calculatedLimit = limit;
         }
-        // Check if trying to fetch future data (prevent look-ahead bias)
-        // ONLY for non-RAW modes - RAW MODE bypasses this check
-        if (!isRawMode && endTimestamp > when) {
-            throw new Error(`ClientExchange getRawCandles: endTimestamp (${endTimestamp}) is beyond execution context when (${when}) - look-ahead bias prevented`);
+        // Invalid: no parameters or only sDate or only eDate
+        else {
+            throw new Error(`ClientExchange getRawCandles: invalid parameter combination. ` +
+                `Provide one of: (sDate+eDate+limit), (sDate+eDate), (eDate+limit), (sDate+limit), or (limit only). ` +
+                `Got: sDate=${sDate}, eDate=${eDate}, limit=${limit}`);
         }
-        const since = new Date(startTimestamp);
+        // Fetch candles using existing logic
+        const since = new Date(sinceTimestamp);
         let allData = [];
-        // Fetch data in chunks if limit exceeds max per request
-        if (candleLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-            let remaining = candleLimit;
+        if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+            let remaining = calculatedLimit;
             let currentSince = new Date(since.getTime());
             while (remaining > 0) {
                 const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
@@ -2177,16 +2177,16 @@ class ClientExchange {
                 allData.push(...chunkData);
                 remaining -= chunkLimit;
                 if (remaining > 0) {
-                    currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                    currentSince = new Date(currentSince.getTime() + chunkLimit * step * MS_PER_MINUTE$1);
                 }
             }
         }
         else {
-            allData = await GET_CANDLES_FN({ symbol, interval, limit: candleLimit }, since, this);
+            allData = await GET_CANDLES_FN({ symbol, interval, limit: calculatedLimit }, since, this);
         }
         // Filter candles to strictly match the requested range
-        const filteredData = allData.filter((candle) => candle.timestamp >= startTimestamp &&
-            candle.timestamp < endTimestamp);
+        const filteredData = allData.filter((candle) => candle.timestamp >= sinceTimestamp &&
+            candle.timestamp < untilTimestamp);
         // Apply distinct by timestamp to remove duplicates
         const uniqueData = Array.from(new Map(filteredData.map((candle) => [candle.timestamp, candle])).values());
         if (filteredData.length !== uniqueData.length) {
@@ -2194,12 +2194,12 @@ class ClientExchange {
             this.params.logger.warn(msg);
             console.warn(msg);
         }
-        if (uniqueData.length < candleLimit) {
-            const msg = `ClientExchange getRawCandles: Expected ${candleLimit} candles, got ${uniqueData.length}`;
+        if (uniqueData.length < calculatedLimit) {
+            const msg = `ClientExchange getRawCandles: Expected ${calculatedLimit} candles, got ${uniqueData.length}`;
             this.params.logger.warn(msg);
             console.warn(msg);
         }
-        await CALL_CANDLE_DATA_CALLBACKS_FN(this, symbol, interval, since, candleLimit, uniqueData);
+        await CALL_CANDLE_DATA_CALLBACKS_FN(this, symbol, interval, since, calculatedLimit, uniqueData);
         return uniqueData;
     }
     /**
@@ -2221,7 +2221,7 @@ class ClientExchange {
         });
         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);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -2412,6 +2412,28 @@ class ExchangeConnectionService {
             });
             return await this.getExchange(this.methodContextService.context.exchangeName).getOrderBook(symbol, depth);
         };
+        /**
+         * Fetches raw candles with flexible date/limit parameters.
+         *
+         * Routes to exchange determined by methodContextService.context.exchangeName.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param interval - Candle interval (e.g., "1h", "1d")
+         * @param limit - Optional number of candles to fetch
+         * @param sDate - Optional start date in milliseconds
+         * @param eDate - Optional end date in milliseconds
+         * @returns Promise resolving to array of candle data
+         */
+        this.getRawCandles = async (symbol, interval, limit, sDate, eDate) => {
+            this.loggerService.log("exchangeConnectionService getRawCandles", {
+                symbol,
+                interval,
+                limit,
+                sDate,
+                eDate,
+            });
+            return await this.getExchange(this.methodContextService.context.exchangeName).getRawCandles(symbol, interval, limit, sDate, eDate);
+        };
     }
 }
 
@@ -9955,6 +9977,40 @@ class ExchangeCoreService {
                 backtest,
             });
         };
+        /**
+         * Fetches raw candles with flexible date/limit parameters and execution context.
+         *
+         * @param symbol - Trading pair symbol
+         * @param interval - Candle interval (e.g., "1m", "1h")
+         * @param when - Timestamp for context (used in backtest mode)
+         * @param backtest - Whether running in backtest mode
+         * @param limit - Optional number of candles to fetch
+         * @param sDate - Optional start date in milliseconds
+         * @param eDate - Optional end date in milliseconds
+         * @returns Promise resolving to array of candles
+         */
+        this.getRawCandles = async (symbol, interval, when, backtest, limit, sDate, eDate) => {
+            this.loggerService.log("exchangeCoreService getRawCandles", {
+                symbol,
+                interval,
+                when,
+                backtest,
+                limit,
+                sDate,
+                eDate,
+            });
+            if (!MethodContextService.hasContext()) {
+                throw new Error("exchangeCoreService getRawCandles requires a method context");
+            }
+            await this.validate(this.methodContextService.context.exchangeName);
+            return await ExecutionContextService.runInContext(async () => {
+                return await this.exchangeConnectionService.getRawCandles(symbol, interval, limit, sDate, eDate);
+            }, {
+                symbol,
+                when,
+                backtest,
+            });
+        };
     }
 }
 
@@ -25258,6 +25314,7 @@ const GET_SYMBOL_METHOD_NAME = "exchange.getSymbol";
 const GET_CONTEXT_METHOD_NAME = "exchange.getContext";
 const HAS_TRADE_CONTEXT_METHOD_NAME = "exchange.hasTradeContext";
 const GET_ORDER_BOOK_METHOD_NAME = "exchange.getOrderBook";
+const GET_RAW_CANDLES_METHOD_NAME = "exchange.getRawCandles";
 /**
  * Checks if trade context is active (execution and method contexts).
  *
@@ -25515,6 +25572,53 @@ async function getOrderBook(symbol, depth) {
     }
     return await bt.exchangeConnectionService.getOrderBook(symbol, depth);
 }
+/**
+ * Fetches raw candles with flexible date/limit parameters.
+ *
+ * All modes respect execution context and prevent look-ahead bias.
+ *
+ * Parameter combinations:
+ * 1. sDate + eDate + limit: fetches with explicit parameters, validates eDate <= when
+ * 2. sDate + eDate: calculates limit from date range, validates eDate <= when
+ * 3. eDate + limit: calculates sDate backward, validates eDate <= when
+ * 4. sDate + limit: fetches forward, validates calculated endTimestamp <= when
+ * 5. Only limit: uses execution.context.when as reference (backward)
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param interval - Candle interval ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h")
+ * @param limit - Optional number of candles to fetch
+ * @param sDate - Optional start date in milliseconds
+ * @param eDate - Optional end date in milliseconds
+ * @returns Promise resolving to array of candle data
+ *
+ * @example
+ * ```typescript
+ * // Fetch 100 candles backward from current context time
+ * const candles = await getRawCandles("BTCUSDT", "1m", 100);
+ *
+ * // Fetch candles for specific date range
+ * const rangeCandles = await getRawCandles("BTCUSDT", "1h", undefined, startMs, endMs);
+ *
+ * // Fetch with all parameters specified
+ * const exactCandles = await getRawCandles("BTCUSDT", "1m", 100, startMs, endMs);
+ * ```
+ */
+async function getRawCandles(symbol, interval, limit, sDate, eDate) {
+    bt.loggerService.info(GET_RAW_CANDLES_METHOD_NAME, {
+        symbol,
+        interval,
+        limit,
+        sDate,
+        eDate,
+    });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getRawCandles requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getRawCandles requires a method context");
+    }
+    return await bt.exchangeConnectionService.getRawCandles(symbol, interval, limit, sDate, eDate);
+}
 
 const CANCEL_SCHEDULED_METHOD_NAME = "strategy.commitCancelScheduled";
 const CLOSE_PENDING_METHOD_NAME = "strategy.commitClosePending";
@@ -31786,6 +31890,8 @@ const EXCHANGE_METHOD_NAME_GET_AVERAGE_PRICE = "ExchangeUtils.getAveragePrice";
 const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
 const EXCHANGE_METHOD_NAME_GET_ORDER_BOOK = "ExchangeUtils.getOrderBook";
+const EXCHANGE_METHOD_NAME_GET_RAW_CANDLES = "ExchangeUtils.getRawCandles";
+const MS_PER_MINUTE = 60000;
 /**
  * Gets backtest mode flag from execution context if available.
  * Returns false if no execution context exists (live mode).
@@ -32139,6 +32245,151 @@ class ExchangeInstance {
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
+        /**
+         * Fetches raw candles with flexible date/limit parameters.
+         *
+         * Uses Date.now() instead of execution context when for look-ahead bias protection.
+         *
+         * Parameter combinations:
+         * 1. sDate + eDate + limit: fetches with explicit parameters, validates eDate <= now
+         * 2. sDate + eDate: calculates limit from date range, validates eDate <= now
+         * 3. eDate + limit: calculates sDate backward, validates eDate <= now
+         * 4. sDate + limit: fetches forward, validates calculated endTimestamp <= now
+         * 5. Only limit: uses Date.now() as reference (backward)
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param interval - Candle interval (e.g., "1m", "1h")
+         * @param limit - Optional number of candles to fetch
+         * @param sDate - Optional start date in milliseconds
+         * @param eDate - Optional end date in milliseconds
+         * @returns Promise resolving to array of candle data
+         *
+         * @example
+         * ```typescript
+         * const instance = new ExchangeInstance("binance");
+         *
+         * // Fetch 100 candles backward from now
+         * const candles = await instance.getRawCandles("BTCUSDT", "1m", 100);
+         *
+         * // Fetch candles for specific date range
+         * const rangeCandles = await instance.getRawCandles("BTCUSDT", "1h", undefined, startMs, endMs);
+         * ```
+         */
+        this.getRawCandles = async (symbol, interval, limit, sDate, eDate) => {
+            bt.loggerService.info(EXCHANGE_METHOD_NAME_GET_RAW_CANDLES, {
+                exchangeName: this.exchangeName,
+                symbol,
+                interval,
+                limit,
+                sDate,
+                eDate,
+            });
+            const step = INTERVAL_MINUTES$1[interval];
+            if (!step) {
+                throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
+            }
+            const nowTimestamp = Date.now();
+            let sinceTimestamp;
+            let untilTimestamp;
+            let calculatedLimit;
+            // Case 1: all three parameters provided
+            if (sDate !== undefined && eDate !== undefined && limit !== undefined) {
+                if (sDate >= eDate) {
+                    throw new Error(`ExchangeInstance getRawCandles: sDate (${sDate}) must be < eDate (${eDate})`);
+                }
+                if (eDate > nowTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: eDate (${eDate}) exceeds current time (${nowTimestamp}). Look-ahead bias protection.`);
+                }
+                sinceTimestamp = sDate;
+                untilTimestamp = eDate;
+                calculatedLimit = limit;
+            }
+            // Case 2: sDate + eDate (no limit) - calculate limit from date range
+            else if (sDate !== undefined && eDate !== undefined && limit === undefined) {
+                if (sDate >= eDate) {
+                    throw new Error(`ExchangeInstance getRawCandles: sDate (${sDate}) must be < eDate (${eDate})`);
+                }
+                if (eDate > nowTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: eDate (${eDate}) exceeds current time (${nowTimestamp}). Look-ahead bias protection.`);
+                }
+                sinceTimestamp = sDate;
+                untilTimestamp = eDate;
+                calculatedLimit = Math.ceil((eDate - sDate) / (step * MS_PER_MINUTE));
+                if (calculatedLimit <= 0) {
+                    throw new Error(`ExchangeInstance getRawCandles: calculated limit is ${calculatedLimit}, must be > 0`);
+                }
+            }
+            // Case 3: eDate + limit (no sDate) - calculate sDate backward from eDate
+            else if (sDate === undefined && eDate !== undefined && limit !== undefined) {
+                if (eDate > nowTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: eDate (${eDate}) exceeds current time (${nowTimestamp}). Look-ahead bias protection.`);
+                }
+                untilTimestamp = eDate;
+                sinceTimestamp = eDate - limit * step * MS_PER_MINUTE;
+                calculatedLimit = limit;
+            }
+            // Case 4: sDate + limit (no eDate) - calculate eDate forward from sDate
+            else if (sDate !== undefined && eDate === undefined && limit !== undefined) {
+                sinceTimestamp = sDate;
+                untilTimestamp = sDate + limit * step * MS_PER_MINUTE;
+                if (untilTimestamp > nowTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: calculated endTimestamp (${untilTimestamp}) exceeds current time (${nowTimestamp}). Look-ahead bias protection.`);
+                }
+                calculatedLimit = limit;
+            }
+            // Case 5: Only limit - use Date.now() as reference (backward)
+            else if (sDate === undefined && eDate === undefined && limit !== undefined) {
+                untilTimestamp = nowTimestamp;
+                sinceTimestamp = nowTimestamp - limit * step * MS_PER_MINUTE;
+                calculatedLimit = limit;
+            }
+            // Invalid: no parameters or only sDate or only eDate
+            else {
+                throw new Error(`ExchangeInstance getRawCandles: invalid parameter combination. ` +
+                    `Provide one of: (sDate+eDate+limit), (sDate+eDate), (eDate+limit), (sDate+limit), or (limit only). ` +
+                    `Got: sDate=${sDate}, eDate=${eDate}, limit=${limit}`);
+            }
+            // Try to read from cache first
+            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+            if (cachedCandles !== null) {
+                return cachedCandles;
+            }
+            // Fetch candles
+            const since = new Date(sinceTimestamp);
+            let allData = [];
+            const isBacktest = await GET_BACKTEST_FN();
+            const getCandles = this._methods.getCandles;
+            if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                let remaining = calculatedLimit;
+                let currentSince = new Date(since.getTime());
+                while (remaining > 0) {
+                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                    allData.push(...chunkData);
+                    remaining -= chunkLimit;
+                    if (remaining > 0) {
+                        currentSince = new Date(currentSince.getTime() + chunkLimit * step * MS_PER_MINUTE);
+                    }
+                }
+            }
+            else {
+                allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
+            }
+            // Filter candles to strictly match the requested range
+            const filteredData = allData.filter((candle) => candle.timestamp >= sinceTimestamp &&
+                candle.timestamp < untilTimestamp);
+            // Apply distinct by timestamp to remove duplicates
+            const uniqueData = Array.from(new Map(filteredData.map((candle) => [candle.timestamp, candle])).values());
+            if (filteredData.length !== uniqueData.length) {
+                bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${filteredData.length - uniqueData.length} duplicate candles by timestamp`);
+            }
+            if (uniqueData.length < calculatedLimit) {
+                bt.loggerService.warn(`ExchangeInstance getRawCandles: Expected ${calculatedLimit} candles, got ${uniqueData.length}`);
+            }
+            // Write to cache after successful fetch
+            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
+            return uniqueData;
+        };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);
     }
@@ -32243,6 +32494,24 @@ class ExchangeUtils {
             const instance = this._getInstance(context.exchangeName);
             return await instance.getOrderBook(symbol, depth);
         };
+        /**
+         * Fetches raw candles with flexible date/limit parameters.
+         *
+         * Uses Date.now() instead of execution context when for look-ahead bias protection.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param interval - Candle interval (e.g., "1m", "1h")
+         * @param context - Execution context with exchange name
+         * @param limit - Optional number of candles to fetch
+         * @param sDate - Optional start date in milliseconds
+         * @param eDate - Optional end date in milliseconds
+         * @returns Promise resolving to array of candle data
+         */
+        this.getRawCandles = async (symbol, interval, context, limit, sDate, eDate) => {
+            bt.exchangeValidationService.validate(context.exchangeName, EXCHANGE_METHOD_NAME_GET_RAW_CANDLES);
+            const instance = this._getInstance(context.exchangeName);
+            return await instance.getRawCandles(symbol, interval, limit, sDate, eDate);
+        };
     }
 }
 /**
@@ -33374,4 +33643,4 @@ const set = (object, path, value) => {
     }
 };
 
-export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, Optimizer, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addOptimizerSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitSignalPromptHistory, commitTrailingStop, commitTrailingTake, dumpSignalData, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getOptimizerSchema, getOrderBook, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listOptimizerSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideOptimizerSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate };
+export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, Optimizer, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addOptimizerSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitSignalPromptHistory, commitTrailingStop, commitTrailingTake, dumpSignalData, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getOptimizerSchema, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listOptimizerSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideOptimizerSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate };

package/package.json

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