backtest-kit 3.7.1 → 3.8.0

package/build/index.mjs

@@ -3298,8 +3298,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;
@@ -3784,8 +3784,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
@@ -4268,7 +4268,7 @@ const PARTIAL_PROFIT_FN = (self, signal, percentToClose, currentPrice) => {
         type: "profit",
         percent: percentToClose,
         entryCountAtClose,
-        price: currentPrice,
+        currentPrice,
         debugTimestamp: getDebugTimestamp(),
         effectivePrice,
     });
@@ -4307,7 +4307,7 @@ const PARTIAL_LOSS_FN = (self, signal, percentToClose, currentPrice) => {
     signal._partial.push({
         type: "loss",
         percent: percentToClose,
-        price: currentPrice,
+        currentPrice,
         entryCountAtClose,
         effectivePrice,
         debugTimestamp: getDebugTimestamp(),
@@ -6250,6 +6250,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.
      *
@@ -8425,6 +8556,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.
@@ -11863,6 +12059,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.
@@ -28885,10 +29139,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";
@@ -28899,6 +29171,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.
  *
@@ -29457,6 +29736,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";
 /**
@@ -30648,11 +31126,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";
@@ -31189,6 +31676,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.
          *
@@ -31410,6 +32025,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.
          *
@@ -31831,11 +32554,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";
@@ -32344,6 +33076,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.
          *
@@ -32562,6 +33406,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.
          *
@@ -40082,4 +41032,25 @@ const set = (object, path, value) => {
     }
 };
 
-export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getBreakeven, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getEffectivePriceOpen, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getPendingSignal, getRawCandles, getRiskSchema, getScheduledSignal, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, getTotalClosed, getTotalCostClosed, getTotalPercentClosed, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, shutdown, stopStrategy, toProfitLossDto, validate, waitForCandle, warmCandles };
+/**
+ * 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;
+};
+
+export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialLossCost, commitPartialProfit, commitPartialProfitCost, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getBreakeven, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getEffectivePriceOpen, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getPendingSignal, getPositionAveragePrice, getPositionInvestedCost, getPositionInvestedCount, getPositionLevels, getPositionPartials, getPositionPnlCost, getPositionPnlPercent, getRawCandles, getRiskSchema, getScheduledSignal, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, getTotalClosed, getTotalCostClosed, getTotalPercentClosed, getWalkerSchema, hasTradeContext, investedCostToPercent, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, percentDiff, percentValue, roundTicks, set, setColumns, setConfig, setLogger, shutdown, stopStrategy, toProfitLossDto, validate, waitForCandle, warmCandles };