backtest-kit 2.1.2 → 2.1.3

package/build/index.cjs

@@ -1667,6 +1667,7 @@ class PersistCandleUtils {
  */
 const PersistCandleAdapter = new PersistCandleUtils();
 
+const MS_PER_MINUTE$1 = 60000;
 const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
@@ -1812,7 +1813,7 @@ const WRITE_CANDLES_CACHE_FN$1 = functoolsKit.trycatch(functoolsKit.queued(async
 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) {
@@ -1918,7 +1919,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) {
@@ -1931,7 +1932,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);
                 }
             }
         }
@@ -1978,7 +1979,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 [];
@@ -1995,7 +1996,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);
                 }
             }
         }
@@ -2090,22 +2091,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
@@ -2124,73 +2122,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);
@@ -2198,16 +2198,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) {
@@ -2215,12 +2215,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;
     }
     /**
@@ -2242,7 +2242,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);
     }
 }
@@ -2433,6 +2433,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);
+        };
     }
 }
 
@@ -9976,6 +9998,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,
+            });
+        };
     }
 }
 
@@ -25279,6 +25335,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).
  *
@@ -25536,6 +25593,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";
@@ -31807,6 +31911,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).
@@ -32160,6 +32266,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);
     }
@@ -32264,6 +32515,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);
+        };
     }
 }
 /**
@@ -33461,6 +33730,7 @@ exports.getFrameSchema = getFrameSchema;
 exports.getMode = getMode;
 exports.getOptimizerSchema = getOptimizerSchema;
 exports.getOrderBook = getOrderBook;
+exports.getRawCandles = getRawCandles;
 exports.getRiskSchema = getRiskSchema;
 exports.getSizingSchema = getSizingSchema;
 exports.getStrategySchema = getStrategySchema;