backtest-kit 3.7.1 → 3.8.0

package/build/index.cjs

@@ -3318,8 +3318,8 @@ const toProfitLossDto = (signal, priceClose) => {
                 ? partial.effectivePrice * (1 + GLOBAL_CONFIG.CC_PERCENT_SLIPPAGE / 100)
                 : partial.effectivePrice * (1 - GLOBAL_CONFIG.CC_PERCENT_SLIPPAGE / 100);
             const priceCloseWithSlippage = signal.position === "long"
-                ? partial.price * (1 - GLOBAL_CONFIG.CC_PERCENT_SLIPPAGE / 100)
-                : partial.price * (1 + GLOBAL_CONFIG.CC_PERCENT_SLIPPAGE / 100);
+                ? partial.currentPrice * (1 - GLOBAL_CONFIG.CC_PERCENT_SLIPPAGE / 100)
+                : partial.currentPrice * (1 + GLOBAL_CONFIG.CC_PERCENT_SLIPPAGE / 100);
             const partialPnl = signal.position === "long"
                 ? ((priceCloseWithSlippage - priceOpenWithSlippage) / priceOpenWithSlippage) * 100
                 : ((priceOpenWithSlippage - priceCloseWithSlippage) / priceOpenWithSlippage) * 100;
@@ -3804,8 +3804,8 @@ const PROCESS_COMMIT_QUEUE_FN = async (self, timestamp) => {
 const TO_PUBLIC_SIGNAL = (signal) => {
     const hasTrailingSL = "_trailingPriceStopLoss" in signal && signal._trailingPriceStopLoss !== undefined;
     const hasTrailingTP = "_trailingPriceTakeProfit" in signal && signal._trailingPriceTakeProfit !== undefined;
-    const partialExecuted = ("_partial" in signal && Array.isArray(signal._partial))
-        ? signal._partial.reduce((sum, partial) => sum + partial.percent, 0)
+    const partialExecuted = "_partial" in signal
+        ? getTotalClosed(signal).totalClosedPercent
         : 0;
     const totalEntries = ("_entry" in signal && Array.isArray(signal._entry))
         ? signal._entry.length
@@ -4288,7 +4288,7 @@ const PARTIAL_PROFIT_FN = (self, signal, percentToClose, currentPrice) => {
         type: "profit",
         percent: percentToClose,
         entryCountAtClose,
-        price: currentPrice,
+        currentPrice,
         debugTimestamp: getDebugTimestamp(),
         effectivePrice,
     });
@@ -4327,7 +4327,7 @@ const PARTIAL_LOSS_FN = (self, signal, percentToClose, currentPrice) => {
     signal._partial.push({
         type: "loss",
         percent: percentToClose,
-        price: currentPrice,
+        currentPrice,
         entryCountAtClose,
         effectivePrice,
         debugTimestamp: getDebugTimestamp(),
@@ -6270,6 +6270,137 @@ class ClientStrategy {
         const { remainingCostBasis } = getTotalClosed(this._pendingSignal);
         return remainingCostBasis;
     }
+    /**
+     * Returns the effective (DCA-averaged) entry price for the current pending signal.
+     *
+     * This is the harmonic mean of all _entry prices, which is the correct
+     * cost-basis price used in all PNL calculations.
+     * With no DCA entries, equals the original priceOpen.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to effective entry price or null
+     */
+    async getPositionAveragePrice(symbol) {
+        this.params.logger.debug("ClientStrategy getPositionAveragePrice", { symbol });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        return getEffectivePriceOpen(this._pendingSignal);
+    }
+    /**
+     * 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.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to entry count or null
+     */
+    async getPositionInvestedCount(symbol) {
+        this.params.logger.debug("ClientStrategy getPositionInvestedCount", { symbol });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        return this._pendingSignal._entry?.length ?? 1;
+    }
+    /**
+     * Returns the total invested cost basis in dollars for the current pending signal.
+     *
+     * Equal to entryCount × $100 (COST_BASIS_PER_ENTRY).
+     * 1 entry = $100, 2 entries = $200, etc.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to total invested cost in dollars or null
+     */
+    async getPositionInvestedCost(symbol) {
+        this.params.logger.debug("ClientStrategy getPositionInvestedCost", { symbol });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        return (this._pendingSignal._entry?.length ?? 1) * COST_BASIS_PER_ENTRY;
+    }
+    /**
+     * Returns the unrealized PNL percentage for the current pending signal at currentPrice.
+     *
+     * Accounts for partial closes, DCA entries, slippage and fees
+     * (delegates to toProfitLossDto).
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @returns Promise resolving to pnlPercentage or null
+     */
+    async getPositionPnlPercent(symbol, currentPrice) {
+        this.params.logger.debug("ClientStrategy getPositionPnlPercent", { symbol, currentPrice });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        const pnl = toProfitLossDto(this._pendingSignal, currentPrice);
+        return pnl.pnlPercentage;
+    }
+    /**
+     * Returns the unrealized PNL in dollars for the current pending signal at currentPrice.
+     *
+     * Calculated as: pnlPercentage / 100 × totalInvestedCost
+     * Accounts for partial closes, DCA entries, slippage and fees.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @returns Promise resolving to pnl in dollars or null
+     */
+    async getPositionPnlCost(symbol, currentPrice) {
+        this.params.logger.debug("ClientStrategy getPositionPnlCost", { symbol, currentPrice });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        const totalInvested = (this._pendingSignal._entry?.length ?? 1) * COST_BASIS_PER_ENTRY;
+        const pnl = toProfitLossDto(this._pendingSignal, currentPrice);
+        return (pnl.pnlPercentage / 100) * totalInvested;
+    }
+    /**
+     * Returns the list of DCA entry prices for the current pending signal.
+     *
+     * The first element is always the original priceOpen (initial entry).
+     * Each subsequent element is a price added by commitAverageBuy().
+     *
+     * Returns null if no pending signal exists.
+     * Returns a single-element array [priceOpen] if no DCA entries were made.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to array of entry prices or null
+     *
+     * @example
+     * // No DCA: [43000]
+     * // One DCA: [43000, 42000]
+     * // Two DCA: [43000, 42000, 41500]
+     */
+    async getPositionLevels(symbol) {
+        this.params.logger.debug("ClientStrategy getPositionLevels", { symbol });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        const entries = this._pendingSignal._entry;
+        if (!entries || entries.length === 0) {
+            return [this._pendingSignal.priceOpen];
+        }
+        return entries.map((e) => e.price);
+    }
+    async getPositionPartials(symbol) {
+        this.params.logger.debug("ClientStrategy getPositionPartials", { symbol });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        return this._pendingSignal._partial ?? [];
+    }
     /**
      * Performs a single tick of strategy execution.
      *
@@ -8445,6 +8576,71 @@ class StrategyConnectionService {
             const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
             return await strategy.getTotalCostClosed(symbol);
         };
+        this.getPositionAveragePrice = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getPositionAveragePrice", {
+                symbol,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionAveragePrice(symbol);
+        };
+        this.getPositionInvestedCount = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getPositionInvestedCount", {
+                symbol,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionInvestedCount(symbol);
+        };
+        this.getPositionInvestedCost = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getPositionInvestedCost", {
+                symbol,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionInvestedCost(symbol);
+        };
+        this.getPositionPnlPercent = async (backtest, symbol, currentPrice, context) => {
+            this.loggerService.log("strategyConnectionService getPositionPnlPercent", {
+                symbol,
+                currentPrice,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionPnlPercent(symbol, currentPrice);
+        };
+        this.getPositionPnlCost = async (backtest, symbol, currentPrice, context) => {
+            this.loggerService.log("strategyConnectionService getPositionPnlCost", {
+                symbol,
+                currentPrice,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionPnlCost(symbol, currentPrice);
+        };
+        this.getPositionLevels = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getPositionLevels", {
+                symbol,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionLevels(symbol);
+        };
+        this.getPositionPartials = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getPositionPartials", {
+                symbol,
+                context,
+                backtest,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            return await strategy.getPositionPartials(symbol);
+        };
         /**
          * Retrieves the currently active scheduled signal for the strategy.
          * If no scheduled signal exists, returns null.
@@ -11883,6 +12079,64 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getTotalCostClosed(backtest, symbol, context);
         };
+        this.getPositionAveragePrice = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getPositionAveragePrice", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionAveragePrice(backtest, symbol, context);
+        };
+        this.getPositionInvestedCount = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getPositionInvestedCount", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionInvestedCount(backtest, symbol, context);
+        };
+        this.getPositionInvestedCost = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getPositionInvestedCost", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionInvestedCost(backtest, symbol, context);
+        };
+        this.getPositionPnlPercent = async (backtest, symbol, currentPrice, context) => {
+            this.loggerService.log("strategyCoreService getPositionPnlPercent", {
+                symbol,
+                currentPrice,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionPnlPercent(backtest, symbol, currentPrice, context);
+        };
+        this.getPositionPnlCost = async (backtest, symbol, currentPrice, context) => {
+            this.loggerService.log("strategyCoreService getPositionPnlCost", {
+                symbol,
+                currentPrice,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionPnlCost(backtest, symbol, currentPrice, context);
+        };
+        this.getPositionLevels = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getPositionLevels", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionLevels(backtest, symbol, context);
+        };
+        this.getPositionPartials = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getPositionPartials", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getPositionPartials(backtest, symbol, context);
+        };
         /**
          * Retrieves the currently active scheduled signal for the symbol.
          * If no scheduled signal exists, returns null.
@@ -28905,10 +29159,28 @@ async function getAggregatedTrades(symbol, limit) {
     return await bt.exchangeConnectionService.getAggregatedTrades(symbol, limit);
 }
 
+/**
+ * Convert an absolute dollar amount to a percentage of the invested position cost.
+ * Use the result as the `percent` argument to `commitPartialProfit` / `commitPartialLoss`.
+ *
+ * @param dollarAmount - Dollar value to close (e.g. 150)
+ * @param investedCost - Total invested cost from `getPositionInvestedCost` (e.g. 300)
+ * @returns Percentage of the position to close (0–100)
+ *
+ * @example
+ * const percent = investedCostToPercent(150, 300); // 50
+ * await commitPartialProfit("BTCUSDT", percent);
+ */
+const investedCostToPercent = (dollarAmount, investedCost) => {
+    return (dollarAmount / investedCost) * 100;
+};
+
 const CANCEL_SCHEDULED_METHOD_NAME = "strategy.commitCancelScheduled";
 const CLOSE_PENDING_METHOD_NAME = "strategy.commitClosePending";
 const PARTIAL_PROFIT_METHOD_NAME = "strategy.commitPartialProfit";
 const PARTIAL_LOSS_METHOD_NAME = "strategy.commitPartialLoss";
+const PARTIAL_PROFIT_COST_METHOD_NAME = "strategy.commitPartialProfitCost";
+const PARTIAL_LOSS_COST_METHOD_NAME = "strategy.commitPartialLossCost";
 const TRAILING_STOP_METHOD_NAME = "strategy.commitTrailingStop";
 const TRAILING_PROFIT_METHOD_NAME = "strategy.commitTrailingTake";
 const BREAKEVEN_METHOD_NAME = "strategy.commitBreakeven";
@@ -28919,6 +29191,13 @@ const GET_TOTAL_COST_CLOSED_METHOD_NAME = "strategy.getTotalCostClosed";
 const GET_PENDING_SIGNAL_METHOD_NAME = "strategy.getPendingSignal";
 const GET_SCHEDULED_SIGNAL_METHOD_NAME = "strategy.getScheduledSignal";
 const GET_BREAKEVEN_METHOD_NAME = "strategy.getBreakeven";
+const GET_POSITION_AVERAGE_PRICE_METHOD_NAME = "strategy.getPositionAveragePrice";
+const GET_POSITION_INVESTED_COUNT_METHOD_NAME = "strategy.getPositionInvestedCount";
+const GET_POSITION_INVESTED_COST_METHOD_NAME = "strategy.getPositionInvestedCost";
+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";
 /**
  * Cancels the scheduled signal without stopping the strategy.
  *
@@ -29477,6 +29756,205 @@ async function getBreakeven(symbol, currentPrice) {
     const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
     return await bt.strategyCoreService.getBreakeven(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName });
 }
+async function getPositionAveragePrice(symbol) {
+    bt.loggerService.info(GET_POSITION_AVERAGE_PRICE_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionAveragePrice requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionAveragePrice requires a method context");
+    }
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    return await bt.strategyCoreService.getPositionAveragePrice(isBacktest, symbol, { exchangeName, frameName, strategyName });
+}
+async function getPositionInvestedCount(symbol) {
+    bt.loggerService.info(GET_POSITION_INVESTED_COUNT_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionInvestedCount requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionInvestedCount requires a method context");
+    }
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    return await bt.strategyCoreService.getPositionInvestedCount(isBacktest, symbol, { exchangeName, frameName, strategyName });
+}
+async function getPositionInvestedCost(symbol) {
+    bt.loggerService.info(GET_POSITION_INVESTED_COST_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionInvestedCost requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionInvestedCost requires a method context");
+    }
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    return await bt.strategyCoreService.getPositionInvestedCost(isBacktest, symbol, { exchangeName, frameName, strategyName });
+}
+async function getPositionPnlPercent(symbol) {
+    bt.loggerService.info(GET_POSITION_PNL_PERCENT_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionPnlPercent requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionPnlPercent requires a method context");
+    }
+    const currentPrice = await getAveragePrice(symbol);
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    return await bt.strategyCoreService.getPositionPnlPercent(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName });
+}
+/**
+ * Executes partial close at profit level by absolute dollar amount (moving toward TP).
+ *
+ * Convenience wrapper around commitPartialProfit that converts a dollar amount
+ * to a percentage of the invested position cost automatically.
+ * Price must be moving toward take profit (in profit direction).
+ *
+ * Automatically detects backtest/live mode from execution context.
+ * Automatically fetches current price via getAveragePrice.
+ *
+ * @param symbol - Trading pair symbol
+ * @param dollarAmount - Dollar value of position to close (e.g. 150 closes $150 worth)
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
+ *
+ * @throws Error if currentPrice is not in profit direction:
+ *   - LONG: currentPrice must be > priceOpen
+ *   - SHORT: currentPrice must be < priceOpen
+ *
+ * @example
+ * ```typescript
+ * import { commitPartialProfitCost } from "backtest-kit";
+ *
+ * // Close $150 of a $300 position (50%) at profit
+ * const success = await commitPartialProfitCost("BTCUSDT", 150);
+ * if (success) {
+ *   console.log('Partial profit executed');
+ * }
+ * ```
+ */
+async function commitPartialProfitCost(symbol, dollarAmount) {
+    bt.loggerService.info(PARTIAL_PROFIT_COST_METHOD_NAME, { symbol, dollarAmount });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("commitPartialProfitCost requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("commitPartialProfitCost requires a method context");
+    }
+    const currentPrice = await getAveragePrice(symbol);
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    const investedCost = await bt.strategyCoreService.getPositionInvestedCost(isBacktest, symbol, { exchangeName, frameName, strategyName });
+    if (investedCost === null)
+        return false;
+    const percentToClose = investedCostToPercent(dollarAmount, investedCost);
+    return await bt.strategyCoreService.partialProfit(isBacktest, symbol, percentToClose, currentPrice, { exchangeName, frameName, strategyName });
+}
+/**
+ * Executes partial close at loss level by absolute dollar amount (moving toward SL).
+ *
+ * Convenience wrapper around commitPartialLoss that converts a dollar amount
+ * to a percentage of the invested position cost automatically.
+ * Price must be moving toward stop loss (in loss direction).
+ *
+ * Automatically detects backtest/live mode from execution context.
+ * Automatically fetches current price via getAveragePrice.
+ *
+ * @param symbol - Trading pair symbol
+ * @param dollarAmount - Dollar value of position to close (e.g. 100 closes $100 worth)
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
+ *
+ * @throws Error if currentPrice is not in loss direction:
+ *   - LONG: currentPrice must be < priceOpen
+ *   - SHORT: currentPrice must be > priceOpen
+ *
+ * @example
+ * ```typescript
+ * import { commitPartialLossCost } from "backtest-kit";
+ *
+ * // Close $100 of a $300 position (~33%) at loss
+ * const success = await commitPartialLossCost("BTCUSDT", 100);
+ * if (success) {
+ *   console.log('Partial loss executed');
+ * }
+ * ```
+ */
+async function commitPartialLossCost(symbol, dollarAmount) {
+    bt.loggerService.info(PARTIAL_LOSS_COST_METHOD_NAME, { symbol, dollarAmount });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("commitPartialLossCost requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("commitPartialLossCost requires a method context");
+    }
+    const currentPrice = await getAveragePrice(symbol);
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    const investedCost = await bt.strategyCoreService.getPositionInvestedCost(isBacktest, symbol, { exchangeName, frameName, strategyName });
+    if (investedCost === null)
+        return false;
+    const percentToClose = investedCostToPercent(dollarAmount, investedCost);
+    return await bt.strategyCoreService.partialLoss(isBacktest, symbol, percentToClose, currentPrice, { exchangeName, frameName, strategyName });
+}
+async function getPositionPnlCost(symbol) {
+    bt.loggerService.info(GET_POSITION_PNL_COST_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionPnlCost requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionPnlCost requires a method context");
+    }
+    const currentPrice = await getAveragePrice(symbol);
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    return await bt.strategyCoreService.getPositionPnlCost(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName });
+}
+/**
+ * Returns the list of DCA entry prices for the current pending signal.
+ *
+ * The first element is always the original priceOpen (initial entry).
+ * Each subsequent element is a price added by commitAverageBuy().
+ *
+ * Returns null if no pending signal exists.
+ * Returns a single-element array [priceOpen] if no DCA entries were made.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to array of entry prices or null
+ *
+ * @example
+ * ```typescript
+ * import { getPositionLevels } from "backtest-kit";
+ *
+ * const levels = await getPositionLevels("BTCUSDT");
+ * // No DCA: [43000]
+ * // One DCA: [43000, 42000]
+ * ```
+ */
+async function getPositionLevels(symbol) {
+    bt.loggerService.info(GET_POSITION_LEVELS_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionLevels requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionLevels requires a method context");
+    }
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    return await bt.strategyCoreService.getPositionLevels(isBacktest, symbol, { exchangeName, frameName, strategyName });
+}
+async function getPositionPartials(symbol) {
+    bt.loggerService.info(GET_POSITION_PARTIALS_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getPositionPartials requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getPositionPartials requires a method context");
+    }
+    const { backtest: isBacktest } = bt.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = bt.methodContextService.context;
+    return await bt.strategyCoreService.getPositionPartials(isBacktest, symbol, { exchangeName, frameName, strategyName });
+}
 
 const STOP_STRATEGY_METHOD_NAME = "control.stopStrategy";
 /**
@@ -30668,11 +31146,20 @@ const BACKTEST_METHOD_NAME_GET_TOTAL_PERCENT_CLOSED = "BacktestUtils.getTotalPer
 const BACKTEST_METHOD_NAME_GET_TOTAL_COST_CLOSED = "BacktestUtils.getTotalCostClosed";
 const BACKTEST_METHOD_NAME_GET_SCHEDULED_SIGNAL = "BacktestUtils.getScheduledSignal";
 const BACKTEST_METHOD_NAME_GET_BREAKEVEN = "BacktestUtils.getBreakeven";
+const BACKTEST_METHOD_NAME_GET_POSITION_AVERAGE_PRICE = "BacktestUtils.getPositionAveragePrice";
+const BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COUNT = "BacktestUtils.getPositionInvestedCount";
+const BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COST = "BacktestUtils.getPositionInvestedCost";
+const BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT = "BacktestUtils.getPositionPnlPercent";
+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_BREAKEVEN = "Backtest.commitBreakeven";
 const BACKTEST_METHOD_NAME_CANCEL_SCHEDULED = "Backtest.commitCancelScheduled";
 const BACKTEST_METHOD_NAME_CLOSE_PENDING = "Backtest.commitClosePending";
 const BACKTEST_METHOD_NAME_PARTIAL_PROFIT = "BacktestUtils.commitPartialProfit";
 const BACKTEST_METHOD_NAME_PARTIAL_LOSS = "BacktestUtils.commitPartialLoss";
+const BACKTEST_METHOD_NAME_PARTIAL_PROFIT_COST = "BacktestUtils.commitPartialProfitCost";
+const BACKTEST_METHOD_NAME_PARTIAL_LOSS_COST = "BacktestUtils.commitPartialLossCost";
 const BACKTEST_METHOD_NAME_TRAILING_STOP = "BacktestUtils.commitTrailingStop";
 const BACKTEST_METHOD_NAME_TRAILING_PROFIT = "BacktestUtils.commitTrailingTake";
 const BACKTEST_METHOD_NAME_ACTIVATE_SCHEDULED = "Backtest.commitActivateScheduled";
@@ -31209,6 +31696,134 @@ class BacktestUtils {
             }
             return await bt.strategyCoreService.getBreakeven(true, symbol, currentPrice, context);
         };
+        this.getPositionAveragePrice = async (symbol, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_AVERAGE_PRICE, {
+                symbol,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_AVERAGE_PRICE);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_AVERAGE_PRICE);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_AVERAGE_PRICE);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_AVERAGE_PRICE));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_AVERAGE_PRICE));
+            }
+            return await bt.strategyCoreService.getPositionAveragePrice(true, symbol, context);
+        };
+        this.getPositionInvestedCount = async (symbol, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COUNT, {
+                symbol,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COUNT);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COUNT);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COUNT);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COUNT));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COUNT));
+            }
+            return await bt.strategyCoreService.getPositionInvestedCount(true, symbol, context);
+        };
+        this.getPositionInvestedCost = async (symbol, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COST, {
+                symbol,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COST);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COST));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_INVESTED_COST));
+            }
+            return await bt.strategyCoreService.getPositionInvestedCost(true, symbol, context);
+        };
+        this.getPositionPnlPercent = async (symbol, currentPrice, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT, {
+                symbol,
+                currentPrice,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_PERCENT));
+            }
+            return await bt.strategyCoreService.getPositionPnlPercent(true, symbol, currentPrice, context);
+        };
+        this.getPositionPnlCost = async (symbol, currentPrice, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_PNL_COST, {
+                symbol,
+                currentPrice,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_COST);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_COST));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_PNL_COST));
+            }
+            return await bt.strategyCoreService.getPositionPnlCost(true, symbol, currentPrice, context);
+        };
+        this.getPositionLevels = async (symbol, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_LEVELS, {
+                symbol,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_LEVELS);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_LEVELS);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_LEVELS);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_LEVELS));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_LEVELS));
+            }
+            return await bt.strategyCoreService.getPositionLevels(true, symbol, context);
+        };
+        this.getPositionPartials = async (symbol, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_GET_POSITION_PARTIALS, {
+                symbol,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIALS);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIALS);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIALS);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIALS));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_POSITION_PARTIALS));
+            }
+            return await bt.strategyCoreService.getPositionPartials(true, symbol, context);
+        };
         /**
          * Stops the strategy from generating new signals.
          *
@@ -31430,6 +32045,114 @@ class BacktestUtils {
             }
             return await bt.strategyCoreService.partialLoss(true, symbol, percentToClose, currentPrice, context);
         };
+        /**
+         * Executes partial close at profit level by absolute dollar amount (moving toward TP).
+         *
+         * Convenience wrapper around commitPartialProfit that converts a dollar amount
+         * to a percentage of the invested position cost automatically.
+         * Price must be moving toward take profit (in profit direction).
+         *
+         * @param symbol - Trading pair symbol
+         * @param dollarAmount - Dollar value of position to close (e.g. 150 closes $150 worth)
+         * @param currentPrice - Current market price for this partial close
+         * @param context - Execution context with strategyName, exchangeName, and frameName
+         * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
+         *
+         * @throws Error if currentPrice is not in profit direction:
+         *   - LONG: currentPrice must be > priceOpen
+         *   - SHORT: currentPrice must be < priceOpen
+         *
+         * @example
+         * ```typescript
+         * // Close $150 of a $300 position (50%) at profit
+         * const success = await Backtest.commitPartialProfitCost("BTCUSDT", 150, 45000, {
+         *   exchangeName: "binance",
+         *   frameName: "frame1",
+         *   strategyName: "my-strategy"
+         * });
+         * if (success) {
+         *   console.log('Partial profit executed');
+         * }
+         * ```
+         */
+        this.commitPartialProfitCost = async (symbol, dollarAmount, currentPrice, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_PARTIAL_PROFIT_COST, {
+                symbol,
+                dollarAmount,
+                currentPrice,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_PARTIAL_PROFIT_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_PARTIAL_PROFIT_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_PARTIAL_PROFIT_COST);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_PARTIAL_PROFIT_COST));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_PARTIAL_PROFIT_COST));
+            }
+            const investedCost = await bt.strategyCoreService.getPositionInvestedCost(true, symbol, context);
+            if (investedCost === null)
+                return false;
+            const percentToClose = (dollarAmount / investedCost) * 100;
+            return await bt.strategyCoreService.partialProfit(true, symbol, percentToClose, currentPrice, context);
+        };
+        /**
+         * Executes partial close at loss level by absolute dollar amount (moving toward SL).
+         *
+         * Convenience wrapper around commitPartialLoss that converts a dollar amount
+         * to a percentage of the invested position cost automatically.
+         * Price must be moving toward stop loss (in loss direction).
+         *
+         * @param symbol - Trading pair symbol
+         * @param dollarAmount - Dollar value of position to close (e.g. 100 closes $100 worth)
+         * @param currentPrice - Current market price for this partial close
+         * @param context - Execution context with strategyName, exchangeName, and frameName
+         * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
+         *
+         * @throws Error if currentPrice is not in loss direction:
+         *   - LONG: currentPrice must be < priceOpen
+         *   - SHORT: currentPrice must be > priceOpen
+         *
+         * @example
+         * ```typescript
+         * // Close $100 of a $300 position (~33%) at loss
+         * const success = await Backtest.commitPartialLossCost("BTCUSDT", 100, 38000, {
+         *   exchangeName: "binance",
+         *   frameName: "frame1",
+         *   strategyName: "my-strategy"
+         * });
+         * if (success) {
+         *   console.log('Partial loss executed');
+         * }
+         * ```
+         */
+        this.commitPartialLossCost = async (symbol, dollarAmount, currentPrice, context) => {
+            bt.loggerService.info(BACKTEST_METHOD_NAME_PARTIAL_LOSS_COST, {
+                symbol,
+                dollarAmount,
+                currentPrice,
+                context,
+            });
+            bt.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_PARTIAL_LOSS_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_PARTIAL_LOSS_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_PARTIAL_LOSS_COST);
+                riskList &&
+                    riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_PARTIAL_LOSS_COST));
+                actions &&
+                    actions.forEach((actionName) => bt.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_PARTIAL_LOSS_COST));
+            }
+            const investedCost = await bt.strategyCoreService.getPositionInvestedCost(true, symbol, context);
+            if (investedCost === null)
+                return false;
+            const percentToClose = (dollarAmount / investedCost) * 100;
+            return await bt.strategyCoreService.partialLoss(true, symbol, percentToClose, currentPrice, context);
+        };
         /**
          * Adjusts the trailing stop-loss distance for an active pending signal.
          *
@@ -31851,11 +32574,20 @@ const LIVE_METHOD_NAME_GET_TOTAL_PERCENT_CLOSED = "LiveUtils.getTotalPercentClos
 const LIVE_METHOD_NAME_GET_TOTAL_COST_CLOSED = "LiveUtils.getTotalCostClosed";
 const LIVE_METHOD_NAME_GET_SCHEDULED_SIGNAL = "LiveUtils.getScheduledSignal";
 const LIVE_METHOD_NAME_GET_BREAKEVEN = "LiveUtils.getBreakeven";
+const LIVE_METHOD_NAME_GET_POSITION_AVERAGE_PRICE = "LiveUtils.getPositionAveragePrice";
+const LIVE_METHOD_NAME_GET_POSITION_INVESTED_COUNT = "LiveUtils.getPositionInvestedCount";
+const LIVE_METHOD_NAME_GET_POSITION_INVESTED_COST = "LiveUtils.getPositionInvestedCost";
+const LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT = "LiveUtils.getPositionPnlPercent";
+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_BREAKEVEN = "Live.commitBreakeven";
 const LIVE_METHOD_NAME_CANCEL_SCHEDULED = "Live.cancelScheduled";
 const LIVE_METHOD_NAME_CLOSE_PENDING = "Live.closePending";
 const LIVE_METHOD_NAME_PARTIAL_PROFIT = "LiveUtils.commitPartialProfit";
 const LIVE_METHOD_NAME_PARTIAL_LOSS = "LiveUtils.commitPartialLoss";
+const LIVE_METHOD_NAME_PARTIAL_PROFIT_COST = "LiveUtils.commitPartialProfitCost";
+const LIVE_METHOD_NAME_PARTIAL_LOSS_COST = "LiveUtils.commitPartialLossCost";
 const LIVE_METHOD_NAME_TRAILING_STOP = "LiveUtils.commitTrailingStop";
 const LIVE_METHOD_NAME_TRAILING_PROFIT = "LiveUtils.commitTrailingTake";
 const LIVE_METHOD_NAME_ACTIVATE_SCHEDULED = "Live.commitActivateScheduled";
@@ -32364,6 +33096,118 @@ class LiveUtils {
                 frameName: "",
             });
         };
+        this.getPositionAveragePrice = async (symbol, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_AVERAGE_PRICE, { symbol, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_AVERAGE_PRICE);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_AVERAGE_PRICE);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_AVERAGE_PRICE);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_AVERAGE_PRICE));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_AVERAGE_PRICE));
+            }
+            return await bt.strategyCoreService.getPositionAveragePrice(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        this.getPositionInvestedCount = async (symbol, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_INVESTED_COUNT, { symbol, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COUNT);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COUNT);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COUNT);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COUNT));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COUNT));
+            }
+            return await bt.strategyCoreService.getPositionInvestedCount(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        this.getPositionInvestedCost = async (symbol, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_INVESTED_COST, { symbol, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COST);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COST));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_INVESTED_COST));
+            }
+            return await bt.strategyCoreService.getPositionInvestedCost(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        this.getPositionPnlPercent = async (symbol, currentPrice, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT, { symbol, currentPrice, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_PNL_PERCENT));
+            }
+            return await bt.strategyCoreService.getPositionPnlPercent(false, symbol, currentPrice, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        this.getPositionPnlCost = async (symbol, currentPrice, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_PNL_COST, { symbol, currentPrice, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_PNL_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_PNL_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PNL_COST);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PNL_COST));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_PNL_COST));
+            }
+            return await bt.strategyCoreService.getPositionPnlCost(false, symbol, currentPrice, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        this.getPositionLevels = async (symbol, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_LEVELS, { symbol, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_LEVELS);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_LEVELS);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_LEVELS);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_LEVELS));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_LEVELS));
+            }
+            return await bt.strategyCoreService.getPositionLevels(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        this.getPositionPartials = async (symbol, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_GET_POSITION_PARTIALS, { symbol, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_POSITION_PARTIALS);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_POSITION_PARTIALS);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PARTIALS);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_POSITION_PARTIALS));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_POSITION_PARTIALS));
+            }
+            return await bt.strategyCoreService.getPositionPartials(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
         /**
          * Stops the strategy from generating new signals.
          *
@@ -32582,6 +33426,112 @@ class LiveUtils {
                 frameName: "",
             });
         };
+        /**
+         * Executes partial close at profit level by absolute dollar amount (moving toward TP).
+         *
+         * Convenience wrapper around commitPartialProfit that converts a dollar amount
+         * to a percentage of the invested position cost automatically.
+         * Price must be moving toward take profit (in profit direction).
+         *
+         * @param symbol - Trading pair symbol
+         * @param dollarAmount - Dollar value of position to close (e.g. 150 closes $150 worth)
+         * @param currentPrice - Current market price for this partial close
+         * @param context - Execution context with strategyName and exchangeName
+         * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
+         *
+         * @throws Error if currentPrice is not in profit direction:
+         *   - LONG: currentPrice must be > priceOpen
+         *   - SHORT: currentPrice must be < priceOpen
+         *
+         * @example
+         * ```typescript
+         * // Close $150 of a $300 position (50%) at profit
+         * const success = await Live.commitPartialProfitCost("BTCUSDT", 150, 45000, {
+         *   exchangeName: "binance",
+         *   strategyName: "my-strategy"
+         * });
+         * if (success) {
+         *   console.log('Partial profit executed');
+         * }
+         * ```
+         */
+        this.commitPartialProfitCost = async (symbol, dollarAmount, currentPrice, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_PARTIAL_PROFIT_COST, { symbol, dollarAmount, currentPrice, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_PARTIAL_PROFIT_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_PARTIAL_PROFIT_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_PARTIAL_PROFIT_COST);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_PARTIAL_PROFIT_COST));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_PARTIAL_PROFIT_COST));
+            }
+            const investedCost = await bt.strategyCoreService.getPositionInvestedCost(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+            if (investedCost === null)
+                return false;
+            const percentToClose = (dollarAmount / investedCost) * 100;
+            return await bt.strategyCoreService.partialProfit(false, symbol, percentToClose, currentPrice, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        /**
+         * Executes partial close at loss level by absolute dollar amount (moving toward SL).
+         *
+         * Convenience wrapper around commitPartialLoss that converts a dollar amount
+         * to a percentage of the invested position cost automatically.
+         * Price must be moving toward stop loss (in loss direction).
+         *
+         * @param symbol - Trading pair symbol
+         * @param dollarAmount - Dollar value of position to close (e.g. 100 closes $100 worth)
+         * @param currentPrice - Current market price for this partial close
+         * @param context - Execution context with strategyName and exchangeName
+         * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
+         *
+         * @throws Error if currentPrice is not in loss direction:
+         *   - LONG: currentPrice must be < priceOpen
+         *   - SHORT: currentPrice must be > priceOpen
+         *
+         * @example
+         * ```typescript
+         * // Close $100 of a $300 position (~33%) at loss
+         * const success = await Live.commitPartialLossCost("BTCUSDT", 100, 38000, {
+         *   exchangeName: "binance",
+         *   strategyName: "my-strategy"
+         * });
+         * if (success) {
+         *   console.log('Partial loss executed');
+         * }
+         * ```
+         */
+        this.commitPartialLossCost = async (symbol, dollarAmount, currentPrice, context) => {
+            bt.loggerService.info(LIVE_METHOD_NAME_PARTIAL_LOSS_COST, { symbol, dollarAmount, currentPrice, context });
+            bt.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_PARTIAL_LOSS_COST);
+            bt.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_PARTIAL_LOSS_COST);
+            {
+                const { riskName, riskList, actions } = bt.strategySchemaService.get(context.strategyName);
+                riskName && bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_PARTIAL_LOSS_COST);
+                riskList && riskList.forEach((riskName) => bt.riskValidationService.validate(riskName, LIVE_METHOD_NAME_PARTIAL_LOSS_COST));
+                actions && actions.forEach((actionName) => bt.actionValidationService.validate(actionName, LIVE_METHOD_NAME_PARTIAL_LOSS_COST));
+            }
+            const investedCost = await bt.strategyCoreService.getPositionInvestedCost(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+            if (investedCost === null)
+                return false;
+            const percentToClose = (dollarAmount / investedCost) * 100;
+            return await bt.strategyCoreService.partialLoss(false, symbol, percentToClose, currentPrice, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
         /**
          * Adjusts the trailing stop-loss distance for an active pending signal.
          *
@@ -40102,6 +41052,27 @@ const set = (object, path, value) => {
     }
 };
 
+/**
+ * Calculate the percentage difference between two numbers.
+ * @param {number} a - The first number.
+ * @param {number} b - The second number.
+ * @returns {number} The percentage difference between the two numbers.
+ */
+const percentDiff = (a = 1, b = 2) => {
+    const result = 100 / (Math.min(a, b) / Math.max(a, b)) - 100;
+    return Number.isFinite(result) ? result : 100;
+};
+
+/**
+ * Calculate the percentage change from yesterday's value to today's value.
+ * @param {number} yesterdayValue - The value from yesterday.
+ * @param {number} todayValue - The value from today.
+ * @returns {number} The percentage change from yesterday to today.
+ */
+const percentValue = (yesterdayValue, todayValue) => {
+    return yesterdayValue / todayValue - 1;
+};
+
 exports.ActionBase = ActionBase;
 exports.Backtest = Backtest;
 exports.Breakeven = Breakeven;
@@ -40157,7 +41128,9 @@ exports.commitBreakeven = commitBreakeven;
 exports.commitCancelScheduled = commitCancelScheduled;
 exports.commitClosePending = commitClosePending;
 exports.commitPartialLoss = commitPartialLoss;
+exports.commitPartialLossCost = commitPartialLossCost;
 exports.commitPartialProfit = commitPartialProfit;
+exports.commitPartialProfitCost = commitPartialProfitCost;
 exports.commitTrailingStop = commitTrailingStop;
 exports.commitTrailingTake = commitTrailingTake;
 exports.dumpMessages = dumpMessages;
@@ -40184,6 +41157,13 @@ exports.getMode = getMode;
 exports.getNextCandles = getNextCandles;
 exports.getOrderBook = getOrderBook;
 exports.getPendingSignal = getPendingSignal;
+exports.getPositionAveragePrice = getPositionAveragePrice;
+exports.getPositionInvestedCost = getPositionInvestedCost;
+exports.getPositionInvestedCount = getPositionInvestedCount;
+exports.getPositionLevels = getPositionLevels;
+exports.getPositionPartials = getPositionPartials;
+exports.getPositionPnlCost = getPositionPnlCost;
+exports.getPositionPnlPercent = getPositionPnlPercent;
 exports.getRawCandles = getRawCandles;
 exports.getRiskSchema = getRiskSchema;
 exports.getScheduledSignal = getScheduledSignal;
@@ -40196,6 +41176,7 @@ exports.getTotalCostClosed = getTotalCostClosed;
 exports.getTotalPercentClosed = getTotalPercentClosed;
 exports.getWalkerSchema = getWalkerSchema;
 exports.hasTradeContext = hasTradeContext;
+exports.investedCostToPercent = investedCostToPercent;
 exports.lib = backtest;
 exports.listExchangeSchema = listExchangeSchema;
 exports.listFrameSchema = listFrameSchema;
@@ -40246,6 +41227,8 @@ exports.overrideSizingSchema = overrideSizingSchema;
 exports.overrideStrategySchema = overrideStrategySchema;
 exports.overrideWalkerSchema = overrideWalkerSchema;
 exports.parseArgs = parseArgs;
+exports.percentDiff = percentDiff;
+exports.percentValue = percentValue;
 exports.roundTicks = roundTicks;
 exports.set = set;
 exports.setColumns = setColumns;