backtest-kit 4.0.1 → 5.0.0

package/build/index.cjs

@@ -470,9 +470,17 @@ const GLOBAL_CONFIG = {
      * Allows to commitAverageBuy if currentPrice is not the lowest price since entry, but still lower than priceOpen.
      * This can help improve average entry price in cases where price has rebounded after entry but is still below priceOpen, without waiting for a new lower price.
      *
-     * Default: true (DCA logic enabled everywhere, not just when antirecord is broken)
+     * Default: false (DCA logic enabled only when antirecord is broken)
      */
     CC_ENABLE_DCA_EVERYWHERE: false,
+    /**
+     * Enables PPPL (Partial Profit, Partial Loss) logic even if this breaks a direction of exits
+     * Allows to take partial profit or loss on a position even if it results in a mix of profit and loss exits
+     * This can help lock in profits or cut losses on part of the position without waiting for a perfect exit scenario.
+     *
+     * Default: false (PPPL logic is only applied when it does not break the direction of exits, ensuring clearer profit/loss outcomes)
+     */
+    CC_ENABLE_PPPL_EVERYWHERE: false,
     /**
      * Cost of entering a position (in USD).
      * This is used as a default value for calculating position size and risk management when cost data is not provided by the strategy
@@ -6630,6 +6638,18 @@ class ClientStrategy {
         }
         return entries.map((e) => e.price);
     }
+    /**
+     * Returns the list of partial closes for the current pending signal.
+     *
+     * Each entry records a partial profit or loss close event with its type,
+     * percent closed, price at close, cost basis snapshot, and entry count at close.
+     *
+     * Returns null if no pending signal exists.
+     * Returns an empty array if no partial closes have been executed.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to array of partial close records or null
+     */
     async getPositionPartials(symbol) {
         this.params.logger.debug("ClientStrategy getPositionPartials", { symbol });
         if (!this._pendingSignal) {
@@ -6637,6 +6657,34 @@ class ClientStrategy {
         }
         return this._pendingSignal._partial ?? [];
     }
+    /**
+     * Returns the list of DCA entry prices and costs for the current pending signal.
+     *
+     * Each entry records the price and cost of a single position entry.
+     * The first element is always the original priceOpen (initial entry).
+     * Each subsequent element is an entry added by averageBuy().
+     *
+     * Returns null if no pending signal exists.
+     * Returns a single-element array [{ price: priceOpen, cost }] if no DCA entries were made.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to array of entry records or null
+     *
+     * @example
+     * // No DCA: [{ price: 43000, cost: 100 }]
+     * // One DCA: [{ price: 43000, cost: 100 }, { price: 42000, cost: 100 }]
+     */
+    async getPositionEntries(symbol) {
+        this.params.logger.debug("ClientStrategy getPositionEntries", { symbol });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        const entries = this._pendingSignal._entry;
+        if (!entries || entries.length === 0) {
+            return [{ price: this._pendingSignal.priceOpen, cost: GLOBAL_CONFIG.CC_POSITION_ENTRY_COST }];
+        }
+        return entries.map(({ price, cost }) => ({ price, cost }));
+    }
     /**
      * Performs a single tick of strategy execution.
      *
@@ -7408,10 +7456,12 @@ class ClientStrategy {
         if (typeof currentPrice !== "number" || !isFinite(currentPrice) || currentPrice <= 0)
             return false;
         const effectivePriceOpen = getEffectivePriceOpen(this._pendingSignal);
-        if (this._pendingSignal.position === "long" && currentPrice <= effectivePriceOpen)
-            return false;
-        if (this._pendingSignal.position === "short" && currentPrice >= effectivePriceOpen)
-            return false;
+        if (!GLOBAL_CONFIG.CC_ENABLE_PPPL_EVERYWHERE) {
+            if (this._pendingSignal.position === "long" && currentPrice <= effectivePriceOpen)
+                return false;
+            if (this._pendingSignal.position === "short" && currentPrice >= effectivePriceOpen)
+                return false;
+        }
         const effectiveTakeProfit = this._pendingSignal._trailingPriceTakeProfit ?? this._pendingSignal.priceTakeProfit;
         if (this._pendingSignal.position === "long" && currentPrice >= effectiveTakeProfit)
             return false;
@@ -7495,7 +7545,7 @@ class ClientStrategy {
             throw new Error(`ClientStrategy partialProfit: currentPrice must be a positive finite number, got ${currentPrice}`);
         }
         // Validation: currentPrice must be moving toward TP (profit direction)
-        {
+        if (!GLOBAL_CONFIG.CC_ENABLE_PPPL_EVERYWHERE) {
             const effectivePriceOpen = getEffectivePriceOpen(this._pendingSignal);
             if (this._pendingSignal.position === "long") {
                 // For LONG: currentPrice must be higher than effectivePriceOpen (moving toward TP)
@@ -7589,10 +7639,12 @@ class ClientStrategy {
         if (typeof currentPrice !== "number" || !isFinite(currentPrice) || currentPrice <= 0)
             return false;
         const effectivePriceOpen = getEffectivePriceOpen(this._pendingSignal);
-        if (this._pendingSignal.position === "long" && currentPrice >= effectivePriceOpen)
-            return false;
-        if (this._pendingSignal.position === "short" && currentPrice <= effectivePriceOpen)
-            return false;
+        if (!GLOBAL_CONFIG.CC_ENABLE_PPPL_EVERYWHERE) {
+            if (this._pendingSignal.position === "long" && currentPrice >= effectivePriceOpen)
+                return false;
+            if (this._pendingSignal.position === "short" && currentPrice <= effectivePriceOpen)
+                return false;
+        }
         const effectiveStopLoss = this._pendingSignal._trailingPriceStopLoss ?? this._pendingSignal.priceStopLoss;
         if (this._pendingSignal.position === "long" && currentPrice <= effectiveStopLoss)
             return false;
@@ -7676,7 +7728,7 @@ class ClientStrategy {
             throw new Error(`ClientStrategy partialLoss: currentPrice must be a positive finite number, got ${currentPrice}`);
         }
         // Validation: currentPrice must be moving toward SL (loss direction)
-        {
+        if (!GLOBAL_CONFIG.CC_ENABLE_PPPL_EVERYWHERE) {
             const effectivePriceOpen = getEffectivePriceOpen(this._pendingSignal);
             if (this._pendingSignal.position === "long") {
                 // For LONG: currentPrice must be lower than effectivePriceOpen (moving toward SL)
@@ -9291,6 +9343,15 @@ class StrategyConnectionService {
             const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
             return await strategy.getPositionPartials(symbol);
         };
+        this.getPositionEntries = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getPositionEntries", {
+                symbol,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionEntries(symbol);
+        };
         /**
          * Retrieves the currently active scheduled signal for the strategy.
          * If no scheduled signal exists, returns null.
@@ -10815,7 +10876,6 @@ const METHOD_NAME_PARTIAL_LOSS_AVAILABLE = "ActionBase.partialLossAvailable";
 const METHOD_NAME_PING_SCHEDULED = "ActionBase.pingScheduled";
 const METHOD_NAME_PING_ACTIVE = "ActionBase.pingActive";
 const METHOD_NAME_RISK_REJECTION = "ActionBase.riskRejection";
-const METHOD_NAME_SIGNAL_SYNC = "ActionBase.signalSync";
 const METHOD_NAME_DISPOSE = "ActionBase.dispose";
 const DEFAULT_SOURCE = "default";
 /**
@@ -11227,6 +11287,11 @@ class ActionProxy {
      */
     async signalSync(event) {
         if (this._target.signalSync) {
+            console.error("Action::signalSync is unwanted cause exchange integration should be implemented in Broker.useBrokerAdapter as an infrastructure domain layer");
+            console.error("If you need to implement custom logic on signal open/close, please use signal(), signalBacktest(), signalLive()");
+            console.error("If Action::signalSync throws the exchange will not execute the order!");
+            console.error("");
+            console.error("You have been warned!");
             await this._target.signalSync(event);
         }
     }
@@ -11689,19 +11754,6 @@ class ActionBase {
             source,
         });
     }
-    /**
-     * Gate for position open/close via limit order. Default allows all.
-     * Throw to reject — framework retries next tick.
-     *
-     * NOTE: Exceptions are NOT swallowed — they propagate to CREATE_SYNC_FN.
-     *
-     * @param event - Sync event with action "signal-open" or "signal-close"
-     */
-    signalSync(_event, source = DEFAULT_SOURCE) {
-        bt.loggerService.info(METHOD_NAME_SIGNAL_SYNC, {
-            source,
-        });
-    }
     /**
      * Cleans up resources and subscriptions when action handler is disposed.
      *
@@ -12980,6 +13032,14 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionPartials(backtest, symbol, context);
         };
+        this.getPositionEntries = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getPositionEntries", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionEntries(backtest, symbol, context);
+        };
         /**
          * Retrieves the currently active scheduled signal for the symbol.
          * If no scheduled signal exists, returns null.
@@ -31724,6 +31784,11 @@ BrokerBase = functoolsKit.makeExtendable(BrokerBase);
  */
 const Broker = new BrokerAdapter();
 
+const POSITION_OVERLAP_LADDER_DEFAULT = {
+    upperPercent: 1.5,
+    lowerPercent: 1.5,
+};
+
 const CANCEL_SCHEDULED_METHOD_NAME = "strategy.commitCancelScheduled";
 const CLOSE_PENDING_METHOD_NAME = "strategy.commitClosePending";
 const PARTIAL_PROFIT_METHOD_NAME = "strategy.commitPartialProfit";
@@ -31749,6 +31814,8 @@ const GET_POSITION_PNL_PERCENT_METHOD_NAME = "strategy.getPositionPnlPercent";
 const GET_POSITION_PNL_COST_METHOD_NAME = "strategy.getPositionPnlCost";
 const GET_POSITION_LEVELS_METHOD_NAME = "strategy.getPositionLevels";
 const GET_POSITION_PARTIALS_METHOD_NAME = "strategy.getPositionPartials";
+const GET_POSITION_ENTRY_OVERLAP_METHOD_NAME = "strategy.getPositionEntryOverlap";
+const GET_POSITION_PARTIAL_OVERLAP_METHOD_NAME = "strategy.getPositionPartialOverlap";
 /**
  * Cancels the scheduled signal without stopping the strategy.
  *
@@ -32025,6 +32092,7 @@ async function commitTrailingStop(symbol, percentShift, currentPrice) {
         percentShift,
         currentPrice,
         newStopLossPrice: slPercentShiftToPrice(percentShift, signal.priceStopLoss, effectivePriceOpen, signal.position),
+        takeProfitPrice: signal.priceTakeProfit,
         position: signal.position,
         context: { exchangeName, frameName, strategyName },
         backtest: isBacktest,
@@ -32104,6 +32172,7 @@ async function commitTrailingTake(symbol, percentShift, currentPrice) {
         percentShift,
         currentPrice,
         newTakeProfitPrice: tpPercentShiftToPrice(percentShift, signal.priceTakeProfit, effectivePriceOpen, signal.position),
+        takeProfitPrice: signal.priceTakeProfit,
         position: signal.position,
         context: { exchangeName, frameName, strategyName },
         backtest: isBacktest,
@@ -32155,6 +32224,7 @@ async function commitTrailingStopCost(symbol, newStopLossPrice) {
         currentPrice,
         newStopLossPrice,
         position: signal.position,
+        takeProfitPrice: signal.priceTakeProfit,
         context: { exchangeName, frameName, strategyName },
         backtest: isBacktest,
     });
@@ -32204,6 +32274,7 @@ async function commitTrailingTakeCost(symbol, newTakeProfitPrice) {
         percentShift,
         currentPrice,
         newTakeProfitPrice,
+        takeProfitPrice: signal.priceTakeProfit,
         position: signal.position,
         context: { exchangeName, frameName, strategyName },
         backtest: isBacktest,
@@ -32530,6 +32601,31 @@ async function getBreakeven(symbol, currentPrice) {
     const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
     return await bt.strategyCoreService.getBreakeven(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName });
 }
+/**
+ * Returns the effective (DCA-weighted) entry price for the current pending signal.
+ *
+ * Uses cost-weighted harmonic mean: Σcost / Σ(cost/price).
+ * When partial closes exist, the price is computed iteratively using
+ * costBasisAtClose snapshots from each partial, then blended with any
+ * DCA entries added after the last partial.
+ * With no DCA entries, equals the original priceOpen.
+ *
+ * Returns null if no pending signal exists.
+ *
+ * Automatically detects backtest/live mode from execution context.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to effective entry price or null
+ *
+ * @example
+ * ```typescript
+ * import { getPositionAveragePrice } from "backtest-kit";
+ *
+ * const avgPrice = await getPositionAveragePrice("BTCUSDT");
+ * // No DCA: avgPrice === priceOpen
+ * // After DCA at lower price: avgPrice < priceOpen
+ * ```
+ */
 async function getPositionAveragePrice(symbol) {
     bt.loggerService.info(GET_POSITION_AVERAGE_PRICE_METHOD_NAME, {
         symbol,
@@ -32544,6 +32640,28 @@ async function getPositionAveragePrice(symbol) {
     const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
     return await bt.strategyCoreService.getPositionAveragePrice(isBacktest, symbol, { exchangeName, frameName, strategyName });
 }
+/**
+ * Returns the number of DCA entries made for the current pending signal.
+ *
+ * 1 = original entry only (no DCA).
+ * Increases by 1 with each successful commitAverageBuy().
+ *
+ * Returns null if no pending signal exists.
+ *
+ * Automatically detects backtest/live mode from execution context.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to entry count or null
+ *
+ * @example
+ * ```typescript
+ * import { getPositionInvestedCount } from "backtest-kit";
+ *
+ * const count = await getPositionInvestedCount("BTCUSDT");
+ * // No DCA: count === 1
+ * // After one DCA: count === 2
+ * ```
+ */
 async function getPositionInvestedCount(symbol) {
     bt.loggerService.info(GET_POSITION_INVESTED_COUNT_METHOD_NAME, {
         symbol,
@@ -32558,6 +32676,28 @@ async function getPositionInvestedCount(symbol) {
     const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
     return await bt.strategyCoreService.getPositionInvestedCount(isBacktest, symbol, { exchangeName, frameName, strategyName });
 }
+/**
+ * Returns the total invested cost basis in dollars for the current pending signal.
+ *
+ * Equal to the sum of all _entry costs (Σ entry.cost).
+ * Each entry cost is set at the time of commitAverageBuy (defaults to CC_POSITION_ENTRY_COST).
+ *
+ * Returns null if no pending signal exists.
+ *
+ * Automatically detects backtest/live mode from execution context.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to total invested cost in dollars or null
+ *
+ * @example
+ * ```typescript
+ * import { getPositionInvestedCost } from "backtest-kit";
+ *
+ * const cost = await getPositionInvestedCost("BTCUSDT");
+ * // No DCA, default cost: cost === 100
+ * // After one DCA with default cost: cost === 200
+ * ```
+ */
 async function getPositionInvestedCost(symbol) {
     bt.loggerService.info(GET_POSITION_INVESTED_COST_METHOD_NAME, {
         symbol,
@@ -32572,6 +32712,29 @@ async function getPositionInvestedCost(symbol) {
     const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
     return await bt.strategyCoreService.getPositionInvestedCost(isBacktest, symbol, { exchangeName, frameName, strategyName });
 }
+/**
+ * Returns the unrealized PNL percentage for the current pending signal at current market price.
+ *
+ * Accounts for partial closes, DCA entries, slippage and fees
+ * (delegates to toProfitLossDto).
+ *
+ * Returns null if no pending signal exists.
+ *
+ * Automatically detects backtest/live mode from execution context.
+ * Automatically fetches current price via getAveragePrice.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to PNL percentage or null
+ *
+ * @example
+ * ```typescript
+ * import { getPositionPnlPercent } from "backtest-kit";
+ *
+ * const pnlPct = await getPositionPnlPercent("BTCUSDT");
+ * // LONG at 100, current=105: pnlPct ≈ 5
+ * // LONG at 100, current=95: pnlPct ≈ -5
+ * ```
+ */
 async function getPositionPnlPercent(symbol) {
     bt.loggerService.info(GET_POSITION_PNL_PERCENT_METHOD_NAME, { symbol });
     if (!ExecutionContextService.hasContext()) {
@@ -32721,6 +32884,29 @@ async function commitPartialLossCost(symbol, dollarAmount) {
     });
     return await bt.strategyCoreService.partialLoss(isBacktest, symbol, percentToClose, currentPrice, { exchangeName, frameName, strategyName });
 }
+/**
+ * Returns the unrealized PNL in dollars for the current pending signal at current market price.
+ *
+ * Calculated as: pnlPercentage / 100 × totalInvestedCost.
+ * Accounts for partial closes, DCA entries, slippage and fees.
+ *
+ * Returns null if no pending signal exists.
+ *
+ * Automatically detects backtest/live mode from execution context.
+ * Automatically fetches current price via getAveragePrice.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to PNL in dollars or null
+ *
+ * @example
+ * ```typescript
+ * import { getPositionPnlCost } from "backtest-kit";
+ *
+ * const pnlCost = await getPositionPnlCost("BTCUSDT");
+ * // LONG at 100, invested $100, current=105: pnlCost ≈ 5
+ * // LONG at 100, invested $200 (DCA), current=95: pnlCost ≈ -10
+ * ```
+ */
 async function getPositionPnlCost(symbol) {
     bt.loggerService.info(GET_POSITION_PNL_COST_METHOD_NAME, { symbol });
     if (!ExecutionContextService.hasContext()) {
@@ -32807,6 +32993,104 @@ async function getPositionPartials(symbol) {
     const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
     return await bt.strategyCoreService.getPositionPartials(isBacktest, symbol, { exchangeName, frameName, strategyName });
 }
+/**
+ * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
+ * Use this to prevent duplicate DCA entries at the same price area.
+ *
+ * Returns true if currentPrice is within [level - lowerStep, level + upperStep] for any level,
+ * where step = level * percent / 100.
+ * Returns false if no pending signal exists.
+ *
+ * @param symbol - Trading pair symbol
+ * @param currentPrice - Price to check against existing DCA levels
+ * @param ladder - Tolerance zone config; percentages in 0–100 format (default: 1.5% up and down)
+ * @returns Promise<boolean> - true if price overlaps an existing entry level (DCA not recommended)
+ *
+ * @example
+ * ```typescript
+ * import { getPositionEntryOverlap } from "backtest-kit";
+ *
+ * // LONG with levels [43000, 42000], check if 42100 is too close to 42000
+ * const overlap = await getPositionEntryOverlap("BTCUSDT", 42100, { upperPercent: 5, lowerPercent: 5 });
+ * // overlap = true (42100 is within 5% of 42000 = [39900, 44100])
+ * if (!overlap) {
+ *   await commitAverageBuy("BTCUSDT");
+ * }
+ * ```
+ */
+async function getPositionEntryOverlap(symbol, currentPrice, ladder = POSITION_OVERLAP_LADDER_DEFAULT) {
+    bt.loggerService.info(GET_POSITION_ENTRY_OVERLAP_METHOD_NAME, {
+        symbol,
+        currentPrice,
+        ladder,
+    });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionEntryOverlap requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionEntryOverlap requires a method context");
+    }
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    const levels = await bt.strategyCoreService.getPositionLevels(isBacktest, symbol, { exchangeName, frameName, strategyName });
+    if (!levels) {
+        return false;
+    }
+    return levels.some((level) => {
+        const upperStep = (level * ladder.upperPercent) / 100;
+        const lowerStep = (level * ladder.lowerPercent) / 100;
+        return currentPrice >= level - lowerStep && currentPrice <= level + upperStep;
+    });
+}
+/**
+ * Checks whether the current price falls within the tolerance zone of any existing partial close price.
+ * Use this to prevent duplicate partial closes at the same price area.
+ *
+ * Returns true if currentPrice is within [partial.currentPrice - lowerStep, partial.currentPrice + upperStep]
+ * for any partial, where step = partial.currentPrice * percent / 100.
+ * Returns false if no pending signal exists or no partials have been executed yet.
+ *
+ * @param symbol - Trading pair symbol
+ * @param currentPrice - Price to check against existing partial close prices
+ * @param ladder - Tolerance zone config; percentages in 0–100 format (default: 1.5% up and down)
+ * @returns Promise<boolean> - true if price overlaps an existing partial price (partial not recommended)
+ *
+ * @example
+ * ```typescript
+ * import { getPositionPartialOverlap } from "backtest-kit";
+ *
+ * // Partials at [45000], check if 45100 is too close
+ * const overlap = await getPositionPartialOverlap("BTCUSDT", 45100, { upperPercent: 1.5, lowerPercent: 1.5 });
+ * // overlap = true (45100 is within 1.5% of 45000)
+ * if (!overlap) {
+ *   await commitPartialProfit("BTCUSDT", 50);
+ * }
+ * ```
+ */
+async function getPositionPartialOverlap(symbol, currentPrice, ladder = POSITION_OVERLAP_LADDER_DEFAULT) {
+    bt.loggerService.info(GET_POSITION_PARTIAL_OVERLAP_METHOD_NAME, {
+        symbol,
+        currentPrice,
+        ladder,
+    });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionPartialOverlap requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionPartialOverlap requires a method context");
+    }
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    const partials = await bt.strategyCoreService.getPositionPartials(isBacktest, symbol, { exchangeName, frameName, strategyName });
+    if (!partials) {
+        return false;
+    }
+    return partials.some((partial) => {
+        const upperStep = (partial.currentPrice * ladder.upperPercent) / 100;
+        const lowerStep = (partial.currentPrice * ladder.lowerPercent) / 100;
+        return currentPrice >= partial.currentPrice - lowerStep && currentPrice <= partial.currentPrice + upperStep;
+    });
+}
 
 const STOP_STRATEGY_METHOD_NAME = "control.stopStrategy";
 /**
@@ -34032,6 +34316,9 @@ const BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT = "BacktestUtils.getPosition
 const BACKTEST_METHOD_NAME_GET_POSITION_PNL_COST = "BacktestUtils.getPositionPnlCost";
 const BACKTEST_METHOD_NAME_GET_POSITION_LEVELS = "BacktestUtils.getPositionLevels";
 const BACKTEST_METHOD_NAME_GET_POSITION_PARTIALS = "BacktestUtils.getPositionPartials";
+const BACKTEST_METHOD_NAME_GET_POSITION_ENTRIES = "BacktestUtils.getPositionEntries";
+const BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP = "BacktestUtils.getPositionEntryOverlap";
+const BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP = "BacktestUtils.getPositionPartialOverlap";
 const BACKTEST_METHOD_NAME_BREAKEVEN = "Backtest.commitBreakeven";
 const BACKTEST_METHOD_NAME_CANCEL_SCHEDULED = "Backtest.commitCancelScheduled";
 const BACKTEST_METHOD_NAME_CLOSE_PENDING = "Backtest.commitClosePending";
@@ -34787,6 +35074,125 @@ class BacktestUtils {
             }
             return await bt.strategyCoreService.getPositionPartials(true, symbol, context);
         };
+        /**
+         * Returns the list of DCA entry prices and costs for the current pending signal.
+         *
+         * Each element represents a single position entry — the initial open or a subsequent
+         * DCA entry added via commitAverageBuy.
+         *
+         * Returns null if no pending signal exists.
+         * Returns a single-element array if no DCA entries were made.
+         *
+         * Each entry contains:
+         * - `price` — execution price of this entry
+         * - `cost` — dollar cost allocated to this entry (e.g. 100 for $100)
+         *
+         * @param symbol - Trading pair symbol
+         * @param context - Execution context with strategyName, exchangeName, and frameName
+         * @returns Array of entry records, or null if no active position
+         */
+        this.getPositionEntries = async (symbol, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_ENTRIES, {
+                symbol,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRIES);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRIES);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRIES);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRIES));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRIES));
+            }
+            return await bt.strategyCoreService.getPositionEntries(true, symbol, context);
+        };
+        /**
+         * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
+         * Use this to prevent duplicate DCA entries at the same price area.
+         *
+         * Returns true if currentPrice is within [level - lowerStep, level + upperStep] for any level,
+         * where step = level * percent / 100.
+         * Returns false if no pending signal exists.
+         *
+         * @param symbol - Trading pair symbol
+         * @param currentPrice - Price to check against existing DCA levels
+         * @param context - Execution context with strategyName, exchangeName, and frameName
+         * @param ladder - Tolerance zone config; percentages in 0–100 format (default: 1.5% up and down)
+         * @returns true if price overlaps an existing entry level (DCA not recommended)
+         */
+        this.getPositionEntryOverlap = async (symbol, currentPrice, context, ladder = POSITION_OVERLAP_LADDER_DEFAULT) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP, {
+                symbol,
+                currentPrice,
+                context,
+                ladder,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP));
+            }
+            const levels = await bt.strategyCoreService.getPositionLevels(true, symbol, context);
+            if (!levels) {
+                return false;
+            }
+            return levels.some((level) => {
+                const upperStep = (level * ladder.upperPercent) / 100;
+                const lowerStep = (level * ladder.lowerPercent) / 100;
+                return currentPrice >= level - lowerStep && currentPrice <= level + upperStep;
+            });
+        };
+        /**
+         * Checks whether the current price falls within the tolerance zone of any existing partial close price.
+         * Use this to prevent duplicate partial closes at the same price area.
+         *
+         * Returns true if currentPrice is within [partial.currentPrice - lowerStep, partial.currentPrice + upperStep]
+         * for any partial, where step = partial.currentPrice * percent / 100.
+         * Returns false if no pending signal exists or no partials have been executed yet.
+         *
+         * @param symbol - Trading pair symbol
+         * @param currentPrice - Price to check against existing partial close prices
+         * @param context - Execution context with strategyName, exchangeName, and frameName
+         * @param ladder - Tolerance zone config; percentages in 0–100 format (default: 1.5% up and down)
+         * @returns true if price overlaps an existing partial price (partial not recommended)
+         */
+        this.getPositionPartialOverlap = async (symbol, currentPrice, context, ladder = POSITION_OVERLAP_LADDER_DEFAULT) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP, {
+                symbol,
+                currentPrice,
+                context,
+                ladder,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP));
+            }
+            const partials = await bt.strategyCoreService.getPositionPartials(true, symbol, context);
+            if (!partials) {
+                return false;
+            }
+            return partials.some((partial) => {
+                const upperStep = (partial.currentPrice * ladder.upperPercent) / 100;
+                const lowerStep = (partial.currentPrice * ladder.lowerPercent) / 100;
+                return currentPrice >= partial.currentPrice - lowerStep && currentPrice <= partial.currentPrice + upperStep;
+            });
+        };
         /**
          * Stops the strategy from generating new signals.
          *
@@ -35276,6 +35682,7 @@ class BacktestUtils {
                 percentShift,
                 currentPrice,
                 newStopLossPrice: slPercentShiftToPrice(percentShift, signal.priceStopLoss, effectivePriceOpen, signal.position),
+                takeProfitPrice: signal.priceTakeProfit,
                 position: signal.position,
                 context,
                 backtest: true,
@@ -35360,6 +35767,7 @@ class BacktestUtils {
                 percentShift,
                 currentPrice,
                 newTakeProfitPrice: tpPercentShiftToPrice(percentShift, signal.priceTakeProfit, effectivePriceOpen, signal.position),
+                takeProfitPrice: signal.priceTakeProfit,
                 position: signal.position,
                 context,
                 backtest: true,
@@ -35414,6 +35822,7 @@ class BacktestUtils {
                 currentPrice,
                 newStopLossPrice,
                 position: signal.position,
+                takeProfitPrice: signal.priceTakeProfit,
                 context,
                 backtest: true,
             });
@@ -35467,6 +35876,7 @@ class BacktestUtils {
                 currentPrice,
                 newTakeProfitPrice,
                 position: signal.position,
+                takeProfitPrice: signal.priceTakeProfit,
                 context,
                 backtest: true,
             });
@@ -35809,6 +36219,9 @@ const LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT = "LiveUtils.getPositionPnlPerce
 const LIVE_METHOD_NAME_GET_POSITION_PNL_COST = "LiveUtils.getPositionPnlCost";
 const LIVE_METHOD_NAME_GET_POSITION_LEVELS = "LiveUtils.getPositionLevels";
 const LIVE_METHOD_NAME_GET_POSITION_PARTIALS = "LiveUtils.getPositionPartials";
+const LIVE_METHOD_NAME_GET_POSITION_ENTRIES = "LiveUtils.getPositionEntries";
+const LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP = "LiveUtils.getPositionEntryOverlap";
+const LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP = "LiveUtils.getPositionPartialOverlap";
 const LIVE_METHOD_NAME_BREAKEVEN = "Live.commitBreakeven";
 const LIVE_METHOD_NAME_CANCEL_SCHEDULED = "Live.cancelScheduled";
 const LIVE_METHOD_NAME_CLOSE_PENDING = "Live.closePending";
@@ -36623,6 +37036,137 @@ class LiveUtils {
                 frameName: "",
             });
         };
+        /**
+         * Returns the list of DCA entry prices and costs for the current pending signal.
+         *
+         * Each element represents a single position entry — the initial open or a subsequent
+         * DCA entry added via commitAverageBuy.
+         *
+         * Returns null if no pending signal exists.
+         * Returns a single-element array if no DCA entries were made.
+         *
+         * Each entry contains:
+         * - `price` — execution price of this entry
+         * - `cost` — dollar cost allocated to this entry (e.g. 100 for $100)
+         *
+         * @param symbol - Trading pair symbol
+         * @param context - Execution context with strategyName and exchangeName
+         * @returns Array of entry records, or null if no active position
+         */
+        this.getPositionEntries = async (symbol, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_ENTRIES, {
+                symbol,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_ENTRIES);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_ENTRIES);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_ENTRIES);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_ENTRIES));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_ENTRIES));
+            }
+            return await bt.strategyCoreService.getPositionEntries(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        /**
+         * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
+         * Use this to prevent duplicate DCA entries at the same price area.
+         *
+         * Returns true if currentPrice is within [level - lowerStep, level + upperStep] for any level,
+         * where step = level * percent / 100.
+         * Returns false if no pending signal exists.
+         *
+         * @param symbol - Trading pair symbol
+         * @param currentPrice - Price to check against existing DCA levels
+         * @param context - Execution context with strategyName and exchangeName
+         * @param ladder - Tolerance zone config; percentages in 0–100 format (default: 1.5% up and down)
+         * @returns true if price overlaps an existing entry level (DCA not recommended)
+         */
+        this.getPositionEntryOverlap = async (symbol, currentPrice, context, ladder = POSITION_OVERLAP_LADDER_DEFAULT) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP, {
+                symbol,
+                currentPrice,
+                context,
+                ladder,
+            });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP));
+            }
+            const levels = await bt.strategyCoreService.getPositionLevels(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+            if (!levels) {
+                return false;
+            }
+            return levels.some((level) => {
+                const upperStep = (level * ladder.upperPercent) / 100;
+                const lowerStep = (level * ladder.lowerPercent) / 100;
+                return currentPrice >= level - lowerStep && currentPrice <= level + upperStep;
+            });
+        };
+        /**
+         * Checks whether the current price falls within the tolerance zone of any existing partial close price.
+         * Use this to prevent duplicate partial closes at the same price area.
+         *
+         * Returns true if currentPrice is within [partial.currentPrice - lowerStep, partial.currentPrice + upperStep]
+         * for any partial, where step = partial.currentPrice * percent / 100.
+         * Returns false if no pending signal exists or no partials have been executed yet.
+         *
+         * @param symbol - Trading pair symbol
+         * @param currentPrice - Price to check against existing partial close prices
+         * @param context - Execution context with strategyName and exchangeName
+         * @param ladder - Tolerance zone config; percentages in 0–100 format (default: 1.5% up and down)
+         * @returns true if price overlaps an existing partial price (partial not recommended)
+         */
+        this.getPositionPartialOverlap = async (symbol, currentPrice, context, ladder = POSITION_OVERLAP_LADDER_DEFAULT) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP, {
+                symbol,
+                currentPrice,
+                context,
+                ladder,
+            });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP));
+            }
+            const partials = await bt.strategyCoreService.getPositionPartials(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+            if (!partials) {
+                return false;
+            }
+            return partials.some((partial) => {
+                const upperStep = (partial.currentPrice * ladder.upperPercent) / 100;
+                const lowerStep = (partial.currentPrice * ladder.lowerPercent) / 100;
+                return currentPrice >= partial.currentPrice - lowerStep && currentPrice <= partial.currentPrice + upperStep;
+            });
+        };
         /**
          * Stops the strategy from generating new signals.
          *
@@ -37205,6 +37749,7 @@ class LiveUtils {
                 percentShift,
                 currentPrice,
                 newStopLossPrice: slPercentShiftToPrice(percentShift, signal.priceStopLoss, effectivePriceOpen, signal.position),
+                takeProfitPrice: signal.priceTakeProfit,
                 position: signal.position,
                 context,
                 backtest: false,
@@ -37304,6 +37849,7 @@ class LiveUtils {
                 percentShift,
                 currentPrice,
                 newTakeProfitPrice: tpPercentShiftToPrice(percentShift, signal.priceTakeProfit, effectivePriceOpen, signal.position),
+                takeProfitPrice: signal.priceTakeProfit,
                 position: signal.position,
                 context,
                 backtest: false,
@@ -37373,6 +37919,7 @@ class LiveUtils {
                 percentShift,
                 currentPrice,
                 newStopLossPrice,
+                takeProfitPrice: signal.priceTakeProfit,
                 position: signal.position,
                 context,
                 backtest: false,
@@ -37442,6 +37989,7 @@ class LiveUtils {
                 percentShift,
                 currentPrice,
                 newTakeProfitPrice,
+                takeProfitPrice: signal.priceTakeProfit,
                 position: signal.position,
                 context,
                 backtest: false,
@@ -45442,9 +45990,11 @@ exports.getNextCandles = getNextCandles;
 exports.getOrderBook = getOrderBook;
 exports.getPendingSignal = getPendingSignal;
 exports.getPositionAveragePrice = getPositionAveragePrice;
+exports.getPositionEntryOverlap = getPositionEntryOverlap;
 exports.getPositionInvestedCost = getPositionInvestedCost;
 exports.getPositionInvestedCount = getPositionInvestedCount;
 exports.getPositionLevels = getPositionLevels;
+exports.getPositionPartialOverlap = getPositionPartialOverlap;
 exports.getPositionPartials = getPositionPartials;
 exports.getPositionPnlCost = getPositionPnlCost;
 exports.getPositionPnlPercent = getPositionPnlPercent;