backtest-kit 5.0.0 → 5.2.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "backtest-kit",
3
- "version": "5.0.0",
3
+ "version": "5.2.0",
4
4
  "description": "A TypeScript library for trading system backtest",
5
5
  "author": {
6
6
  "name": "Petr Tripolsky",
package/types.d.ts CHANGED
@@ -941,6 +941,13 @@ interface SchedulePingContract {
941
941
  * Contains all signal information: id, position, priceOpen, priceTakeProfit, priceStopLoss, etc.
942
942
  */
943
943
  data: IScheduledSignalRow;
944
+ /**
945
+ * Current market price of the symbol at the time of the ping.
946
+ * Useful for users to implement custom monitoring logic based on price conditions.
947
+ * For example, users can choose to cancel the scheduled signal if the price moves too far from priceOpen.
948
+ * Note: This is the current price at the time of the ping, not necessarily the priceOpen of the signal.
949
+ */
950
+ currentPrice: number;
944
951
  /**
945
952
  * Execution mode flag.
946
953
  * - true: Event from backtest execution (historical candle data)
@@ -1015,6 +1022,13 @@ interface ActivePingContract {
1015
1022
  * Contains all signal information: id, position, priceOpen, priceTakeProfit, priceStopLoss, etc.
1016
1023
  */
1017
1024
  data: ISignalRow;
1025
+ /**
1026
+ * Current market price of the symbol at the time of the ping.
1027
+ * Useful for users to implement custom management logic based on price conditions.
1028
+ * For example, users can choose to close the pending signal if the price moves too far from priceOpen.
1029
+ * Note: This is the current price at the time of the ping, not necessarily the priceOpen of the signal.
1030
+ */
1031
+ currentPrice: number;
1018
1032
  /**
1019
1033
  * Execution mode flag.
1020
1034
  * - true: Event from backtest execution (historical candle data)
@@ -2164,8 +2178,8 @@ interface ISignalRow extends ISignalDto {
2164
2178
  * Used to slice _entry to only entries that existed at this partial.
2165
2179
  */
2166
2180
  entryCountAtClose: number;
2167
- /** Debug only timestamp in milliseconds */
2168
- debugTimestamp?: number;
2181
+ /** Unix timestamp in milliseconds when this partial close was executed */
2182
+ timestamp: number;
2169
2183
  }>;
2170
2184
  /**
2171
2185
  * Trailing stop-loss price that overrides priceStopLoss when set.
@@ -2188,8 +2202,8 @@ interface ISignalRow extends ISignalDto {
2188
2202
  price: number;
2189
2203
  /** Cost of this entry in USD (e.g. 100 for $100 position) */
2190
2204
  cost: number;
2191
- /** Debug only timestamp in milliseconds */
2192
- debugTimestamp?: number;
2205
+ /** Unix timestamp in milliseconds when this entry was executed */
2206
+ timestamp: number;
2193
2207
  }>;
2194
2208
  /**
2195
2209
  * Trailing take-profit price that overrides priceTakeProfit when set.
@@ -2866,9 +2880,29 @@ interface IStrategy {
2866
2880
  * @param symbol - Trading pair symbol
2867
2881
  * @returns Promise resolving to array of entry records or null
2868
2882
  */
2869
- getPositionEntries: (symbol: string) => Promise<Array<{
2883
+ getPositionEntries: (symbol: string, timestamp: number) => Promise<Array<{
2870
2884
  price: number;
2871
2885
  cost: number;
2886
+ timestamp: number;
2887
+ }> | null>;
2888
+ /**
2889
+ * Returns the history of partial closes for the current pending signal.
2890
+ *
2891
+ * Each record includes the type (profit or loss), percentage closed, price, cost basis at close, and timestamp.
2892
+ * Used for tracking how the position was partially closed over time.
2893
+ *
2894
+ * Returns null if no pending signal exists or no partial closes were executed.
2895
+ *
2896
+ * @param symbol - Trading pair symbol
2897
+ * @returns Promise resolving to array of partial close records or null
2898
+ */
2899
+ getPositionPartials: (symbol: string) => Promise<Array<{
2900
+ type: "profit" | "loss";
2901
+ percent: number;
2902
+ currentPrice: number;
2903
+ costBasisAtClose: number;
2904
+ entryCountAtClose: number;
2905
+ timestamp: number;
2872
2906
  }> | null>;
2873
2907
  /**
2874
2908
  * Fast backtest using historical candles.
@@ -2988,14 +3022,15 @@ interface IStrategy {
2988
3022
  * @param percentToClose - Absolute percentage of position to close (0-100)
2989
3023
  * @param currentPrice - Current market price for partial close
2990
3024
  * @param backtest - Whether running in backtest mode
3025
+ * @param timestamp - Unix timestamp (ms) of the candle that triggered this partial close
2991
3026
  * @returns Promise<boolean> - true if partial close executed, false if skipped
2992
3027
  *
2993
3028
  * @example
2994
3029
  * ```typescript
2995
3030
  * callbacks: {
2996
- * onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
3031
+ * onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest, timestamp) => {
2997
3032
  * if (percentTp >= 50) {
2998
- * const success = await strategy.partialProfit(symbol, 25, currentPrice, backtest);
3033
+ * const success = await strategy.partialProfit(symbol, 25, currentPrice, backtest, timestamp);
2999
3034
  * if (success) {
3000
3035
  * console.log('Partial profit executed');
3001
3036
  * }
@@ -3004,7 +3039,7 @@ interface IStrategy {
3004
3039
  * }
3005
3040
  * ```
3006
3041
  */
3007
- partialProfit: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
3042
+ partialProfit: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean, timestamp: number) => Promise<boolean>;
3008
3043
  /**
3009
3044
  * Checks whether `partialProfit` would succeed without executing it.
3010
3045
  *
@@ -3043,14 +3078,15 @@ interface IStrategy {
3043
3078
  * @param percentToClose - Absolute percentage of position to close (0-100)
3044
3079
  * @param currentPrice - Current market price for partial close
3045
3080
  * @param backtest - Whether running in backtest mode
3081
+ * @param timestamp - Unix timestamp (ms) of the candle that triggered this partial close
3046
3082
  * @returns Promise<boolean> - true if partial close executed, false if skipped
3047
3083
  *
3048
3084
  * @example
3049
3085
  * ```typescript
3050
3086
  * callbacks: {
3051
- * onPartialLoss: async (symbol, signal, currentPrice, percentSl, backtest) => {
3087
+ * onPartialLoss: async (symbol, signal, currentPrice, percentSl, backtest, timestamp) => {
3052
3088
  * if (percentSl >= 80) {
3053
- * const success = await strategy.partialLoss(symbol, 50, currentPrice, backtest);
3089
+ * const success = await strategy.partialLoss(symbol, 50, currentPrice, backtest, timestamp);
3054
3090
  * if (success) {
3055
3091
  * console.log('Partial loss executed');
3056
3092
  * }
@@ -3059,7 +3095,7 @@ interface IStrategy {
3059
3095
  * }
3060
3096
  * ```
3061
3097
  */
3062
- partialLoss: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
3098
+ partialLoss: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean, timestamp: number) => Promise<boolean>;
3063
3099
  /**
3064
3100
  * Checks whether `partialLoss` would succeed without executing it.
3065
3101
  *
@@ -3318,9 +3354,11 @@ interface IStrategy {
3318
3354
  * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
3319
3355
  * @param currentPrice - New entry price to add to the averaging history
3320
3356
  * @param backtest - Whether running in backtest mode
3357
+ * @param timestamp - Unix timestamp (ms) of the candle that triggered this DCA entry
3358
+ * @param cost - Optional cost of the new entry (defaults to $100 if not provided)
3321
3359
  * @returns Promise<boolean> - true if entry added, false if rejected by direction check
3322
3360
  */
3323
- averageBuy: (symbol: string, currentPrice: number, backtest: boolean) => Promise<boolean>;
3361
+ averageBuy: (symbol: string, currentPrice: number, backtest: boolean, timestamp: number, cost?: number) => Promise<boolean>;
3324
3362
  /**
3325
3363
  * Checks whether `averageBuy` would succeed without executing it.
3326
3364
  *
@@ -5010,7 +5048,7 @@ declare function getPositionPartials(symbol: string): Promise<{
5010
5048
  currentPrice: number;
5011
5049
  costBasisAtClose: number;
5012
5050
  entryCountAtClose: number;
5013
- debugTimestamp?: number;
5051
+ timestamp: number;
5014
5052
  }[]>;
5015
5053
  /**
5016
5054
  * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
@@ -11837,7 +11875,7 @@ declare class BacktestUtils {
11837
11875
  currentPrice: number;
11838
11876
  costBasisAtClose: number;
11839
11877
  entryCountAtClose: number;
11840
- debugTimestamp?: number;
11878
+ timestamp: number;
11841
11879
  }[]>;
11842
11880
  /**
11843
11881
  * Returns the list of DCA entry prices and costs for the current pending signal.
@@ -11863,6 +11901,7 @@ declare class BacktestUtils {
11863
11901
  }) => Promise<{
11864
11902
  price: number;
11865
11903
  cost: number;
11904
+ timestamp: number;
11866
11905
  }[]>;
11867
11906
  /**
11868
11907
  * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
@@ -12958,7 +12997,7 @@ declare class LiveUtils {
12958
12997
  currentPrice: number;
12959
12998
  costBasisAtClose: number;
12960
12999
  entryCountAtClose: number;
12961
- debugTimestamp?: number;
13000
+ timestamp: number;
12962
13001
  }[]>;
12963
13002
  /**
12964
13003
  * Returns the list of DCA entry prices and costs for the current pending signal.
@@ -12983,6 +13022,7 @@ declare class LiveUtils {
12983
13022
  }) => Promise<{
12984
13023
  price: number;
12985
13024
  cost: number;
13025
+ timestamp: number;
12986
13026
  }[]>;
12987
13027
  /**
12988
13028
  * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
@@ -16417,7 +16457,7 @@ declare class NotificationBacktestAdapter implements INotificationUtils {
16417
16457
  * Proxies call to the underlying notification adapter.
16418
16458
  * @param data - The signal sync contract data
16419
16459
  */
16420
- handleSync: (data: SignalSyncContract) => Promise<void>;
16460
+ handleSync: (data: SignalSyncContract) => any;
16421
16461
  /**
16422
16462
  * Handles risk rejection event.
16423
16463
  * Proxies call to the underlying notification adapter.
@@ -16523,7 +16563,7 @@ declare class NotificationLiveAdapter implements INotificationUtils {
16523
16563
  * Proxies call to the underlying notification adapter.
16524
16564
  * @param data - The signal sync contract data
16525
16565
  */
16526
- handleSync: (data: SignalSyncContract) => Promise<void>;
16566
+ handleSync: (data: SignalSyncContract) => any;
16527
16567
  /**
16528
16568
  * Handles risk rejection event.
16529
16569
  * Proxies call to the underlying notification adapter.
@@ -20907,6 +20947,184 @@ declare class BreakevenConnectionService implements IBreakeven {
20907
20947
  clear: (symbol: string, data: IPublicSignalRow, priceClose: number, backtest: boolean) => Promise<void>;
20908
20948
  }
20909
20949
 
20950
+ /**
20951
+ * Service for tracking the latest candle timestamp per symbol-strategy-exchange-frame combination.
20952
+ *
20953
+ * Maintains a memoized BehaviorSubject per unique key that is updated on every strategy tick
20954
+ * by StrategyConnectionService. Consumers can synchronously read the last known timestamp or
20955
+ * await the first value if none has arrived yet.
20956
+ *
20957
+ * Primary use case: providing the current candle time outside of a tick execution context,
20958
+ * e.g., when a command is triggered between ticks.
20959
+ *
20960
+ * Features:
20961
+ * - One BehaviorSubject per (symbol, strategyName, exchangeName, frameName, backtest) key
20962
+ * - Falls back to ExecutionContextService.context.when when called inside an execution context
20963
+ * - Waits up to LISTEN_TIMEOUT ms for the first timestamp if none is cached yet
20964
+ * - clear() disposes the BehaviorSubject for a single key or all keys
20965
+ *
20966
+ * Architecture:
20967
+ * - Registered as singleton in DI container
20968
+ * - Updated by StrategyConnectionService after each tick
20969
+ * - Cleared by Backtest/Live/Walker at strategy start to prevent stale data
20970
+ *
20971
+ * @example
20972
+ * ```typescript
20973
+ * const ts = await backtest.timeMetaService.getTimestamp("BTCUSDT", context, false);
20974
+ * ```
20975
+ */
20976
+ declare class TimeMetaService {
20977
+ private readonly loggerService;
20978
+ private readonly executionContextService;
20979
+ /**
20980
+ * Memoized factory for BehaviorSubject streams keyed by (symbol, strategyName, exchangeName, frameName, backtest).
20981
+ *
20982
+ * Each subject holds the latest createdAt timestamp emitted by the strategy iterator for that key.
20983
+ * Instances are cached until clear() is called.
20984
+ */
20985
+ private getSource;
20986
+ /**
20987
+ * Returns the current candle timestamp (in milliseconds) for the given symbol and context.
20988
+ *
20989
+ * When called inside an execution context (i.e., during a signal handler or action),
20990
+ * reads the timestamp directly from ExecutionContextService.context.when.
20991
+ * Otherwise, reads the last value from the cached BehaviorSubject. If no value has
20992
+ * been emitted yet, waits up to LISTEN_TIMEOUT ms for the first tick before throwing.
20993
+ *
20994
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
20995
+ * @param context - Strategy, exchange, and frame identifiers
20996
+ * @param backtest - True if backtest mode, false if live mode
20997
+ * @returns Unix timestamp in milliseconds of the latest processed candle
20998
+ * @throws When no timestamp arrives within LISTEN_TIMEOUT ms
20999
+ */
21000
+ getTimestamp: (symbol: string, context: {
21001
+ strategyName: string;
21002
+ exchangeName: string;
21003
+ frameName: string;
21004
+ }, backtest: boolean) => Promise<number>;
21005
+ /**
21006
+ * Pushes a new timestamp value into the BehaviorSubject for the given key.
21007
+ *
21008
+ * Called by StrategyConnectionService after each strategy tick to keep
21009
+ * the cached timestamp up to date.
21010
+ *
21011
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
21012
+ * @param timestamp - The createdAt timestamp from the tick (milliseconds)
21013
+ * @param context - Strategy, exchange, and frame identifiers
21014
+ * @param backtest - True if backtest mode, false if live mode
21015
+ */
21016
+ next: (symbol: string, timestamp: number, context: {
21017
+ strategyName: string;
21018
+ exchangeName: string;
21019
+ frameName: string;
21020
+ }, backtest: boolean) => Promise<void>;
21021
+ /**
21022
+ * Disposes cached BehaviorSubject(s) to free memory and prevent stale data.
21023
+ *
21024
+ * When called without arguments, clears all memoized timestamp streams.
21025
+ * When called with a payload, clears only the stream for the specified key.
21026
+ * Should be called at strategy start (Backtest/Live/Walker) to reset state.
21027
+ *
21028
+ * @param payload - Optional key to clear a single stream; omit to clear all
21029
+ */
21030
+ clear: (payload?: {
21031
+ symbol: string;
21032
+ strategyName: string;
21033
+ exchangeName: string;
21034
+ frameName: string;
21035
+ backtest: boolean;
21036
+ }) => void;
21037
+ }
21038
+
21039
+ /**
21040
+ * Service for tracking the latest market price per symbol-strategy-exchange-frame combination.
21041
+ *
21042
+ * Maintains a memoized BehaviorSubject per unique key that is updated on every strategy tick
21043
+ * by StrategyConnectionService. Consumers can synchronously read the last known price or
21044
+ * await the first value if none has arrived yet.
21045
+ *
21046
+ * Primary use case: providing the current price outside of a tick execution context,
21047
+ * e.g., when a command is triggered between ticks.
21048
+ *
21049
+ * Features:
21050
+ * - One BehaviorSubject per (symbol, strategyName, exchangeName, frameName, backtest) key
21051
+ * - Falls back to ExchangeConnectionService.getAveragePrice when called inside an execution context
21052
+ * - Waits up to LISTEN_TIMEOUT ms for the first price if none is cached yet
21053
+ * - clear() disposes the BehaviorSubject for a single key or all keys
21054
+ *
21055
+ * Architecture:
21056
+ * - Registered as singleton in DI container
21057
+ * - Updated by StrategyConnectionService after each tick
21058
+ * - Cleared by Backtest/Live/Walker at strategy start to prevent stale data
21059
+ *
21060
+ * @example
21061
+ * ```typescript
21062
+ * const price = await backtest.priceMetaService.getCurrentPrice("BTCUSDT", context, false);
21063
+ * ```
21064
+ */
21065
+ declare class PriceMetaService {
21066
+ private readonly loggerService;
21067
+ private readonly exchangeConnectionService;
21068
+ /**
21069
+ * Memoized factory for BehaviorSubject streams keyed by (symbol, strategyName, exchangeName, frameName, backtest).
21070
+ *
21071
+ * Each subject holds the latest currentPrice emitted by the strategy iterator for that key.
21072
+ * Instances are cached until clear() is called.
21073
+ */
21074
+ private getSource;
21075
+ /**
21076
+ * Returns the current market price for the given symbol and context.
21077
+ *
21078
+ * When called inside an execution context (i.e., during a signal handler or action),
21079
+ * delegates to ExchangeConnectionService.getAveragePrice for the live exchange price.
21080
+ * Otherwise, reads the last value from the cached BehaviorSubject. If no value has
21081
+ * been emitted yet, waits up to LISTEN_TIMEOUT ms for the first tick before throwing.
21082
+ *
21083
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
21084
+ * @param context - Strategy, exchange, and frame identifiers
21085
+ * @param backtest - True if backtest mode, false if live mode
21086
+ * @returns Current market price in quote currency
21087
+ * @throws When no price arrives within LISTEN_TIMEOUT ms
21088
+ */
21089
+ getCurrentPrice: (symbol: string, context: {
21090
+ strategyName: string;
21091
+ exchangeName: string;
21092
+ frameName: string;
21093
+ }, backtest: boolean) => Promise<number>;
21094
+ /**
21095
+ * Pushes a new price value into the BehaviorSubject for the given key.
21096
+ *
21097
+ * Called by StrategyConnectionService after each strategy tick to keep
21098
+ * the cached price up to date.
21099
+ *
21100
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
21101
+ * @param currentPrice - The latest price from the tick
21102
+ * @param context - Strategy, exchange, and frame identifiers
21103
+ * @param backtest - True if backtest mode, false if live mode
21104
+ */
21105
+ next: (symbol: string, currentPrice: number, context: {
21106
+ strategyName: string;
21107
+ exchangeName: string;
21108
+ frameName: string;
21109
+ }, backtest: boolean) => Promise<void>;
21110
+ /**
21111
+ * Disposes cached BehaviorSubject(s) to free memory and prevent stale data.
21112
+ *
21113
+ * When called without arguments, clears all memoized price streams.
21114
+ * When called with a payload, clears only the stream for the specified key.
21115
+ * Should be called at strategy start (Backtest/Live/Walker) to reset state.
21116
+ *
21117
+ * @param payload - Optional key to clear a single stream; omit to clear all
21118
+ */
21119
+ clear: (payload?: {
21120
+ symbol: string;
21121
+ strategyName: string;
21122
+ exchangeName: string;
21123
+ frameName: string;
21124
+ backtest: boolean;
21125
+ }) => void;
21126
+ }
21127
+
20910
21128
  /**
20911
21129
  * Type definition for strategy methods.
20912
21130
  * Maps all keys of IStrategy to any type.
@@ -20949,6 +21167,8 @@ declare class StrategyConnectionService implements TStrategy$1 {
20949
21167
  readonly partialConnectionService: PartialConnectionService;
20950
21168
  readonly breakevenConnectionService: BreakevenConnectionService;
20951
21169
  readonly actionCoreService: ActionCoreService;
21170
+ readonly timeMetaService: TimeMetaService;
21171
+ readonly priceMetaService: PriceMetaService;
20952
21172
  /**
20953
21173
  * Retrieves memoized ClientStrategy instance for given symbol-strategy pair with exchange and frame isolation.
20954
21174
  *
@@ -21008,36 +21228,139 @@ declare class StrategyConnectionService implements TStrategy$1 {
21008
21228
  exchangeName: ExchangeName;
21009
21229
  frameName: FrameName;
21010
21230
  }) => Promise<number | null>;
21231
+ /**
21232
+ * Returns the effective (DCA-averaged) entry price for the current pending signal.
21233
+ *
21234
+ * This is the harmonic mean of all _entry prices, which is the correct
21235
+ * cost-basis price used in all PNL calculations.
21236
+ * With no DCA entries, equals the original priceOpen.
21237
+ *
21238
+ * Returns null if no pending signal exists.
21239
+ *
21240
+ * @param backtest - Whether running in backtest mode
21241
+ * @param symbol - Trading pair symbol
21242
+ * @param context - Execution context with strategyName, exchangeName, frameName
21243
+ * @returns Promise resolving to effective entry price or null
21244
+ */
21011
21245
  getPositionAveragePrice: (backtest: boolean, symbol: string, context: {
21012
21246
  strategyName: StrategyName;
21013
21247
  exchangeName: ExchangeName;
21014
21248
  frameName: FrameName;
21015
21249
  }) => Promise<number | null>;
21250
+ /**
21251
+ * Returns the number of DCA entries made for the current pending signal.
21252
+ *
21253
+ * 1 = original entry only (no DCA).
21254
+ * Increases by 1 with each successful commitAverageBuy().
21255
+ *
21256
+ * Returns null if no pending signal exists.
21257
+ *
21258
+ * @param backtest - Whether running in backtest mode
21259
+ * @param symbol - Trading pair symbol
21260
+ * @param context - Execution context with strategyName, exchangeName, frameName
21261
+ * @returns Promise resolving to entry count or null
21262
+ */
21016
21263
  getPositionInvestedCount: (backtest: boolean, symbol: string, context: {
21017
21264
  strategyName: StrategyName;
21018
21265
  exchangeName: ExchangeName;
21019
21266
  frameName: FrameName;
21020
21267
  }) => Promise<number | null>;
21268
+ /**
21269
+ * Returns the total invested cost basis in dollars for the current pending signal.
21270
+ *
21271
+ * Equal to entryCount × $100 (COST_BASIS_PER_ENTRY).
21272
+ * 1 entry = $100, 2 entries = $200, etc.
21273
+ *
21274
+ * Returns null if no pending signal exists.
21275
+ *
21276
+ * @param backtest - Whether running in backtest mode
21277
+ * @param symbol - Trading pair symbol
21278
+ * @param context - Execution context with strategyName, exchangeName, frameName
21279
+ * @returns Promise resolving to total invested cost in dollars or null
21280
+ */
21021
21281
  getPositionInvestedCost: (backtest: boolean, symbol: string, context: {
21022
21282
  strategyName: StrategyName;
21023
21283
  exchangeName: ExchangeName;
21024
21284
  frameName: FrameName;
21025
21285
  }) => Promise<number | null>;
21286
+ /**
21287
+ * Returns the unrealized PNL percentage for the current pending signal at currentPrice.
21288
+ *
21289
+ * Accounts for partial closes, DCA entries, slippage and fees
21290
+ * (delegates to toProfitLossDto).
21291
+ *
21292
+ * Returns null if no pending signal exists.
21293
+ *
21294
+ * @param backtest - Whether running in backtest mode
21295
+ * @param symbol - Trading pair symbol
21296
+ * @param currentPrice - Current market price
21297
+ * @param context - Execution context with strategyName, exchangeName, frameName
21298
+ * @returns Promise resolving to pnlPercentage or null
21299
+ */
21026
21300
  getPositionPnlPercent: (backtest: boolean, symbol: string, currentPrice: number, context: {
21027
21301
  strategyName: StrategyName;
21028
21302
  exchangeName: ExchangeName;
21029
21303
  frameName: FrameName;
21030
21304
  }) => Promise<number | null>;
21305
+ /**
21306
+ * Returns the unrealized PNL in dollars for the current pending signal at currentPrice.
21307
+ *
21308
+ * Calculated as: pnlPercentage / 100 × totalInvestedCost
21309
+ * Accounts for partial closes, DCA entries, slippage and fees.
21310
+ *
21311
+ * Returns null if no pending signal exists.
21312
+ *
21313
+ * @param backtest - Whether running in backtest mode
21314
+ * @param symbol - Trading pair symbol
21315
+ * @param currentPrice - Current market price
21316
+ * @param context - Execution context with strategyName, exchangeName, frameName
21317
+ * @returns Promise resolving to pnl in dollars or null
21318
+ */
21031
21319
  getPositionPnlCost: (backtest: boolean, symbol: string, currentPrice: number, context: {
21032
21320
  strategyName: StrategyName;
21033
21321
  exchangeName: ExchangeName;
21034
21322
  frameName: FrameName;
21035
21323
  }) => Promise<number | null>;
21324
+ /**
21325
+ * Returns the list of DCA entry prices for the current pending signal.
21326
+ *
21327
+ * The first element is always the original priceOpen (initial entry).
21328
+ * Each subsequent element is a price added by commitAverageBuy().
21329
+ *
21330
+ * Returns null if no pending signal exists.
21331
+ * Returns a single-element array [priceOpen] if no DCA entries were made.
21332
+ *
21333
+ * @param backtest - Whether running in backtest mode
21334
+ * @param symbol - Trading pair symbol
21335
+ * @param context - Execution context with strategyName, exchangeName, frameName
21336
+ * @returns Promise resolving to array of entry prices or null
21337
+ *
21338
+ * @example
21339
+ * ```typescript
21340
+ * // No DCA: [43000]
21341
+ * // One DCA: [43000, 42000]
21342
+ * // Two DCA: [43000, 42000, 41500]
21343
+ * ```
21344
+ */
21036
21345
  getPositionLevels: (backtest: boolean, symbol: string, context: {
21037
21346
  strategyName: StrategyName;
21038
21347
  exchangeName: ExchangeName;
21039
21348
  frameName: FrameName;
21040
21349
  }) => Promise<number[] | null>;
21350
+ /**
21351
+ * Returns the list of partial closes for the current pending signal.
21352
+ *
21353
+ * Each entry records a partial profit or loss close event with its type,
21354
+ * percent closed, price at close, cost basis snapshot, and entry count at close.
21355
+ *
21356
+ * Returns null if no pending signal exists.
21357
+ * Returns an empty array if no partial closes have been executed.
21358
+ *
21359
+ * @param backtest - Whether running in backtest mode
21360
+ * @param symbol - Trading pair symbol
21361
+ * @param context - Execution context with strategyName, exchangeName, frameName
21362
+ * @returns Promise resolving to array of partial close records or null
21363
+ */
21041
21364
  getPositionPartials: (backtest: boolean, symbol: string, context: {
21042
21365
  strategyName: StrategyName;
21043
21366
  exchangeName: ExchangeName;
@@ -21048,8 +21371,29 @@ declare class StrategyConnectionService implements TStrategy$1 {
21048
21371
  currentPrice: number;
21049
21372
  costBasisAtClose: number;
21050
21373
  entryCountAtClose: number;
21051
- debugTimestamp?: number;
21374
+ timestamp: number;
21052
21375
  }[]>;
21376
+ /**
21377
+ * Returns the list of DCA entry prices and costs for the current pending signal.
21378
+ *
21379
+ * Each entry records the price and cost of a single position entry.
21380
+ * The first element is always the original priceOpen (initial entry).
21381
+ * Each subsequent element is an entry added by averageBuy().
21382
+ *
21383
+ * Returns null if no pending signal exists.
21384
+ * Returns a single-element array [{ price: priceOpen, cost }] if no DCA entries were made.
21385
+ *
21386
+ * @param backtest - Whether running in backtest mode
21387
+ * @param symbol - Trading pair symbol
21388
+ * @param context - Execution context with strategyName, exchangeName, frameName
21389
+ * @returns Promise resolving to array of entry records or null
21390
+ *
21391
+ * @example
21392
+ * ```typescript
21393
+ * // No DCA: [{ price: 43000, cost: 100 }]
21394
+ * // One DCA: [{ price: 43000, cost: 100 }, { price: 42000, cost: 100 }]
21395
+ * ```
21396
+ */
21053
21397
  getPositionEntries: (backtest: boolean, symbol: string, context: {
21054
21398
  strategyName: StrategyName;
21055
21399
  exchangeName: ExchangeName;
@@ -21057,6 +21401,7 @@ declare class StrategyConnectionService implements TStrategy$1 {
21057
21401
  }) => Promise<{
21058
21402
  price: number;
21059
21403
  cost: number;
21404
+ timestamp: number;
21060
21405
  }[]>;
21061
21406
  /**
21062
21407
  * Retrieves the currently active scheduled signal for the strategy.
@@ -22301,7 +22646,7 @@ declare class StrategyCoreService implements TStrategy {
22301
22646
  currentPrice: number;
22302
22647
  costBasisAtClose: number;
22303
22648
  entryCountAtClose: number;
22304
- debugTimestamp?: number;
22649
+ timestamp: number;
22305
22650
  }[]>;
22306
22651
  getPositionEntries: (backtest: boolean, symbol: string, context: {
22307
22652
  strategyName: StrategyName;
@@ -22310,6 +22655,7 @@ declare class StrategyCoreService implements TStrategy {
22310
22655
  }) => Promise<{
22311
22656
  price: number;
22312
22657
  cost: number;
22658
+ timestamp: number;
22313
22659
  }[]>;
22314
22660
  /**
22315
22661
  * Retrieves the currently active scheduled signal for the symbol.
@@ -25328,6 +25674,8 @@ declare const backtest: {
25328
25674
  riskGlobalService: RiskGlobalService;
25329
25675
  partialGlobalService: PartialGlobalService;
25330
25676
  breakevenGlobalService: BreakevenGlobalService;
25677
+ timeMetaService: TimeMetaService;
25678
+ priceMetaService: PriceMetaService;
25331
25679
  exchangeCoreService: ExchangeCoreService;
25332
25680
  strategyCoreService: StrategyCoreService;
25333
25681
  actionCoreService: ActionCoreService;