backtest-kit 3.7.0 → 3.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/types.d.ts CHANGED
@@ -1958,7 +1958,24 @@ interface ISignalRow extends ISignalDto {
1958
1958
  /** Percentage of position closed (0-100) */
1959
1959
  percent: number;
1960
1960
  /** Price at which this partial was executed */
1961
- price: number;
1961
+ currentPrice: number;
1962
+ /** Debug only timestamp in milliseconds */
1963
+ debugTimestamp?: number;
1964
+ /**
1965
+ * Effective entry price (DCA average) at the moment this partial close was executed.
1966
+ * Captured from GET_EFFECTIVE_PRICE_OPEN at partial close time.
1967
+ * Used in PNL calculation when averageBuy() is called after partial closes,
1968
+ * so each partial's profit is calculated against the correct entry price at that moment.
1969
+ */
1970
+ effectivePrice: number;
1971
+ /**
1972
+ * Entry count (number of entries in _entry history) at the moment this partial close was executed.
1973
+ * Used to determine which entries are included in the effective price calculation for this partial close.
1974
+ * When averageBuy() is called after partial closes, new entries are added to _entry, but they should not affect the effective price used for already executed partial closes.
1975
+ * By capturing entryCountAtClose, we can slice the _entry array to include only the entries that were part of the position at the time of this partial close when calculating the effective price for PNL.
1976
+ * This ensures that each partial close's PNL is calculated against the correct average entry price, even if more averaging happens after the partial close.
1977
+ */
1978
+ entryCountAtClose: number;
1962
1979
  }>;
1963
1980
  /**
1964
1981
  * Trailing stop-loss price that overrides priceStopLoss when set.
@@ -1979,6 +1996,8 @@ interface ISignalRow extends ISignalDto {
1979
1996
  _entry?: Array<{
1980
1997
  /** Price at which this entry was executed */
1981
1998
  price: number;
1999
+ /** Debug only timestamp in milliseconds */
2000
+ debugTimestamp?: number;
1982
2001
  }>;
1983
2002
  /**
1984
2003
  * Trailing take-profit price that overrides priceTakeProfit when set.
@@ -2568,6 +2587,57 @@ interface IStrategy {
2568
2587
  * @returns Promise resolving to true if strategy is stopped, false otherwise
2569
2588
  */
2570
2589
  getStopped: (symbol: string) => Promise<boolean>;
2590
+ /**
2591
+ * Returns how much of the position is still held, as a percentage of totalInvested.
2592
+ *
2593
+ * Uses dollar-basis cost-basis replay (DCA-aware).
2594
+ * 100% means nothing was closed yet. Decreases with each partial close.
2595
+ *
2596
+ * Returns 100 if no pending signal or no partial closes.
2597
+ *
2598
+ * @param symbol - Trading pair symbol
2599
+ * @returns Promise resolving to held percentage (0–100)
2600
+ */
2601
+ getTotalPercentClosed: (symbol: string) => Promise<number | null>;
2602
+ /**
2603
+ * Returns how many dollars of cost basis are still held (not yet closed by partials).
2604
+ *
2605
+ * Full position open: equals totalInvested (entries × $100).
2606
+ * Decreases with each partial close, increases with each averageBuy().
2607
+ *
2608
+ * Returns totalInvested if no pending signal or no partial closes.
2609
+ *
2610
+ * @param symbol - Trading pair symbol
2611
+ * @returns Promise resolving to held cost basis in dollars
2612
+ */
2613
+ getTotalCostClosed: (symbol: string) => Promise<number | null>;
2614
+ /**
2615
+ * Returns the effective (DCA-averaged) entry price for the current pending signal.
2616
+ * Returns null if no pending signal exists.
2617
+ */
2618
+ getPositionAveragePrice: (symbol: string) => Promise<number | null>;
2619
+ /**
2620
+ * Returns the number of DCA entries for the current pending signal.
2621
+ * 1 = original entry only. Returns null if no pending signal exists.
2622
+ */
2623
+ getPositionInvestedCount: (symbol: string) => Promise<number | null>;
2624
+ /**
2625
+ * Returns the total invested cost basis in dollars (entryCount × $100).
2626
+ * Returns null if no pending signal exists.
2627
+ */
2628
+ getPositionInvestedCost: (symbol: string) => Promise<number | null>;
2629
+ /**
2630
+ * Returns the unrealized PNL percentage at currentPrice.
2631
+ * Accounts for partial closes, DCA entries, slippage and fees.
2632
+ * Returns null if no pending signal exists.
2633
+ */
2634
+ getPositionPnlPercent: (symbol: string, currentPrice: number) => Promise<number | null>;
2635
+ /**
2636
+ * Returns the unrealized PNL in dollars at currentPrice.
2637
+ * Calculated as: pnlPercentage / 100 × totalInvestedCost.
2638
+ * Returns null if no pending signal exists.
2639
+ */
2640
+ getPositionPnlCost: (symbol: string, currentPrice: number) => Promise<number | null>;
2571
2641
  /**
2572
2642
  * Fast backtest using historical candles.
2573
2643
  * Iterates through candles, calculates VWAP, checks TP/SL on each candle.
@@ -4210,6 +4280,202 @@ declare function commitActivateScheduled(symbol: string, activateId?: string): P
4210
4280
  * ```
4211
4281
  */
4212
4282
  declare function commitAverageBuy(symbol: string): Promise<boolean>;
4283
+ /**
4284
+ * Returns the percentage of the position currently held (not closed).
4285
+ * 100 = nothing has been closed (full position), 0 = fully closed.
4286
+ * Correctly accounts for DCA entries between partial closes.
4287
+ *
4288
+ * Automatically detects backtest/live mode from execution context.
4289
+ *
4290
+ * @param symbol - Trading pair symbol
4291
+ * @returns Promise<number> - held percentage (0–100)
4292
+ *
4293
+ * @example
4294
+ * ```typescript
4295
+ * import { getTotalPercentClosed } from "backtest-kit";
4296
+ *
4297
+ * const heldPct = await getTotalPercentClosed("BTCUSDT");
4298
+ * console.log(`Holding ${heldPct}% of position`);
4299
+ * ```
4300
+ */
4301
+ declare function getTotalPercentClosed(symbol: string): Promise<number>;
4302
+ /**
4303
+ * Returns the cost basis in dollars of the position currently held (not closed).
4304
+ * Correctly accounts for DCA entries between partial closes.
4305
+ *
4306
+ * Automatically detects backtest/live mode from execution context.
4307
+ *
4308
+ * @param symbol - Trading pair symbol
4309
+ * @returns Promise<number> - held cost basis in dollars
4310
+ *
4311
+ * @example
4312
+ * ```typescript
4313
+ * import { getTotalCostClosed } from "backtest-kit";
4314
+ *
4315
+ * const heldCost = await getTotalCostClosed("BTCUSDT");
4316
+ * console.log(`Holding $${heldCost} of position`);
4317
+ * ```
4318
+ */
4319
+ declare function getTotalCostClosed(symbol: string): Promise<number>;
4320
+ /**
4321
+ * Returns the currently active pending signal for the strategy.
4322
+ * If no active signal exists, returns null.
4323
+ *
4324
+ * Automatically detects backtest/live mode from execution context.
4325
+ *
4326
+ * @param symbol - Trading pair symbol
4327
+ * @returns Promise resolving to pending signal or null
4328
+ *
4329
+ * @example
4330
+ * ```typescript
4331
+ * import { getPendingSignal } from "backtest-kit";
4332
+ *
4333
+ * const pending = await getPendingSignal("BTCUSDT");
4334
+ * if (pending) {
4335
+ * console.log("Active signal:", pending.id);
4336
+ * }
4337
+ * ```
4338
+ */
4339
+ declare function getPendingSignal(symbol: string): Promise<ISignalRow>;
4340
+ /**
4341
+ * Returns the currently active scheduled signal for the strategy.
4342
+ * If no scheduled signal exists, returns null.
4343
+ *
4344
+ * Automatically detects backtest/live mode from execution context.
4345
+ *
4346
+ * @param symbol - Trading pair symbol
4347
+ * @returns Promise resolving to scheduled signal or null
4348
+ *
4349
+ * @example
4350
+ * ```typescript
4351
+ * import { getScheduledSignal } from "backtest-kit";
4352
+ *
4353
+ * const scheduled = await getScheduledSignal("BTCUSDT");
4354
+ * if (scheduled) {
4355
+ * console.log("Scheduled signal:", scheduled.id);
4356
+ * }
4357
+ * ```
4358
+ */
4359
+ declare function getScheduledSignal(symbol: string): Promise<IScheduledSignalRow>;
4360
+ /**
4361
+ * Checks if breakeven threshold has been reached for the current pending signal.
4362
+ *
4363
+ * Returns true if price has moved far enough in profit direction to cover
4364
+ * transaction costs. Threshold is calculated as: (CC_PERCENT_SLIPPAGE + CC_PERCENT_FEE) * 2
4365
+ *
4366
+ * Automatically detects backtest/live mode from execution context.
4367
+ *
4368
+ * @param symbol - Trading pair symbol
4369
+ * @param currentPrice - Current market price to check against threshold
4370
+ * @returns Promise<boolean> - true if breakeven threshold reached, false otherwise
4371
+ *
4372
+ * @example
4373
+ * ```typescript
4374
+ * import { getBreakeven, getAveragePrice } from "backtest-kit";
4375
+ *
4376
+ * const price = await getAveragePrice("BTCUSDT");
4377
+ * const canBreakeven = await getBreakeven("BTCUSDT", price);
4378
+ * if (canBreakeven) {
4379
+ * console.log("Breakeven available");
4380
+ * }
4381
+ * ```
4382
+ */
4383
+ declare function getBreakeven(symbol: string, currentPrice: number): Promise<boolean>;
4384
+ declare function getPositionAveragePrice(symbol: string): Promise<number | null>;
4385
+ declare function getPositionInvestedCount(symbol: string): Promise<number | null>;
4386
+ declare function getPositionInvestedCost(symbol: string): Promise<number | null>;
4387
+ declare function getPositionPnlPercent(symbol: string): Promise<number | null>;
4388
+ /**
4389
+ * Executes partial close at profit level by absolute dollar amount (moving toward TP).
4390
+ *
4391
+ * Convenience wrapper around commitPartialProfit that converts a dollar amount
4392
+ * to a percentage of the invested position cost automatically.
4393
+ * Price must be moving toward take profit (in profit direction).
4394
+ *
4395
+ * Automatically detects backtest/live mode from execution context.
4396
+ * Automatically fetches current price via getAveragePrice.
4397
+ *
4398
+ * @param symbol - Trading pair symbol
4399
+ * @param dollarAmount - Dollar value of position to close (e.g. 150 closes $150 worth)
4400
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
4401
+ *
4402
+ * @throws Error if currentPrice is not in profit direction:
4403
+ * - LONG: currentPrice must be > priceOpen
4404
+ * - SHORT: currentPrice must be < priceOpen
4405
+ *
4406
+ * @example
4407
+ * ```typescript
4408
+ * import { commitPartialProfitCost } from "backtest-kit";
4409
+ *
4410
+ * // Close $150 of a $300 position (50%) at profit
4411
+ * const success = await commitPartialProfitCost("BTCUSDT", 150);
4412
+ * if (success) {
4413
+ * console.log('Partial profit executed');
4414
+ * }
4415
+ * ```
4416
+ */
4417
+ declare function commitPartialProfitCost(symbol: string, dollarAmount: number): Promise<boolean>;
4418
+ /**
4419
+ * Executes partial close at loss level by absolute dollar amount (moving toward SL).
4420
+ *
4421
+ * Convenience wrapper around commitPartialLoss that converts a dollar amount
4422
+ * to a percentage of the invested position cost automatically.
4423
+ * Price must be moving toward stop loss (in loss direction).
4424
+ *
4425
+ * Automatically detects backtest/live mode from execution context.
4426
+ * Automatically fetches current price via getAveragePrice.
4427
+ *
4428
+ * @param symbol - Trading pair symbol
4429
+ * @param dollarAmount - Dollar value of position to close (e.g. 100 closes $100 worth)
4430
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
4431
+ *
4432
+ * @throws Error if currentPrice is not in loss direction:
4433
+ * - LONG: currentPrice must be < priceOpen
4434
+ * - SHORT: currentPrice must be > priceOpen
4435
+ *
4436
+ * @example
4437
+ * ```typescript
4438
+ * import { commitPartialLossCost } from "backtest-kit";
4439
+ *
4440
+ * // Close $100 of a $300 position (~33%) at loss
4441
+ * const success = await commitPartialLossCost("BTCUSDT", 100);
4442
+ * if (success) {
4443
+ * console.log('Partial loss executed');
4444
+ * }
4445
+ * ```
4446
+ */
4447
+ declare function commitPartialLossCost(symbol: string, dollarAmount: number): Promise<boolean>;
4448
+ declare function getPositionPnlCost(symbol: string): Promise<number | null>;
4449
+ /**
4450
+ * Returns the list of DCA entry prices for the current pending signal.
4451
+ *
4452
+ * The first element is always the original priceOpen (initial entry).
4453
+ * Each subsequent element is a price added by commitAverageBuy().
4454
+ *
4455
+ * Returns null if no pending signal exists.
4456
+ * Returns a single-element array [priceOpen] if no DCA entries were made.
4457
+ *
4458
+ * @param symbol - Trading pair symbol
4459
+ * @returns Promise resolving to array of entry prices or null
4460
+ *
4461
+ * @example
4462
+ * ```typescript
4463
+ * import { getPositionLevels } from "backtest-kit";
4464
+ *
4465
+ * const levels = await getPositionLevels("BTCUSDT");
4466
+ * // No DCA: [43000]
4467
+ * // One DCA: [43000, 42000]
4468
+ * ```
4469
+ */
4470
+ declare function getPositionLevels(symbol: string): Promise<number[] | null>;
4471
+ declare function getPositionPartials(symbol: string): Promise<{
4472
+ type: "profit" | "loss";
4473
+ percent: number;
4474
+ currentPrice: number;
4475
+ effectivePrice: number;
4476
+ entryCountAtClose: number;
4477
+ debugTimestamp?: number;
4478
+ }[]>;
4213
4479
 
4214
4480
  /**
4215
4481
  * Stops the strategy from generating new signals.
@@ -4483,6 +4749,14 @@ declare const GLOBAL_CONFIG: {
4483
4749
  * Default: true (mutex locking enabled for candle fetching)
4484
4750
  */
4485
4751
  CC_ENABLE_CANDLE_FETCH_MUTEX: boolean;
4752
+ /**
4753
+ * Enables DCA (Dollar-Cost Averaging) logic even if antirecord is not broken.
4754
+ * Allows to commitAverageBuy if currentPrice is not the lowest price since entry, but still lower than priceOpen.
4755
+ * This can help improve average entry price in cases where price has rebounded after entry but is still below priceOpen, without waiting for a new lower price.
4756
+ *
4757
+ * Default: true (DCA logic enabled everywhere, not just when antirecord is broken)
4758
+ */
4759
+ CC_ENABLE_DCA_EVERYWHERE: boolean;
4486
4760
  };
4487
4761
  /**
4488
4762
  * Type for global configuration object.
@@ -4594,6 +4868,7 @@ declare function getConfig(): {
4594
4868
  CC_MAX_SIGNALS: number;
4595
4869
  CC_MAX_LOG_LINES: number;
4596
4870
  CC_ENABLE_CANDLE_FETCH_MUTEX: boolean;
4871
+ CC_ENABLE_DCA_EVERYWHERE: boolean;
4597
4872
  };
4598
4873
  /**
4599
4874
  * Retrieves the default configuration object for the framework.
@@ -4633,6 +4908,7 @@ declare function getDefaultConfig(): Readonly<{
4633
4908
  CC_MAX_SIGNALS: number;
4634
4909
  CC_MAX_LOG_LINES: number;
4635
4910
  CC_ENABLE_CANDLE_FETCH_MUTEX: boolean;
4911
+ CC_ENABLE_DCA_EVERYWHERE: boolean;
4636
4912
  }>;
4637
4913
  /**
4638
4914
  * Sets custom column configurations for markdown report generation.
@@ -10382,6 +10658,45 @@ declare class BacktestUtils {
10382
10658
  exchangeName: ExchangeName;
10383
10659
  frameName: FrameName;
10384
10660
  }) => Promise<ISignalRow>;
10661
+ /**
10662
+ * Returns the percentage of the position currently held (not closed).
10663
+ * 100 = nothing has been closed (full position), 0 = fully closed.
10664
+ * Correctly accounts for DCA entries between partial closes.
10665
+ *
10666
+ * @param symbol - Trading pair symbol
10667
+ * @param context - Context with strategyName, exchangeName, frameName
10668
+ * @returns Promise<number> - held percentage (0–100)
10669
+ *
10670
+ * @example
10671
+ * ```typescript
10672
+ * const heldPct = await Backtest.getTotalPercentClosed("BTCUSDT", { strategyName, exchangeName, frameName });
10673
+ * console.log(`Holding ${heldPct}% of position`);
10674
+ * ```
10675
+ */
10676
+ getTotalPercentClosed: (symbol: string, context: {
10677
+ strategyName: StrategyName;
10678
+ exchangeName: ExchangeName;
10679
+ frameName: FrameName;
10680
+ }) => Promise<number>;
10681
+ /**
10682
+ * Returns the cost basis in dollars of the position currently held (not closed).
10683
+ * Correctly accounts for DCA entries between partial closes.
10684
+ *
10685
+ * @param symbol - Trading pair symbol
10686
+ * @param context - Context with strategyName, exchangeName, frameName
10687
+ * @returns Promise<number> - held cost basis in dollars
10688
+ *
10689
+ * @example
10690
+ * ```typescript
10691
+ * const heldCost = await Backtest.getTotalCostClosed("BTCUSDT", { strategyName, exchangeName, frameName });
10692
+ * console.log(`Holding $${heldCost} of position`);
10693
+ * ```
10694
+ */
10695
+ getTotalCostClosed: (symbol: string, context: {
10696
+ strategyName: StrategyName;
10697
+ exchangeName: ExchangeName;
10698
+ frameName: FrameName;
10699
+ }) => Promise<number>;
10385
10700
  /**
10386
10701
  * Retrieves the currently active scheduled signal for the strategy.
10387
10702
  * If no scheduled signal exists, returns null.
@@ -10432,6 +10747,48 @@ declare class BacktestUtils {
10432
10747
  exchangeName: ExchangeName;
10433
10748
  frameName: FrameName;
10434
10749
  }) => Promise<boolean>;
10750
+ getPositionAveragePrice: (symbol: string, context: {
10751
+ strategyName: StrategyName;
10752
+ exchangeName: ExchangeName;
10753
+ frameName: FrameName;
10754
+ }) => Promise<number | null>;
10755
+ getPositionInvestedCount: (symbol: string, context: {
10756
+ strategyName: StrategyName;
10757
+ exchangeName: ExchangeName;
10758
+ frameName: FrameName;
10759
+ }) => Promise<number | null>;
10760
+ getPositionInvestedCost: (symbol: string, context: {
10761
+ strategyName: StrategyName;
10762
+ exchangeName: ExchangeName;
10763
+ frameName: FrameName;
10764
+ }) => Promise<number | null>;
10765
+ getPositionPnlPercent: (symbol: string, currentPrice: number, context: {
10766
+ strategyName: StrategyName;
10767
+ exchangeName: ExchangeName;
10768
+ frameName: FrameName;
10769
+ }) => Promise<number | null>;
10770
+ getPositionPnlCost: (symbol: string, currentPrice: number, context: {
10771
+ strategyName: StrategyName;
10772
+ exchangeName: ExchangeName;
10773
+ frameName: FrameName;
10774
+ }) => Promise<number | null>;
10775
+ getPositionLevels: (symbol: string, context: {
10776
+ strategyName: StrategyName;
10777
+ exchangeName: ExchangeName;
10778
+ frameName: FrameName;
10779
+ }) => Promise<number[] | null>;
10780
+ getPositionPartials: (symbol: string, context: {
10781
+ strategyName: StrategyName;
10782
+ exchangeName: ExchangeName;
10783
+ frameName: FrameName;
10784
+ }) => Promise<{
10785
+ type: "profit" | "loss";
10786
+ percent: number;
10787
+ currentPrice: number;
10788
+ effectivePrice: number;
10789
+ entryCountAtClose: number;
10790
+ debugTimestamp?: number;
10791
+ }[]>;
10435
10792
  /**
10436
10793
  * Stops the strategy from generating new signals.
10437
10794
  *
@@ -10582,6 +10939,76 @@ declare class BacktestUtils {
10582
10939
  exchangeName: ExchangeName;
10583
10940
  frameName: FrameName;
10584
10941
  }) => Promise<boolean>;
10942
+ /**
10943
+ * Executes partial close at profit level by absolute dollar amount (moving toward TP).
10944
+ *
10945
+ * Convenience wrapper around commitPartialProfit that converts a dollar amount
10946
+ * to a percentage of the invested position cost automatically.
10947
+ * Price must be moving toward take profit (in profit direction).
10948
+ *
10949
+ * @param symbol - Trading pair symbol
10950
+ * @param dollarAmount - Dollar value of position to close (e.g. 150 closes $150 worth)
10951
+ * @param currentPrice - Current market price for this partial close
10952
+ * @param context - Execution context with strategyName, exchangeName, and frameName
10953
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
10954
+ *
10955
+ * @throws Error if currentPrice is not in profit direction:
10956
+ * - LONG: currentPrice must be > priceOpen
10957
+ * - SHORT: currentPrice must be < priceOpen
10958
+ *
10959
+ * @example
10960
+ * ```typescript
10961
+ * // Close $150 of a $300 position (50%) at profit
10962
+ * const success = await Backtest.commitPartialProfitCost("BTCUSDT", 150, 45000, {
10963
+ * exchangeName: "binance",
10964
+ * frameName: "frame1",
10965
+ * strategyName: "my-strategy"
10966
+ * });
10967
+ * if (success) {
10968
+ * console.log('Partial profit executed');
10969
+ * }
10970
+ * ```
10971
+ */
10972
+ commitPartialProfitCost: (symbol: string, dollarAmount: number, currentPrice: number, context: {
10973
+ strategyName: StrategyName;
10974
+ exchangeName: ExchangeName;
10975
+ frameName: FrameName;
10976
+ }) => Promise<boolean>;
10977
+ /**
10978
+ * Executes partial close at loss level by absolute dollar amount (moving toward SL).
10979
+ *
10980
+ * Convenience wrapper around commitPartialLoss that converts a dollar amount
10981
+ * to a percentage of the invested position cost automatically.
10982
+ * Price must be moving toward stop loss (in loss direction).
10983
+ *
10984
+ * @param symbol - Trading pair symbol
10985
+ * @param dollarAmount - Dollar value of position to close (e.g. 100 closes $100 worth)
10986
+ * @param currentPrice - Current market price for this partial close
10987
+ * @param context - Execution context with strategyName, exchangeName, and frameName
10988
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
10989
+ *
10990
+ * @throws Error if currentPrice is not in loss direction:
10991
+ * - LONG: currentPrice must be < priceOpen
10992
+ * - SHORT: currentPrice must be > priceOpen
10993
+ *
10994
+ * @example
10995
+ * ```typescript
10996
+ * // Close $100 of a $300 position (~33%) at loss
10997
+ * const success = await Backtest.commitPartialLossCost("BTCUSDT", 100, 38000, {
10998
+ * exchangeName: "binance",
10999
+ * frameName: "frame1",
11000
+ * strategyName: "my-strategy"
11001
+ * });
11002
+ * if (success) {
11003
+ * console.log('Partial loss executed');
11004
+ * }
11005
+ * ```
11006
+ */
11007
+ commitPartialLossCost: (symbol: string, dollarAmount: number, currentPrice: number, context: {
11008
+ strategyName: StrategyName;
11009
+ exchangeName: ExchangeName;
11010
+ frameName: FrameName;
11011
+ }) => Promise<boolean>;
10585
11012
  /**
10586
11013
  * Adjusts the trailing stop-loss distance for an active pending signal.
10587
11014
  *
@@ -11186,6 +11613,43 @@ declare class LiveUtils {
11186
11613
  strategyName: StrategyName;
11187
11614
  exchangeName: ExchangeName;
11188
11615
  }) => Promise<ISignalRow>;
11616
+ /**
11617
+ * Returns the percentage of the position currently held (not closed).
11618
+ * 100 = nothing has been closed (full position), 0 = fully closed.
11619
+ * Correctly accounts for DCA entries between partial closes.
11620
+ *
11621
+ * @param symbol - Trading pair symbol
11622
+ * @param context - Context with strategyName and exchangeName
11623
+ * @returns Promise<number> - held percentage (0–100)
11624
+ *
11625
+ * @example
11626
+ * ```typescript
11627
+ * const heldPct = await Live.getTotalPercentClosed("BTCUSDT", { strategyName, exchangeName });
11628
+ * console.log(`Holding ${heldPct}% of position`);
11629
+ * ```
11630
+ */
11631
+ getTotalPercentClosed: (symbol: string, context: {
11632
+ strategyName: StrategyName;
11633
+ exchangeName: ExchangeName;
11634
+ }) => Promise<number>;
11635
+ /**
11636
+ * Returns the cost basis in dollars of the position currently held (not closed).
11637
+ * Correctly accounts for DCA entries between partial closes.
11638
+ *
11639
+ * @param symbol - Trading pair symbol
11640
+ * @param context - Context with strategyName and exchangeName
11641
+ * @returns Promise<number> - held cost basis in dollars
11642
+ *
11643
+ * @example
11644
+ * ```typescript
11645
+ * const heldCost = await Live.getTotalCostClosed("BTCUSDT", { strategyName, exchangeName });
11646
+ * console.log(`Holding $${heldCost} of position`);
11647
+ * ```
11648
+ */
11649
+ getTotalCostClosed: (symbol: string, context: {
11650
+ strategyName: StrategyName;
11651
+ exchangeName: ExchangeName;
11652
+ }) => Promise<number>;
11189
11653
  /**
11190
11654
  * Retrieves the currently active scheduled signal for the strategy.
11191
11655
  * If no scheduled signal exists, returns null.
@@ -11233,6 +11697,41 @@ declare class LiveUtils {
11233
11697
  strategyName: StrategyName;
11234
11698
  exchangeName: ExchangeName;
11235
11699
  }) => Promise<boolean>;
11700
+ getPositionAveragePrice: (symbol: string, context: {
11701
+ strategyName: StrategyName;
11702
+ exchangeName: ExchangeName;
11703
+ }) => Promise<number | null>;
11704
+ getPositionInvestedCount: (symbol: string, context: {
11705
+ strategyName: StrategyName;
11706
+ exchangeName: ExchangeName;
11707
+ }) => Promise<number | null>;
11708
+ getPositionInvestedCost: (symbol: string, context: {
11709
+ strategyName: StrategyName;
11710
+ exchangeName: ExchangeName;
11711
+ }) => Promise<number | null>;
11712
+ getPositionPnlPercent: (symbol: string, currentPrice: number, context: {
11713
+ strategyName: StrategyName;
11714
+ exchangeName: ExchangeName;
11715
+ }) => Promise<number | null>;
11716
+ getPositionPnlCost: (symbol: string, currentPrice: number, context: {
11717
+ strategyName: StrategyName;
11718
+ exchangeName: ExchangeName;
11719
+ }) => Promise<number | null>;
11720
+ getPositionLevels: (symbol: string, context: {
11721
+ strategyName: StrategyName;
11722
+ exchangeName: ExchangeName;
11723
+ }) => Promise<number[] | null>;
11724
+ getPositionPartials: (symbol: string, context: {
11725
+ strategyName: StrategyName;
11726
+ exchangeName: ExchangeName;
11727
+ }) => Promise<{
11728
+ type: "profit" | "loss";
11729
+ percent: number;
11730
+ currentPrice: number;
11731
+ effectivePrice: number;
11732
+ entryCountAtClose: number;
11733
+ debugTimestamp?: number;
11734
+ }[]>;
11236
11735
  /**
11237
11736
  * Stops the strategy from generating new signals.
11238
11737
  *
@@ -11370,6 +11869,72 @@ declare class LiveUtils {
11370
11869
  strategyName: StrategyName;
11371
11870
  exchangeName: ExchangeName;
11372
11871
  }) => Promise<boolean>;
11872
+ /**
11873
+ * Executes partial close at profit level by absolute dollar amount (moving toward TP).
11874
+ *
11875
+ * Convenience wrapper around commitPartialProfit that converts a dollar amount
11876
+ * to a percentage of the invested position cost automatically.
11877
+ * Price must be moving toward take profit (in profit direction).
11878
+ *
11879
+ * @param symbol - Trading pair symbol
11880
+ * @param dollarAmount - Dollar value of position to close (e.g. 150 closes $150 worth)
11881
+ * @param currentPrice - Current market price for this partial close
11882
+ * @param context - Execution context with strategyName and exchangeName
11883
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
11884
+ *
11885
+ * @throws Error if currentPrice is not in profit direction:
11886
+ * - LONG: currentPrice must be > priceOpen
11887
+ * - SHORT: currentPrice must be < priceOpen
11888
+ *
11889
+ * @example
11890
+ * ```typescript
11891
+ * // Close $150 of a $300 position (50%) at profit
11892
+ * const success = await Live.commitPartialProfitCost("BTCUSDT", 150, 45000, {
11893
+ * exchangeName: "binance",
11894
+ * strategyName: "my-strategy"
11895
+ * });
11896
+ * if (success) {
11897
+ * console.log('Partial profit executed');
11898
+ * }
11899
+ * ```
11900
+ */
11901
+ commitPartialProfitCost: (symbol: string, dollarAmount: number, currentPrice: number, context: {
11902
+ strategyName: StrategyName;
11903
+ exchangeName: ExchangeName;
11904
+ }) => Promise<boolean>;
11905
+ /**
11906
+ * Executes partial close at loss level by absolute dollar amount (moving toward SL).
11907
+ *
11908
+ * Convenience wrapper around commitPartialLoss that converts a dollar amount
11909
+ * to a percentage of the invested position cost automatically.
11910
+ * Price must be moving toward stop loss (in loss direction).
11911
+ *
11912
+ * @param symbol - Trading pair symbol
11913
+ * @param dollarAmount - Dollar value of position to close (e.g. 100 closes $100 worth)
11914
+ * @param currentPrice - Current market price for this partial close
11915
+ * @param context - Execution context with strategyName and exchangeName
11916
+ * @returns Promise<boolean> - true if partial close executed, false if skipped or no position
11917
+ *
11918
+ * @throws Error if currentPrice is not in loss direction:
11919
+ * - LONG: currentPrice must be < priceOpen
11920
+ * - SHORT: currentPrice must be > priceOpen
11921
+ *
11922
+ * @example
11923
+ * ```typescript
11924
+ * // Close $100 of a $300 position (~33%) at loss
11925
+ * const success = await Live.commitPartialLossCost("BTCUSDT", 100, 38000, {
11926
+ * exchangeName: "binance",
11927
+ * strategyName: "my-strategy"
11928
+ * });
11929
+ * if (success) {
11930
+ * console.log('Partial loss executed');
11931
+ * }
11932
+ * ```
11933
+ */
11934
+ commitPartialLossCost: (symbol: string, dollarAmount: number, currentPrice: number, context: {
11935
+ strategyName: StrategyName;
11936
+ exchangeName: ExchangeName;
11937
+ }) => Promise<boolean>;
11373
11938
  /**
11374
11939
  * Adjusts the trailing stop-loss distance for an active pending signal.
11375
11940
  *
@@ -15317,6 +15882,77 @@ declare class StrategyCoreService implements TStrategy$1 {
15317
15882
  exchangeName: ExchangeName;
15318
15883
  frameName: FrameName;
15319
15884
  }) => Promise<ISignalRow | null>;
15885
+ /**
15886
+ * Returns the percentage of the position currently held (not closed).
15887
+ * 100 = nothing has been closed (full position), 0 = fully closed.
15888
+ * Correctly accounts for DCA entries between partial closes.
15889
+ *
15890
+ * @param backtest - Whether running in backtest mode
15891
+ * @param symbol - Trading pair symbol
15892
+ * @param context - Execution context with strategyName, exchangeName, frameName
15893
+ * @returns Promise<number> - held percentage (0–100)
15894
+ */
15895
+ getTotalPercentClosed: (backtest: boolean, symbol: string, context: {
15896
+ strategyName: StrategyName;
15897
+ exchangeName: ExchangeName;
15898
+ frameName: FrameName;
15899
+ }) => Promise<number | null>;
15900
+ /**
15901
+ * Returns the cost basis in dollars of the position currently held (not closed).
15902
+ * Correctly accounts for DCA entries between partial closes.
15903
+ *
15904
+ * @param backtest - Whether running in backtest mode
15905
+ * @param symbol - Trading pair symbol
15906
+ * @param context - Execution context with strategyName, exchangeName, frameName
15907
+ * @returns Promise<number> - held cost basis in dollars
15908
+ */
15909
+ getTotalCostClosed: (backtest: boolean, symbol: string, context: {
15910
+ strategyName: StrategyName;
15911
+ exchangeName: ExchangeName;
15912
+ frameName: FrameName;
15913
+ }) => Promise<number | null>;
15914
+ getPositionAveragePrice: (backtest: boolean, symbol: string, context: {
15915
+ strategyName: StrategyName;
15916
+ exchangeName: ExchangeName;
15917
+ frameName: FrameName;
15918
+ }) => Promise<number | null>;
15919
+ getPositionInvestedCount: (backtest: boolean, symbol: string, context: {
15920
+ strategyName: StrategyName;
15921
+ exchangeName: ExchangeName;
15922
+ frameName: FrameName;
15923
+ }) => Promise<number | null>;
15924
+ getPositionInvestedCost: (backtest: boolean, symbol: string, context: {
15925
+ strategyName: StrategyName;
15926
+ exchangeName: ExchangeName;
15927
+ frameName: FrameName;
15928
+ }) => Promise<number | null>;
15929
+ getPositionPnlPercent: (backtest: boolean, symbol: string, currentPrice: number, context: {
15930
+ strategyName: StrategyName;
15931
+ exchangeName: ExchangeName;
15932
+ frameName: FrameName;
15933
+ }) => Promise<number | null>;
15934
+ getPositionPnlCost: (backtest: boolean, symbol: string, currentPrice: number, context: {
15935
+ strategyName: StrategyName;
15936
+ exchangeName: ExchangeName;
15937
+ frameName: FrameName;
15938
+ }) => Promise<number | null>;
15939
+ getPositionLevels: (backtest: boolean, symbol: string, context: {
15940
+ strategyName: StrategyName;
15941
+ exchangeName: ExchangeName;
15942
+ frameName: FrameName;
15943
+ }) => Promise<number[] | null>;
15944
+ getPositionPartials: (backtest: boolean, symbol: string, context: {
15945
+ strategyName: StrategyName;
15946
+ exchangeName: ExchangeName;
15947
+ frameName: FrameName;
15948
+ }) => Promise<{
15949
+ type: "profit" | "loss";
15950
+ percent: number;
15951
+ currentPrice: number;
15952
+ effectivePrice: number;
15953
+ entryCountAtClose: number;
15954
+ debugTimestamp?: number;
15955
+ }[]>;
15320
15956
  /**
15321
15957
  * Retrieves the currently active scheduled signal for the symbol.
15322
15958
  * If no scheduled signal exists, returns null.
@@ -17132,6 +17768,36 @@ declare const get: (object: any, path: any) => any;
17132
17768
  */
17133
17769
  declare const set: (object: any, path: any, value: any) => boolean;
17134
17770
 
17771
+ /**
17772
+ * Calculate the percentage difference between two numbers.
17773
+ * @param {number} a - The first number.
17774
+ * @param {number} b - The second number.
17775
+ * @returns {number} The percentage difference between the two numbers.
17776
+ */
17777
+ declare const percentDiff: (a?: number, b?: number) => number;
17778
+
17779
+ /**
17780
+ * Calculate the percentage change from yesterday's value to today's value.
17781
+ * @param {number} yesterdayValue - The value from yesterday.
17782
+ * @param {number} todayValue - The value from today.
17783
+ * @returns {number} The percentage change from yesterday to today.
17784
+ */
17785
+ declare const percentValue: (yesterdayValue: number, todayValue: number) => number;
17786
+
17787
+ /**
17788
+ * Convert an absolute dollar amount to a percentage of the invested position cost.
17789
+ * Use the result as the `percent` argument to `commitPartialProfit` / `commitPartialLoss`.
17790
+ *
17791
+ * @param dollarAmount - Dollar value to close (e.g. 150)
17792
+ * @param investedCost - Total invested cost from `getPositionInvestedCost` (e.g. 300)
17793
+ * @returns Percentage of the position to close (0–100)
17794
+ *
17795
+ * @example
17796
+ * const percent = investedCostToPercent(150, 300); // 50
17797
+ * await commitPartialProfit("BTCUSDT", percent);
17798
+ */
17799
+ declare const investedCostToPercent: (dollarAmount: number, investedCost: number) => number;
17800
+
17135
17801
  /**
17136
17802
  * Client implementation for exchange data access.
17137
17803
  *
@@ -18170,6 +18836,77 @@ declare class StrategyConnectionService implements TStrategy {
18170
18836
  exchangeName: ExchangeName;
18171
18837
  frameName: FrameName;
18172
18838
  }) => Promise<ISignalRow | null>;
18839
+ /**
18840
+ * Returns the percentage of the position currently held (not closed).
18841
+ * 100 = nothing has been closed (full position), 0 = fully closed.
18842
+ * Correctly accounts for DCA entries between partial closes.
18843
+ *
18844
+ * @param backtest - Whether running in backtest mode
18845
+ * @param symbol - Trading pair symbol
18846
+ * @param context - Execution context with strategyName, exchangeName, frameName
18847
+ * @returns Promise<number> - held percentage (0–100)
18848
+ */
18849
+ getTotalPercentClosed: (backtest: boolean, symbol: string, context: {
18850
+ strategyName: StrategyName;
18851
+ exchangeName: ExchangeName;
18852
+ frameName: FrameName;
18853
+ }) => Promise<number | null>;
18854
+ /**
18855
+ * Returns the cost basis in dollars of the position currently held (not closed).
18856
+ * Correctly accounts for DCA entries between partial closes.
18857
+ *
18858
+ * @param backtest - Whether running in backtest mode
18859
+ * @param symbol - Trading pair symbol
18860
+ * @param context - Execution context with strategyName, exchangeName, frameName
18861
+ * @returns Promise<number> - held cost basis in dollars
18862
+ */
18863
+ getTotalCostClosed: (backtest: boolean, symbol: string, context: {
18864
+ strategyName: StrategyName;
18865
+ exchangeName: ExchangeName;
18866
+ frameName: FrameName;
18867
+ }) => Promise<number | null>;
18868
+ getPositionAveragePrice: (backtest: boolean, symbol: string, context: {
18869
+ strategyName: StrategyName;
18870
+ exchangeName: ExchangeName;
18871
+ frameName: FrameName;
18872
+ }) => Promise<number | null>;
18873
+ getPositionInvestedCount: (backtest: boolean, symbol: string, context: {
18874
+ strategyName: StrategyName;
18875
+ exchangeName: ExchangeName;
18876
+ frameName: FrameName;
18877
+ }) => Promise<number | null>;
18878
+ getPositionInvestedCost: (backtest: boolean, symbol: string, context: {
18879
+ strategyName: StrategyName;
18880
+ exchangeName: ExchangeName;
18881
+ frameName: FrameName;
18882
+ }) => Promise<number | null>;
18883
+ getPositionPnlPercent: (backtest: boolean, symbol: string, currentPrice: number, context: {
18884
+ strategyName: StrategyName;
18885
+ exchangeName: ExchangeName;
18886
+ frameName: FrameName;
18887
+ }) => Promise<number | null>;
18888
+ getPositionPnlCost: (backtest: boolean, symbol: string, currentPrice: number, context: {
18889
+ strategyName: StrategyName;
18890
+ exchangeName: ExchangeName;
18891
+ frameName: FrameName;
18892
+ }) => Promise<number | null>;
18893
+ getPositionLevels: (backtest: boolean, symbol: string, context: {
18894
+ strategyName: StrategyName;
18895
+ exchangeName: ExchangeName;
18896
+ frameName: FrameName;
18897
+ }) => Promise<number[] | null>;
18898
+ getPositionPartials: (backtest: boolean, symbol: string, context: {
18899
+ strategyName: StrategyName;
18900
+ exchangeName: ExchangeName;
18901
+ frameName: FrameName;
18902
+ }) => Promise<{
18903
+ type: "profit" | "loss";
18904
+ percent: number;
18905
+ currentPrice: number;
18906
+ effectivePrice: number;
18907
+ entryCountAtClose: number;
18908
+ debugTimestamp?: number;
18909
+ }[]>;
18173
18910
  /**
18174
18911
  * Retrieves the currently active scheduled signal for the strategy.
18175
18912
  * If no scheduled signal exists, returns null.
@@ -21754,4 +22491,75 @@ declare const backtest: {
21754
22491
  loggerService: LoggerService;
21755
22492
  };
21756
22493
 
21757
- export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, type AverageBuyCommit, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IAggregatedTradeData, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type ILog, type ILogEntry, type ILogger, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicCandleData, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Log, type LogData, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, type MeasureData, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TLogCtor, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, 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, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, 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, validate, waitForCandle, warmCandles };
22494
+ /**
22495
+ * Calculates profit/loss for a closed signal with slippage and fees.
22496
+ *
22497
+ * For signals with partial closes:
22498
+ * - Weights are calculated by ACTUAL DOLLAR VALUE of each partial relative to total invested.
22499
+ * This correctly handles DCA entries that occur before or after partial closes.
22500
+ *
22501
+ * Cost basis is reconstructed by replaying the partial sequence via entryCountAtClose + percent:
22502
+ * costBasis = 0
22503
+ * for each partial[i]:
22504
+ * costBasis += (entryCountAtClose[i] - entryCountAtClose[i-1]) × $100
22505
+ * partialDollarValue[i] = (percent[i] / 100) × costBasis
22506
+ * weight[i] = partialDollarValue[i] / totalInvested
22507
+ * costBasis *= (1 - percent[i] / 100)
22508
+ *
22509
+ * Fee structure:
22510
+ * - Open fee: CC_PERCENT_FEE (charged once)
22511
+ * - Close fee: CC_PERCENT_FEE × weight × (closeWithSlip / openWithSlip) per partial/remaining
22512
+ *
22513
+ * @param signal - Closed signal with position details and optional partial history
22514
+ * @param priceClose - Actual close price at final exit
22515
+ * @returns PNL data with percentage and prices
22516
+ */
22517
+ declare const toProfitLossDto: (signal: ISignalRow, priceClose: number) => IStrategyPnL;
22518
+
22519
+ /**
22520
+ * Returns the effective entry price for price calculations.
22521
+ *
22522
+ * Uses harmonic mean (correct for fixed-dollar DCA: $100 per entry).
22523
+ *
22524
+ * When partial closes exist, replays the partial sequence to reconstruct
22525
+ * the running cost basis at each partial — no extra stored fields needed.
22526
+ *
22527
+ * Cost basis replay:
22528
+ * costBasis starts at 0
22529
+ * for each partial[i]:
22530
+ * newEntries = entryCountAtClose[i] - entryCountAtClose[i-1] (or entryCountAtClose[0] for i=0)
22531
+ * costBasis += newEntries × $100 ← add DCA entries up to this partial
22532
+ * positionCostBasisAtClose[i] = costBasis ← snapshot BEFORE close
22533
+ * costBasis × = (1 - percent[i] / 100) ← reduce after close
22534
+ *
22535
+ * @param signal - Signal row
22536
+ * @returns Effective entry price for PNL calculations
22537
+ */
22538
+ declare const getEffectivePriceOpen: (signal: ISignalRow) => number;
22539
+
22540
+ /**
22541
+ * Returns the total closed state of a position using cost-basis replay.
22542
+ *
22543
+ * Correctly accounts for DCA entries added between partial closes via averageBuy().
22544
+ * Simple percent summation (sum of _partial[i].percent) is INCORRECT when averageBuy()
22545
+ * is called between partials — this function uses the same cost-basis replay as
22546
+ * toProfitLossDto to compute the true dollar-weighted closed fraction.
22547
+ *
22548
+ * Cost-basis replay:
22549
+ * costBasis = 0
22550
+ * for each partial[i]:
22551
+ * costBasis += (entryCountAtClose[i] - entryCountAtClose[i-1]) × $100
22552
+ * closedDollar += (percent[i] / 100) × costBasis
22553
+ * costBasis ×= (1 - percent[i] / 100)
22554
+ * // then add entries added AFTER the last partial
22555
+ * costBasis += (currentEntryCount - lastPartialEntryCount) × $100
22556
+ *
22557
+ * @param signal - Signal row with _partial and _entry arrays
22558
+ * @returns Object with totalClosedPercent (0–100+) and remainingCostBasis (dollar value still open)
22559
+ */
22560
+ declare const getTotalClosed: (signal: ISignalRow) => {
22561
+ totalClosedPercent: number;
22562
+ remainingCostBasis: number;
22563
+ };
22564
+
22565
+ export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, type AverageBuyCommit, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IAggregatedTradeData, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type ILog, type ILogEntry, type ILogger, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicCandleData, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Log, type LogData, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, type MeasureData, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TLogCtor, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, 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 };