--- title: private/interfaces group: private --- # backtest-kit api reference ![schema](../../assets/uml.svg) **Overview:** Backtest-kit is a production-ready TypeScript framework for backtesting and live trading strategies with crash-safe state persistence, signal validation, and memory-optimized architecture. The framework follows clean architecture principles with dependency injection, separation of concerns, and type-safe discriminated unions. **Core Concepts:** * **Signal Lifecycle:** Type-safe state machine (idle → opened → active → closed) with discriminated unions * **Execution Modes:** Backtest mode (historical data) and Live mode (real-time with crash recovery) * **VWAP Pricing:** Volume Weighted Average Price from last 5 1-minute candles for all entry/exit decisions * **Signal Validation:** Comprehensive validation ensures TP/SL logic, positive prices, and valid timestamps * **Interval Throttling:** Prevents signal spam with configurable intervals (1m, 3m, 5m, 15m, 30m, 1h) * **Crash-Safe Persistence:** Atomic file writes with automatic state recovery for live trading * **Async Generators:** Memory-efficient streaming for backtest and live execution * **Accurate PNL:** Calculation with fees (0.1%) and slippage (0.1%) for realistic simulations * **Event System:** Signal emitters for backtest/live/global signals, errors, and completion events * **Graceful Shutdown:** Live.background() waits for open positions to close before stopping * **Pluggable Persistence:** Custom adapters for Redis, MongoDB, or any storage backend **Architecture Layers:** * **Client Layer:** Pure business logic without DI (ClientStrategy, ClientExchange, ClientFrame) using prototype methods for memory efficiency * **Service Layer:** DI-based services organized by responsibility: * **Schema Services:** Registry pattern for configuration with shallow validation (StrategySchemaService, ExchangeSchemaService, FrameSchemaService) * **Validation Services:** Runtime existence validation with memoization (StrategyValidationService, ExchangeValidationService, FrameValidationService) * **Connection Services:** Memoized client instance creators (StrategyConnectionService, ExchangeConnectionService, FrameConnectionService) * **Global Services:** Context wrappers for public API (StrategyGlobalService, ExchangeGlobalService, FrameGlobalService) * **Logic Services:** Async generator orchestration (BacktestLogicPrivateService, LiveLogicPrivateService) * **Markdown Services:** Auto-generated reports with tick-based event log (BacktestMarkdownService, LiveMarkdownService) * **Persistence Layer:** Crash-safe atomic file writes with PersistSignalAdaper, extensible via PersistBase * **Event Layer:** Subject-based emitters (signalEmitter, errorEmitter, doneEmitter) with queued async processing **Key Design Patterns:** * **Discriminated Unions:** Type-safe state machines without optional fields * **Async Generators:** Stream results without memory accumulation, enable early termination * **Dependency Injection:** Custom DI container with Symbol-based tokens * **Memoization:** Client instances cached by schema name using functools-kit * **Context Propagation:** Nested contexts using di-scoped (ExecutionContext + MethodContext) * **Registry Pattern:** Schema services use ToolRegistry for configuration management * **Singleshot Initialization:** One-time operations with cached promise results * **Persist-and-Restart:** Stateless process design with disk-based state recovery * **Pluggable Adapters:** PersistBase as base class for custom storage backends * **Queued Processing:** Sequential event handling with functools-kit queued wrapper **Data Flow (Backtest):** 1. User calls Backtest.background(symbol, context) or Backtest.run(symbol, context) 2. Validation services check strategyName, exchangeName, frameName existence 3. BacktestLogicPrivateService.run(symbol) creates async generator with yield 4. MethodContextService.runInContext sets strategyName, exchangeName, frameName 5. Loop through timeframes, call StrategyGlobalService.tick() 6. ExecutionContextService.runInContext sets symbol, when, backtest=true 7. ClientStrategy.tick() checks VWAP against TP/SL conditions 8. If opened: fetch candles and call ClientStrategy.backtest(candles) 9. Yield closed result and skip timeframes until closeTimestamp 10. Emit signals via signalEmitter, signalBacktestEmitter 11. On completion emit doneEmitter with { backtest: true, symbol, strategyName, exchangeName } **Data Flow (Live):** 1. User calls Live.background(symbol, context) or Live.run(symbol, context) 2. Validation services check strategyName, exchangeName existence 3. LiveLogicPrivateService.run(symbol) creates infinite async generator with while(true) 4. MethodContextService.runInContext sets schema names 5. Loop: create when = new Date(), call StrategyGlobalService.tick() 6. ClientStrategy.waitForInit() loads persisted signal state from PersistSignalAdaper 7. ClientStrategy.tick() with interval throttling and validation 8. setPendingSignal() persists state via PersistSignalAdaper.writeSignalData() 9. Yield opened and closed results, sleep(TICK_TTL) between ticks 10. Emit signals via signalEmitter, signalLiveEmitter 11. On stop() call: wait for lastValue?.action === 'closed' before breaking loop (graceful shutdown) 12. On completion emit doneEmitter with { backtest: false, symbol, strategyName, exchangeName } **Event System:** * **Signal Events:** listenSignal, listenSignalBacktest, listenSignalLive for tick results (idle/opened/active/closed) * **Error Events:** listenError for background execution errors (Live.background, Backtest.background) * **Completion Events:** listenDone, listenDoneOnce for background execution completion with DoneContract * **Queued Processing:** All listeners use queued wrapper from functools-kit for sequential async execution * **Filter Predicates:** Once listeners (listenSignalOnce, listenDoneOnce) accept filter function for conditional triggering **Performance Optimizations:** * Memoization of client instances by schema name * Prototype methods (not arrow functions) for memory efficiency * Fast backtest method skips individual ticks * Timeframe skipping after signal closes * VWAP caching per tick/candle * Async generators stream without array accumulation * Interval throttling prevents excessive signal generation * Singleshot initialization runs exactly once per instance * LiveMarkdownService bounded queue (MAX_EVENTS = 25) prevents memory leaks * Smart idle event replacement (only replaces if no open/active signals after last idle) **Use Cases:** * Algorithmic trading with backtest validation and live deployment * Strategy research and hypothesis testing on historical data * Signal generation with ML models or technical indicators * Portfolio management tracking multiple strategies across symbols * Educational projects for learning trading system architecture * Event-driven trading bots with real-time notifications (Telegram, Discord, email) * Multi-exchange trading with pluggable exchange adapters **Test Coverage:** The framework includes comprehensive unit tests using worker-testbed (tape-based testing): * **exchange.test.mjs:** Tests exchange helper functions (getCandles, getAveragePrice, getDate, getMode, formatPrice, formatQuantity) with mock candle data and VWAP calculations * **event.test.mjs:** Tests Live.background() execution and event listener system (listenSignalLive, listenSignalLiveOnce, listenDone, listenDoneOnce) for async coordination * **validation.test.mjs:** Tests signal validation logic (valid long/short positions, invalid TP/SL relationships, negative price detection, timestamp validation) using listenError for error handling * **pnl.test.mjs:** Tests PNL calculation accuracy with realistic fees (0.1%) and slippage (0.1%) simulation * **backtest.test.mjs:** Tests Backtest.run() and Backtest.background() with signal lifecycle verification (idle → opened → active → closed), listenDone events, early termination, and all close reasons (take_profit, stop_loss, time_expired) * **callbacks.test.mjs:** Tests strategy lifecycle callbacks (onOpen, onClose, onTimeframe) with correct parameter passing, backtest flag verification, and signal object integrity * **report.test.mjs:** Tests markdown report generation (Backtest.getReport, Live.getReport) with statistics validation (win rate, average PNL, total PNL, closed signals count) and table formatting All tests follow consistent patterns: * Unique exchange/strategy/frame names per test to prevent cross-contamination * Mock candle generator (getMockCandles.mjs) with forward timestamp progression * createAwaiter from functools-kit for async coordination * Background execution with Backtest.background() and event-driven completion detection # backtest-kit interfaces ## Interface WalkerStopContract This interface defines a signal event that occurs when a trading walker needs to be stopped, often during backtesting or simulations. It's used to interrupt a running walker and strategy. The signal includes details such as the trading symbol involved (like "BTCUSDT"), the specific name of the strategy to halt, and the walker's name, allowing for targeted stops when multiple walkers are active. Importantly, these stop signals are exclusively used within a backtesting environment. The `when` property records the virtual time of the strategy at the point of interruption, based on the candle data processed – it's not real-world time. ## Interface WalkerStatisticsModel This interface, WalkerStatisticsModel, is designed to hold the results of a backtesting process, providing a clear way to organize and understand the performance of different strategies. It builds upon the existing IWalkerResults interface and adds extra details specifically for comparing strategies against each other. The core of this model is the strategyResults property, which is a list containing all the results generated during the backtest—allowing you to see how each strategy performed. ## Interface WalkerContract The WalkerContract defines what happens as your trading strategies are being compared against each other. Think of it as a report card delivered at the end of each strategy’s test run. Each time a strategy finishes its backtest, this contract provides a snapshot of the results. You'll find information like the strategy's name, the exchange and symbol being used, and detailed performance statistics. It also keeps track of the overall progress of the strategy comparison, including the current best-performing strategy and how many strategies have been tested. The `when` property tells you when the test happened within the simulation – it's not actual time, but rather the time of the last candle processed. This is useful for understanding the sequence of events. The `backtest` flag simply confirms that the information comes from a backtest. ## Interface WalkerCompleteContract This contract, `WalkerCompleteContract`, signals the conclusion of a backtesting process for a set of trading strategies. It's triggered when all strategies have been evaluated and the final results are ready. Think of it as a notification saying, "We're done testing these strategies!" The contract bundles together important information about the backtest, including the name of the walker (the testing process), the symbol being traded, the exchange and timeframe used, the optimization metric, and the number of strategies tested. It also highlights the best-performing strategy, its metric score, and detailed statistics. Crucially, this event is exclusive to backtesting operations and includes a timestamp representing the last candle processed during the entire backtest, not a real-world time. ## Interface ValidationErrorNotification This notification signals that a validation error occurred during your trading strategy's setup or execution. It's designed to help you pinpoint and fix issues related to risk checks and constraints. The notification includes a unique identifier, a detailed error object (complete with a stack trace to help with debugging), and a clear, human-readable explanation of what went wrong. The `backtest` flag will always be false, indicating that the error originated from your live trading context rather than a simulation. Use this information to understand and resolve any problems with your validation rules. ## Interface ValidateArgs This interface, `ValidateArgs`, acts like a central blueprint for making sure the names of things – like exchanges, timeframes, strategies, risk profiles, actions, sizing methods, and parameter sweeps – are all valid within your backtesting setup. Think of it as a quality control check. Each property within `ValidateArgs` represents one of these names, and they all follow the same pattern: they expect an enum object. This enum object holds the permissible values for that particular name (e.g., what valid exchange names exist in your system). The backtest-kit uses this to verify that you're using recognized names and avoid errors. It makes sure everything aligns and works together correctly. ## Interface TrailingTakeCommitNotification This notification tells you when a trailing take profit order has been executed. It provides a wealth of information about the trade, including when it happened, the trading pair involved, and whether it occurred during a backtest or live trading. You'll find details about the original take profit and stop loss levels, the current price at execution, and key performance metrics like peak profit and maximum drawdown. The notification breaks down the trade's financials, detailing costs, multipliers, and the total number of entries and partial closures. It also gives you a complete picture of the position’s P&L, including entry and exit prices and percentages. A helpful 'note' field allows for a more descriptive explanation of the trade's reasoning. Timestamps are included for creation, scheduling, pending, and execution, enabling a full timeline of the trade's lifecycle. ## Interface TrailingTakeCommit This interface describes a trailing take event, which happens when a trading strategy adjusts a take profit level based on price movement. It contains details about the event itself, including confirmation that it's a "trailing-take" action. You’ll find information about how much the take profit was adjusted by, the current price when the adjustment occurred, and the overall profit and loss (pnl) achieved so far for this trade. The record also provides insight into the trade's performance, showing the highest profit attained (peak profit), the largest loss experienced (max drawdown), and whether the original trade was a long (buy) or short (sell) position. Crucially, it includes the initial take profit and stop loss prices, along with any adjustments made through trailing, and timestamps indicating when the signal was created and the position activated. This data is essential for understanding the progression and performance of a trailing take profit strategy. ## Interface TrailingStopCommitNotification This notification signals that a trailing stop has been triggered and a trade has been executed. It provides detailed information about the trade, including a unique identifier, the timestamp of the event, and whether it occurred during a backtest or live trading. You'll find specifics about the trading pair, the strategy used, and the exchange involved. The notification includes key price points like the entry price, take profit, and stop-loss levels, both original and adjusted by the trailing stop. It also breaks down the cost of the trade and details the position size. Furthermore, it gives you a comprehensive picture of the trade’s performance with metrics like profit and loss, peak profit, maximum drawdown, and associated prices and costs. It also captures details like the number of entries and partial closes and gives extra notes if provided. Finally, there are timestamps to track when the signal was scheduled, went pending, and when this notification was generated. ## Interface TrailingStopCommit This describes a trailing stop event within the backtest-kit framework, specifically when a trailing stop mechanism triggers a trade. It contains all the details about what happened during that event. The `action` property confirms that this is indeed a trailing stop event. The `percentShift` tells you the percentage used to adjust the stop loss. You'll find the `currentPrice` which is the market price when the trailing stop adjustment occurred, along with the `pnl` representing the total profit or loss for the closed position. Also provided is the `peakProfit` and `maxDrawdown` to see the best and worst performance of the position so far. The `position` property specifies if it's a long (buy) or short (sell) trade. Further details include the initial `priceOpen` (entry price), the `priceTakeProfit` and `priceStopLoss` (which might have changed due to trailing), their original values (`originalPriceTakeProfit`, `originalPriceStopLoss`), the `scheduledAt` timestamp of the signal, and the `pendingAt` timestamp when the position became active. ## Interface TickEvent This describes a standardized way to represent events happening within the trading system, like when a trade is scheduled, opened, closed, or cancelled. The `TickEvent` object bundles all the relevant details about a single event into one place, making it easier to generate reports and analyze trading activity. Think of it as a comprehensive record of what happened and when, including price data, order details like take profit and stop loss levels, and performance metrics like profit and loss. Different event types (like "scheduled", "opened", or "closed") have different sets of properties that are relevant to that specific stage of the trading process. It also includes information about averaging (DCA) and partial closes. ## Interface SyncStatisticsModel This model holds statistics about sync events within your trading system. Think of it as a way to monitor the lifecycle of your signals. You'll find a detailed list of individual sync events in the `eventList` property, allowing you to examine each one closely. The `totalEvents` property tells you just how many sync events have occurred. Separate counts of signal openings (`openCount`) and signal closures (`closeCount`) are also provided, giving you insights into signal activity. ## Interface SyncEvent This data structure holds all the key information about events that happen during a trading signal's lifecycle, particularly useful for creating reports. It includes details like the exact time of the event (timestamp), the trading pair involved (symbol), which strategy was used (strategyName), and where the trade took place (exchangeName). You'll find information about the signal itself, such as a unique identifier (signalId) and the specific action that occurred (action). Crucially, it captures pricing information – the current market price, the entry price (priceOpen), and any take profit or stop loss levels, both as initially set and after any adjustments. The data also tracks information related to dollar-cost averaging (DCA) through entries and partial closes, and provides a performance snapshot, including total profit and loss (pnl), peak profit, and maximum drawdown. It will tell you why a signal was closed (closeReason) and whether the event is part of a backtest. Finally, it holds the time when the signal was created and when it started (scheduledAt, pendingAt) and when the event was actually created (createdAt). ## Interface StrategyStatisticsModel This model holds the statistics generated during a strategy backtest. It allows you to easily track various actions your strategy took, such as canceling scheduled orders, closing pending orders, or adjusting positions with partial profits or losses. You'll find a comprehensive list of events in the `eventList` property, providing details for each action. The model also gives you aggregate counts for different event types, like trailing stops, breakeven adjustments, and average buy orders, providing a quick overview of your strategy's behavior. It's like a scorecard summarizing what your strategy did during the backtest. ## Interface StrategyPauseNotification This notification lets you know when a trading strategy has been paused or resumed. When a strategy is paused, it stops opening new trades, but any existing trades still being managed continue as normal. The `type` property confirms it's a pause notification, while `id` gives it a unique identifier. You’ll find essential details like the timestamp of the change, whether it happened during a backtest or live trading, the trading pair involved (like BTCUSDT), the name of the strategy, the exchange used, and the frame used for trading. Critically, the `paused` property tells you the current pause state – true means paused, and false means resumed – and `createdAt` provides the notification’s creation timestamp. ## Interface StrategyEvent This object holds all the details about events that happen within your trading strategy, like when a trade is opened, closed, or modified. It's designed to provide a complete record of what's happening so you can understand and analyze your strategy's performance. Each event includes information like the exact time it occurred, the trading pair involved, the name of the strategy, and the exchange used. You'll also find specifics about the trade itself – whether it's a long or short position, the entry price, and any take profit or stop loss levels that are in effect, showing both the initially set and the currently adjusted prices. For strategies using dollar-cost averaging (DCA), it tracks entries and partials, along with the running profit and loss. There’s even a field to add notes, which allows you to record any relevant context about the event. It's particularly useful for backtesting, but also relevant for live trading, as it clearly distinguishes between backtest and live modes. ## Interface SignalScheduledNotification This notification tells you about a signal that's been set up to execute in the future. It's like a heads-up that a trade is going to happen, whether you're running a backtest or live trading. Each notification has a unique identifier, a timestamp indicating when the signal was scheduled, and details about whether it's a backtest or live trade. You'll find details like the trading symbol (e.g., BTCUSDT), the strategy that generated the signal, and which exchange it will be executed on. It also includes the specifics of the trade itself: the position (long or short), target entry price, take profit, and stop loss levels. Beyond the basics, you'll also get information on potential trailing adjustments to take profit and stop loss, original prices, the number of entries and partial closes, the cost of the trade, and leverage details. The notification also provides a wealth of performance metrics related to this signal, including total profit/loss (in USD and percentage), peak profit, maximum drawdown, and associated prices and entry counts. Finally, a 'note' field allows for optional descriptive text related to the signal's reasoning. ## Interface SignalOpenedNotification This notification signals the opening of a new trading position. It provides a wealth of information about the trade, including a unique identifier and a timestamp indicating when it happened. You'll find details like whether it's a backtest or live trade, which exchange and strategy were involved, and the direction of the trade (long or short). The notification outlines crucial price points – the entry price, take profit, and stop loss – along with their original values before any adjustments like trailing stops. It also includes details about any DCA averaging or partial closes that occurred. Beyond the basic trade details, it delves into performance metrics like total profit and loss (PNL), maximum drawdown, and peak profit. Each of these metrics is broken down further, offering insights into the price levels and entry counts associated with these key events. Finally, the notification contains optional notes and timestamps related to the signal’s scheduling, pending, and creation. It’s a comprehensive record of a trading position's initiation, useful for tracking performance and analyzing trading behavior. ## Interface SignalInfoNotification This framework provides a way for trading strategies to share informational updates about open positions. When a strategy generates a note – essentially a helpful message about what’s happening – this notification structure carries all the details. It includes everything from the strategy's name and the exchange being used to key details like the entry price, take profit levels, stop-loss orders, and the current market price. You'll also find performance metrics within the notification, like peak profit, maximum drawdown, and overall profit/loss, broken down into percentages and USD values. It provides a comprehensive snapshot of the position's history and performance, including data about DCA entries and partial closes. Each notification has a unique identifier and a timestamp, making it easy to track and reference. The framework also indicates whether the signal originated from a backtest or live trading environment, helping with analysis and debugging. Finally, there’s a field for custom notes provided by the strategy, along with an optional user-defined ID for linking to external systems. ## Interface SignalInfoContract This defines how information signals are communicated within the trading framework. When a strategy wants to share a custom message related to an open trade, it uses this structure to broadcast that information. The signal includes details like the trading symbol, the name of the strategy generating the signal, the exchange being used, and the frame it's running in. You’ll also find important data points like the original signal prices, the current market price, and a note that the strategy can provide. A unique identifier helps link signals to external systems, and a flag indicates whether the signal originated from a backtest or live trading session. Finally, a timestamp and `Date` object pinpoint exactly when the event occurred, representing either the virtual time during backtesting or the real-time clock during live execution. It's essentially a structured notification system for strategies to communicate details about their actions. ## Interface SignalEventContract This interface describes events related to pending trading signals, specifically when a position is opened or closed. It allows you to track the lifecycle of a signal without needing to monitor the entire signal stream. The events are triggered during the backtesting or live trading process. They provide information about the signal's action (opened or closed), the trading symbol, the strategy managing the signal, the exchange used, and the timeframe. You'll receive this data when a new position is initiated or an existing one is closed, covering various scenarios like take-profit, stop-loss, time expiration, user actions, or broker fills. The `data` property offers comprehensive details about the signal, including entry and exit prices, and potential profit/loss. When a position closes, the `closeReason` property explains why it was closed. The `currentPrice` indicates the effective price at the time of the event. You also get information regarding whether the event occurred during a backtest or live execution and the exact timestamp of the event. ## Interface SignalData$1 This interface, `SignalData`, helps organize the data used to track performance during backtesting. It describes a single trading signal that has already been closed. Each `SignalData` object contains details like the strategy that created it, a unique ID for the signal, the symbol being traded (like BTC/USDT), whether it was a long or short position, and the percentage profit or loss (PNL). You’ll also find information about why the signal closed and the times it was opened and closed. Essentially, it’s a snapshot of a completed trade for analysis. ## Interface SignalCommitBase This defines the common information shared by all signal commit events within the backtest kit. Every signal event, whether it's part of a backtest or a live trading session, will include details like the trading pair symbol, the name of the strategy that generated the signal, the exchange used, and the timeframe involved. You'll also find information about whether the event came from a backtest (allowing for historical simulation) or live trading, a unique ID for the signal, and the precise time it occurred. Beyond that, the event tracks the number of entries and partial closes executed, the original entry price, the signal’s data at that moment, and an optional note for human explanation of the signal’s reasoning. This base structure ensures consistent and understandable reporting across all signal events. ## Interface SignalClosedNotification This notification signals that a trading position has been closed, whether it was due to hitting a take profit or stop loss, or some other reason. It provides a ton of details about the closed trade, including when it happened, whether it was a backtest or live trade, and which strategy was responsible. You'll find information about the symbol traded, the entry and exit prices, and the original target prices set for profit and loss. The notification also breaks down the details of any DCA (Dollar-Cost Averaging) used, and any partial closes executed. Beyond the basic metrics like profit/loss and cost, it also tracks peak profit and maximum drawdown, offering insights into the trade's performance throughout its lifecycle. Finally, it includes timestamps for key events – creation, pending, and closure – and a reason for why the position was closed. ## Interface SignalCancelledNotification This notification indicates that a trading signal was cancelled before it could be activated. It provides a wealth of information about the signal and the circumstances surrounding its cancellation, including a unique identifier, the time it was cancelled, and whether it occurred during a backtest or live trading. You'll find details about the intended trade – its direction (long or short), target prices (take profit and stop loss), and original entry price – along with information about costs, leverage, and DCA averaging if it was used. The notification also includes key performance indicators (KPIs) like P&L, peak profit, and maximum drawdown, although these are typically zero values for a cancelled signal. A `cancelReason` field explains why the signal was cancelled, whether it was due to a timeout, price rejection, or user intervention. Finally, it contains details about the signal's scheduling timeline, including when it was created and when it was intended to be active, alongside an optional note for added context. This comprehensive data enables you to understand why a signal wasn't executed and identify potential issues with your trading strategy. ## Interface Signal The `Signal` object holds information about a single trading signal generated during a backtest. It includes the opening price at which the position was initiated. You'll also find a record of all entry points, detailing each entry's price, associated cost, and the time it occurred. Additionally, a history of partial exits is tracked, listing details like whether it was a profit or loss, the percentage of the position closed, the closing price at the time of the partial exit, the cost basis at that time, the number of shares/contracts at the time, and the timestamp. ## Interface Signal$3 This section describes the `Signal$3` object, which is a core component of the backtest-kit framework. It represents a trading signal and tracks key information about a position. The `priceOpen` property simply holds the initial price at which the position was opened. The `_entry` array stores a record of each entry made within the position, detailing the price, total cost, and the timestamp of the entry. Finally, `_partial` logs any partial exits from the position, noting the type (profit or loss), percentage of position closed, closing price, cost basis at the time of closure, the number of units held at closure, and the associated timestamp. ## Interface Signal$2 The `Signal$2` object keeps track of information related to a trading signal's execution. It holds the initial entry price for the position, allowing you to easily reference the starting point of the trade. You'll also find a record of all entry events, detailing each time the signal triggered a position opening, including the price, cost, and timestamp. Finally, it tracks any partial exits or adjustments made to the position, noting the type (profit or loss), percentage, current price, cost basis, entry count, and timestamp of each event. This gives you a full history of how the signal’s position evolved over time. ## Interface Signal$1 This `Signal` object holds key information about a trading position. It tracks the initial entry price of the trade using the `priceOpen` property, a simple number representing that value. The `_entry` property is an array that logs every instance of when a position was initiated, detailing the price, associated cost, and the time of the entry. For partial exits, the `_partial` property keeps a record of when and why a portion of the position was closed, including metrics like the profit/loss type, percentage, current price, cost basis, entry count, and timestamp. ## Interface ScheduledEvent The `ScheduledEvent` object provides a consolidated view of trading events, whether they were scheduled, opened, or cancelled. It's designed to be a central source of information when you're generating reports about your trading activity. Each event record includes details like when it happened (timestamp), what type of event it was (scheduled, cancelled, or opened), the trading pair involved (symbol), and a unique identifier for the signal (signalId). You’ll also find important price points, like the intended entry price (priceOpen), take profit level (priceTakeProfit), and stop loss level (priceStopLoss), as well as their original values before any adjustments. For events involving multiple entries (like a DCA strategy), the total number of entries and partial closes are included. It also tracks unrealized profit and loss (pnl), and additional information such as reason for cancellation and duration. Finally, the timestamp when the position became active or was created (scheduledAt) is also available. ## Interface ScheduleStatisticsModel This model holds key statistics related to signals that are scheduled for future execution. Think of it as a report card for your scheduled trading strategies. It breaks down the data into several categories: * **eventList:** A comprehensive list of every scheduled event, including when it was planned, executed, or cancelled. * **totalEvents:** The overall number of scheduled events, encompassing all stages. * **totalScheduled:** Simply, the total number of signals you’ve scheduled. * **totalOpened:** The number of signals that have actually been activated from those scheduled. * **totalCancelled:** The count of signals that were cancelled before activation. The model also calculates important performance indicators: * **cancellationRate:** A percentage representing how often scheduled signals are cancelled; a lower rate is generally desirable. * **activationRate:** A percentage reflecting how often scheduled signals are successfully activated; a higher rate is better. * **avgWaitTime:** The average time (in minutes) that cancelled signals waited before being cancelled. * **avgActivationTime:** The average time (in minutes) that signals waited before being activated. ## Interface SchedulePingContract This describes the data you receive when a scheduled signal is actively being monitored. Think of it as a regular check-in event that happens roughly every minute while a signal is live. It provides details about the signal itself - the trading pair, the strategy using it, the exchange it's connected to, and the timeframe it applies to. You’ll also see the full data associated with that signal, including things like entry price, take profit, and stop loss levels. Importantly, it includes the current market price at the time of the ping, and tells you whether this is a backtest (historical data) or live trading situation. The `when` property contains the exact time of the ping, which is critical for understanding the context of the event, especially in backtest mode. This allows you to build custom logic to manage or react to signals based on these recurring updates. ## Interface ScheduleEventContract This contract helps you keep track of when signals are scheduled and cancelled within the trading framework, without needing to watch every signal. It’s like a notification system specifically for signals that are waiting to be activated or have been removed before activation. You can use this to know when a signal is being prepared or when one is being discarded – for example, if it timed out or was manually cancelled. The events are triggered during backtesting or live trading and contain detailed information about the signal: * Which symbol it relates to (e.g., BTCUSDT). * The strategy that created it. * The exchange and timeframe. * All the details of the signal itself, like its price levels and position size. * If the signal was cancelled, you'll also know why. The timing of these events depends on whether you're backtesting (based on the candle’s timestamp) or live trading (based on the real-time clock). This allows your code to react to the scheduling or cancellation of signals in a controlled way. ## Interface RiskStatisticsModel This model holds statistics about risk rejections, helping you understand where your risk management is triggered. It contains a complete list of the risk rejection events themselves. You’ll also find the total count of rejections, and breakdowns of those rejections organized by the symbols involved and the strategies that caused them. This lets you quickly pinpoint areas needing attention in your trading system. ## Interface RiskRejectionNotification This notification lets you know when a trading signal was blocked by your risk management rules. It's a heads-up that something prevented a trade from happening. The notification includes details like the unique ID of the rejected signal, when it occurred, and whether it was during a backtest or live trading. You'll see the trading pair involved (like BTCUSDT), the name of the strategy that tried to execute the trade, and the exchange where it was rejected. Crucially, it explains *why* the signal was rejected with a human-readable reason. Additional information like the number of open positions, the current market price, and details about the proposed trade (entry price, take profit, stop loss) are also provided. If a signal had specific notes attached, they'll be included too, along with the creation timestamp of the rejection notification itself. ## Interface RiskEvent This data structure holds information about signals that were blocked due to risk management rules. It's designed to help you understand *why* a trade didn't happen. Each `RiskEvent` includes details like when the event occurred (`timestamp`), the trading pair involved (`symbol`), the specific signal that was rejected (`currentSignal`), and the name of the strategy and exchange that generated it. You'll also find the current market price at the time of the rejection, how many other positions the strategy held, and a unique ID to track each rejection. A note explains the reason for the rejection, and a flag indicates whether the event happened during backtesting or live trading. ## Interface RiskContract The RiskContract represents a signal that was blocked due to risk validation. It's a record of when a trading signal couldn't be executed because it violated a defined risk limit. This record includes vital details like the trading pair involved (symbol), the specifics of the signal itself (currentSignal), which strategy tried to execute it (strategyName), and the timeframe it was associated with (frameName). You'll also find information about the exchange, the current market price, and the total number of open positions at the time. Each rejection has a unique ID (rejectionId) and a human-readable explanation (rejectionNote) for why it was rejected. A timestamp and corresponding Date object (when) indicate precisely when the rejection occurred. Finally, a flag (backtest) specifies whether the event happened during a backtest or in live trading. This information is valuable for risk management reports and allows users to understand and monitor rejected trading signals. ## Interface ProgressWalkerContract The ProgressWalkerContract represents updates on the status of a background process, like when running a large number of trading strategies. It gives you insights into what's happening behind the scenes. You'll find details like the name of the process, the exchange and frame being used, and the specific trading symbol involved. The contract shows how many strategies are being considered overall, how many have already been processed, and the percentage of completion. Importantly, these progress updates are exclusive to backtesting scenarios. The `when` property provides a virtual timestamp reflecting the timing of the processed trading data. This isn't actual clock time, but rather a reference point in the backtest timeline. ## Interface ProgressBacktestContract This interface provides updates on the progress of a backtest. It’s designed to give you insights into how far along the backtesting process is, offering details like the exchange and strategy being used, the trading symbol, and the total number of historical data points being analyzed. You’ll see the number of data points already processed and a percentage indicating overall completion. Importantly, the `when` property tells you the virtual time associated with the current progress point, showing the timeframe being evaluated. This helps you understand the context of the progress event within the backtest timeline. ## Interface PerformanceStatisticsModel This model holds performance statistics gathered from a trading strategy. It allows you to see how a strategy performed, broken down by different metrics. You'll find the strategy's name clearly labeled, along with the total number of performance events that were tracked and the overall time it took to gather those statistics. The `metricStats` property organizes performance data into groups based on metric type, providing a more structured view. Finally, a list of all individual performance events, with their raw data, is available for in-depth analysis. ## Interface PerformanceContract The PerformanceContract helps you keep an eye on how your trading strategies are performing. It's like a detailed log that records important events during the trading process. Each entry in this log includes the exact time the event happened (both as a numerical timestamp and a readable date), as well as the time of the bar or tick being processed. It also specifies what kind of operation was being done (like order placement or data fetching), how long it took to complete, and which strategy, exchange, and symbol were involved. You can use this information to identify where your system might be slow or inefficient. The PerformanceContract also tells you whether the data comes from a backtest simulation or a live trading session. ## Interface PauseContract This interface describes events that happen when a trading strategy is paused or resumed. It provides information about when a strategy stops or starts making trades, allowing you to inform users about these changes. The event includes details like the trading symbol involved, whether the strategy is now paused or running again, and the exact time of the change. You'll also find the name of the strategy, the exchange it's using, and the timeframe of the data. Finally, a flag indicates whether this event is part of a historical simulation (backtest) or live trading. ## Interface PartialStatisticsModel This model holds the key statistics about partial profit and loss events during a backtest. It’s designed to give you a clear picture of how often your strategy is realizing gains and losses. You'll find the raw details of each profit or loss event in the `eventList` property – a complete record of each occurrence. The `totalEvents` field tells you the overall number of profit and loss events that happened. `totalProfit` and `totalLoss` specifically count how many times your strategy made a profit and a loss respectively. ## Interface PartialProfitContract The `PartialProfitContract` represents a notification when a trading strategy hits a partial profit milestone, like 10%, 20%, or 30% profit. This helps you track how your strategy is performing and when take-profit orders are being executed. Each event includes details about the trade, such as the symbol (e.g., BTCUSDT), the name of the strategy being used, and the exchange and frame where the trade is running. You’ll also find the original data related to the trade signal and the current price when the milestone was reached. Crucially, you can identify if the event came from a backtest (using historical data) or from live trading. The `timestamp` and associated `when` property give you a precise record of when this profit level was achieved, using either a virtual time in backtests or the actual time in live trading. These events are used by services that build reports and also let you create custom callbacks to react to these events. ## Interface PartialProfitCommitNotification This notification tells you when a partial profit target has been achieved during a trade. It provides a detailed snapshot of the trade's status, including the timestamp, whether it's a backtest or live trade, the trading pair, and the strategy involved. You'll find key information like the signal identifier, percentage of position closed, current market price, and the trade direction (long or short). It also includes details like the entry price, take profit and stop-loss prices, and original pricing before any trailing adjustments. Beyond the immediate details, you get a complete picture of the trade's performance. See the cost of entry, leverage used, and details about any DCA (Dollar Cost Averaging) employed. The notification also extensively reports on profit and loss metrics: total PNL, peak profit, maximum drawdown, and related pricing, percentages, and entry counts. A helpful note field allows for human-readable explanations of the trade’s reasoning. Finally, it includes timestamps related to signal creation, pending status, and notification creation. ## Interface PartialProfitCommit This event signifies a partial profit-taking action within a trading strategy. It provides a snapshot of the position's performance and details surrounding the partial close. The `action` property clearly identifies this as a partial profit event. You’ll find the `percentToClose` indicating what portion of the position is being closed. It also includes the current market price (`currentPrice`) at the time of the action and the total profit and loss (`pnl`) realized from the closed part of the trade. To understand the broader context of the position’s lifecycle, you also have access to its peak profit, maximum drawdown, and initial entry details including open price, take profit, and stop-loss levels – both as originally set and as they were adjusted. Finally, the timestamps `scheduledAt` and `pendingAt` help track when the signal was generated and when the position first became active, respectively. ## Interface PartialProfitAvailableNotification This notification lets you know when a trading strategy has reached a specific profit milestone, like 10%, 20%, or 30% gain. It’s triggered during both backtesting and live trading. The notification includes a lot of details to help you understand what happened. You’ll find information like the unique identifier of the trade, the exact time it reached the milestone, the trading pair involved (like BTCUSDT), and the exchange where the trade occurred. It also breaks down the key numbers – entry price, current price, the take profit and stop-loss prices, and importantly, how much profit has been made so far. You'll see a complete picture of the position’s performance, including peak profit, maximum drawdown, and all the relevant pricing details, alongside details on any averaging or partial close strategies employed. Finally, there’s an optional note to provide extra context about the trade. ## Interface PartialLossContract The `PartialLossContract` describes notifications related to when a trading strategy hits predefined loss levels, like -10%, -20%, or -30% drawdown. These notifications, or events, are triggered when a strategy's losses reach these milestones. Each event contains details about the trading symbol, the name of the strategy that generated the signal, the exchange and frame used, and comprehensive data about the original signal. You’ll also find the current price at the time of the loss, the specific loss level reached, and whether the event came from a backtest or live trading. The timestamps help synchronize the data, showing when the loss level was detected – either as a virtual time during backtesting or real-time during live trading. This allows for accurate tracking of strategy performance and potential stop-loss triggers. Events are only sent once for each loss level per signal to avoid duplicates. ## Interface PartialLossCommitNotification This notification is triggered when a partial position closure happens, whether it's part of a backtest or live trading. It provides a detailed breakdown of what happened, including a unique ID, the exact time of the closure, and whether it occurred during a backtest. You'll find all the key details about the trade itself, like the symbol, strategy name, and exchange involved, along with information about the signal that initiated the action. The notification gives a complete picture of the position, from the initial entry price and take/stop loss levels to the current market price. It also includes a ton of performance metrics – peak profit, maximum drawdown, and profit/loss percentages – along with the prices and costs associated with those milestones. This allows for in-depth analysis of performance and potential improvements to strategies. You can also see details related to DCA, total entries, partials, and even any notes added to the signal. Finally, timestamps related to the signal’s lifecycle are available for tracking its progression. ## Interface PartialLossCommit This describes a partial loss event within a trading strategy's backtest. It represents a situation where a portion of an existing position is being closed out. The `action` property definitively identifies this as a "partial-loss" action. The `percentToClose` tells you what percentage of the position is being closed. Several properties provide context about the position's performance. You'll find the `currentPrice` at the time of the partial loss, along with the total Profit and Loss (`pnl`), the highest profit achieved (`peakProfit`), and the maximum drawdown experienced (`maxDrawdown`). The `position` property indicates whether it’s a long (buy) or short (sell) trade. Key entry details like the `priceOpen`, and take/stop loss prices are also available, including the original values before any trailing adjustments. Finally, timestamps (`scheduledAt` and `pendingAt`) indicate when the signal was created and when the position was initially activated. ## Interface PartialLossAvailableNotification This notification alerts you when a trading position hits a pre-defined loss milestone, like -10%, -20%, or -30% of its initial value. It's a way to track potential losses as a trade progresses. Each notification includes details such as a unique ID, the exact time the loss level was reached, whether it’s from a backtest or live trade, the trading pair involved, and the strategy and exchange used. You’ll also find information about the trade’s entry price, direction (long or short), stop-loss and take-profit levels (original and adjusted), and detailed profit/loss data, including peak profit and maximum drawdown. The notification also provides insights into the trade’s history, like the number of entries made (especially important for trades using averaging), the number of partial closes executed, and key pricing information used in profit/loss calculations, including slippage and fees. There's also a field for optional notes which can provide context about the trade's reasoning. ## Interface PartialEvent This data structure, called `PartialEvent`, provides a consolidated view of profit and loss milestones during a trade. Think of it as a record of significant points in a trade's life, including when it hit a particular profit or loss level. Each `PartialEvent` includes details like the exact time it happened, whether it was a profit or loss, the trading pair involved, and the name of the strategy used. You'll also find information about the signal that triggered the trade, the position type (long or short), and current market prices. Crucially, it stores the initial entry price, take profit target, and stop loss levels, along with the original values set when the signal was first created. If a strategy uses dollar-cost averaging (DCA), the record also tracks the total number of entries and the original entry price before averaging. Other important details include the percentage of partials executed, the unrealized profit and loss at that point, a human-readable explanation for the trade, and timestamps indicating when the position became active and when the signal was initially scheduled. Finally, a flag indicates whether the trade is part of a backtest or a live trading situation. ## Interface OrderSyncOpenNotification This notification tells you about a new trading position being opened by a strategy, either in backtesting or live trading. It provides a wealth of detail about the trade, including when it happened and a lot of performance metrics. The `type` confirms this is an "order_sync.open" event. A unique `id` identifies the notification, along with a `timestamp` showing exactly when the position opened. You'll find details about the trading pair (`symbol`), the strategy that triggered the trade (`strategyName`), and the exchange used. The notification distinguishes between immediate orders (`orderType: "active"`) and orders placed in advance (`orderType: "schedule"`). Detailed performance information is included, like `pnl` (profit and loss), `peakProfit` (highest profit achieved), and `maxDrawdown` (largest loss incurred). It also breaks down the P&L calculations with entry and exit prices. You can track how the trade progressed with `priceOpen` (entry price), `priceTakeProfit` (take profit price), and `priceStopLoss` (stop loss price), and view original values before any adjustments. DCA and partial closing details are also available via `totalEntries` and `totalPartials`. Finally, `scheduledAt` and `pendingAt` give the timing of signal creation and activation, and `note` offers any relevant human-readable context. The `createdAt` field marks when the notification itself was generated. ## Interface OrderSyncCloseNotification This notification signals that a trading signal has been closed, whether it was due to a profit target being hit, a stop-loss being triggered, time expiring, or a manual closure. It provides a wealth of information about the trade, including when it was closed, the trading pair involved, and the strategy that generated the signal. You'll find details about the trade’s performance like profit and loss (both in USD and percentage terms), along with metrics tracking the highest profit and the largest drawdown the trade experienced. The notification also breaks down how many entries and partials were involved, giving a complete picture of the trading activity. Furthermore, it details the entry and exit prices, original order prices, costs, leverage applied and the reason behind the signal’s closure. Finally, timestamps related to signal creation, position activation, and notification generation are also included. ## Interface OrderSyncCheckNotification This notification provides updates on the status of orders associated with signals, primarily used to confirm that the external order management system is still tracking those orders. It’s sent periodically while a signal is active, acting as a "ping" to check for order synchronization. The framework limits how often these notifications are sent to avoid overwhelming systems, roughly once every 15 minutes per signal. Each notification contains detailed information about the order, including: * **Key identifiers:** A unique ID for the notification, timestamp, and signal. * **Trade details:** The trading symbol, strategy, exchange, order type, position (long or short), and original prices. * **Price and PNL information:** Current market price, effective take profit and stop loss prices, and unrealized profit/loss metrics, including peak profit and maximum drawdown. * **DCA and Partial Close details:** The number of entries and partial closes completed, which are helpful for understanding the execution history. * **Timing Information:** timestamps representing signal creation and when the position transitioned to a pending or active state. * **Optional note:** A human-readable explanation of why the signal was triggered. Essentially, these notifications offer a snapshot of the trade’s current state and performance, which is useful for monitoring and troubleshooting order synchronization and potential discrepancies between the backtest kit and external systems. ## Interface OrderSyncBase OrderSyncBase provides the core information shared across various order synchronization events within the backtest-kit framework. It essentially acts as a common foundation for understanding what's happening with orders, whether they're being actively managed or scheduled for later execution. The `type` property clarifies whether the event relates to an active order ("active") or a scheduled order ("schedule"), helping to differentiate immediate actions from those planned for the future. You'll find details about the trading symbol, the strategy that generated the order, the exchange used, and whether it's part of a backtest or live trading environment. Crucially, `signalId` and `timestamp` provide unique identification and timing for each event, while `attempt` tracks how many times an order has previously failed to execute – a useful indicator for potential issues. Finally, the `signal` property contains the complete data associated with the signal that triggered the order. ## Interface OrderStopContract This event signals that a trading order, initially monitored by the system, has reached a terminal state and will no longer be actively managed. Think of it as a notification that the framework has decided the order is effectively closed or canceled, and no further actions will be taken. There are two main reasons why this might happen: the order was unexpectedly removed from the exchange (perhaps it was filled, canceled, or liquidated elsewhere), or the system encountered too many temporary errors while trying to confirm the order's status. Crucially, this event only occurs in live trading environments; backtesting doesn't perform these order checks. The event provides a wealth of detail about the order, the strategy that generated it, the current market conditions, and the position’s performance to date. You can examine the `reason` property to understand the specific cause of the terminal event and analyze the associated properties to gain insights into the order's lifecycle. Several properties detail the order's entry and exit prices, including original values and any adjustments due to averaging or trailing stops. The event also includes information about the total entries and partial closes related to the trade. ## Interface OrderStopCheckNotification This notification signals a critical event regarding an order being monitored – essentially, the order's check process has reached a terminal state. It's a rare event, happening only when an order is definitively either deleted or has failed repeatedly. You'll receive this notification once per signal. The notification provides detailed information about the order and its performance, including the trading symbol, strategy used, exchange, and signal details. It specifies whether the monitored order was an "active" position (to be closed) or a "schedule" order (to be cancelled). You'll see one of two reasons for the termination: "deleted" (meaning the order was not found) or "exhausted" (meaning retry attempts were exceeded). The notification includes extensive data about the order's history, such as its original and effective prices (take profit, stop loss, entry), costs, leverage, total entries/partials, P&L data (current, peak, drawdown), and timestamps. This data paints a complete picture of the trade’s lifecycle up to the point of termination, allowing for comprehensive post-mortem analysis. There's also additional information on signal creation and pending timestamps, and an optional note field for added context. ## Interface OrderRejectOpenNotification This notification signals that an order couldn't be placed and is a definitive rejection from the exchange – it's not a temporary hiccup that will retry. It’s specifically triggered when the system definitively fails to place an order, meaning further attempts are pointless. Each rejection event provides a lot of detail to help understand why the order failed. You'll find information like the unique signal ID, the strategy name, the exchange involved, and a human-readable explanation of the rejection reason. The notification also includes performance snapshots like P&L, peak profit, and maximum drawdown calculated up to that point. This event offers a comprehensive view of the position’s performance, including key metrics like entry and exit prices, cost, and multiplier. It also contains details such as original prices and trailing stop-loss settings, plus timestamps for signal creation and activation. Crucially, these notifications only occur in live environments, not during backtesting, ensuring consistency across different system components. ## Interface OrderRejectOpenContract This describes what happens when a trading order or scheduled entry can't be executed – it's been definitively rejected. Essentially, the system won’t attempt the trade again and the signal that triggered the order is considered used up. The `action` property tells you *what* was rejected, either an attempt to open a position or a scheduled entry. The `cost` property shows you how much the rejected order would have cost. ## Interface OrderRejectCloseNotification This notification tells you when a closing order for a position was rejected by the broker – essentially, a forced close didn't go through. It only happens when the closing process fails completely, typically due to a broker error, not temporary issues. This is a live-only event, meaning it won't show up in backtest simulations. It provides a lot of information about the rejection, including a unique ID, a timestamp, the trading symbol, and the reason the broker gave for rejecting the order. You'll see details about the strategy involved, the exchange, and the specific order that failed. Beyond the rejection details, the notification also gives you a snapshot of the position's performance up to that point, including profit/loss (P&L), peak profit, maximum drawdown, and related prices and costs. You'll find information on entry and exit prices used in P&L calculations, plus details on the original take profit, stop-loss, and entry prices before any adjustments. The notification also outlines the number of entries and partial closes executed. Finally, it includes key timestamps like when the signal was scheduled, when the position activated, and the reason for the close itself, along with any notes providing extra context. ## Interface OrderRejectCloseContract When an order to close a position is rejected outright, this object signals that the close was definitively refused. It’s used to indicate that the trading engine is forcefully closing the position due to a problem. The `action` property is always "signal-close" – it's a consistent marker for this specific type of rejection. The `closeReason` property explains *why* the close order was rejected; it carries the original reason that prompted the engine to take action. ## Interface OrderRejectBase This event signifies a permanent rejection of an order by the exchange, indicating that retries are not possible. It’s a definitive "no" from the broker, arising from a situation where the exchange directly refused the order. This isn't due to temporary issues or errors that the system might automatically recover from. There are two main scenarios where you'll see this event: either an order to open a new position was rejected, or an order to close an existing position failed. The `type` property tells you which kind of order was rejected—either an "active" order (for opening or closing a position) or a "schedule" order (related to placing an order when a signal is initially created). The event contains a wealth of information about the rejected order, including details like the trading symbol, strategy name, exchange name, and the specific reason for the rejection – which you can find in the `message` field. It also provides a snapshot of the position's performance at the time of rejection, encompassing metrics like P&L, peak profit, and maximum drawdown. Importantly, these rejection events *only* occur in live trading environments; they don't happen during backtesting. The `backtest` property is always false for these events. Also, the `signalId` is crucial – it guarantees that a specific signal will never trigger another order attempt after this rejection. ## Interface OrderOpenContract This event, called `OrderOpenContract`, signifies that a previously placed limit order has been filled, allowing the trading framework to enter a position. It's particularly useful for confirming order executions with external systems, like order management tools or audit logs. Think of it as a confirmation that your limit buy or sell order was accepted and processed by the exchange. The event provides a wealth of information including the price at which the order was filled, the current market price, and details about the position’s performance so far – like peak profit, maximum drawdown, and overall cost. You'll also find details about the original take profit and stop-loss prices, before any adjustments were made, and information about how many entries were made if you’re using a dollar-cost averaging strategy, alongside any partial exits that occurred. The `scheduledAt` and `pendingAt` timestamps track the signal creation and position activation times, offering a complete timeline of the order's journey. ## Interface OrderFillOpenNotification This notification provides confirmation that a trade has been executed or a resting order has been placed – it's essentially the final word on whether your strategy's instructions were followed by the exchange. It only appears after the system is absolutely sure the order has gone through, making it a reliable signal. Think of it as a late-arriving message confirming what you already hoped had happened. The notification includes a wealth of data about the trade including the exact time of confirmation, the trading pair, the strategy responsible, and a unique identifier for the signal. It also provides detailed performance metrics for the position, such as realized profit/loss, peak profit, maximum drawdown, and the prices involved. You'll find data on entry and exit prices, the number of entries made, and even the initial cost of the position. Critically, this notification *only* happens for live trades – it won't appear during backtesting. It represents a concrete confirmation of your strategy's actions in the real world. ## Interface OrderFillOpenContract This object represents a confirmation from your broker about a new position being opened or an order to open a position being placed. It tells you exactly what happened: either a trade was executed ("signal-open"), or an order to trade was sent to the market ("schedule"). The `action` field tells you the type of confirmation. The `cost` field indicates the total amount of money spent to establish this position. Essentially, it’s a record of the financial impact of initiating a trade. ## Interface OrderFillCloseNotification This notification confirms that a trading order has definitively closed on the exchange—it's the final confirmation after a successful execution. It's only received when the trade is truly finished, and won’t appear for temporary or failed attempts. Here's a breakdown of what you'll find in this notification: * **Key Details:** You'll see the trade's unique ID, when it closed, the strategy that initiated it, and the exchange where it occurred. * **Performance Metrics:** Detailed information about the trade’s performance is provided, including profit and loss (PNL) figures, peak profit, maximum drawdown, and entry/exit prices. * **Order Information:** It outlines the order type, the number of attempts it took to close, and the prices used for the trade. * **Trade Context:** You'll find the trade's direction (long or short), the initial entry price, and any original take profit or stop-loss prices that were set. * **Additional Data:** It includes details about the cost of the position, leverage applied, the number of entries (for averaging), and the reason for the closure. A timestamp indicates when the signal was initially created and when the position was activated. This notification offers a comprehensive snapshot of a completed trade's lifecycle and results. ## Interface OrderFillCloseContract This data structure represents when a trading position is closed, and confirms that the broker has executed the closing order – whether that's due to a take profit, stop loss, a time-based rule, or a manual closure. It’s a notification that the exit order has been fulfilled. The `action` property clearly identifies this as a closing event. The `closeReason` provides details about *why* the position was closed, offering valuable insight into the trading logic that triggered the exit. ## Interface OrderFillBase This document describes the `OrderFillBase` event, a crucial notification within the backtest-kit trading framework. It represents a confirmed order execution—meaning the broker has actually placed the order on an exchange. It's important to understand that this isn't fired for order attempts or rejections; it only happens when an order is truly confirmed by the broker. This event provides extensive details about the trade, including the trading pair symbol, the strategy that generated the signal, the exchange used, and the timeframe. The `type` property distinguishes between active (opening or closing a position) and scheduled (initial placement of a resting order). You’ll also find information like the signal identifier, the exact time of confirmation, and details about the market price and profit/loss snapshots at the time of execution. Furthermore, the event includes valuable data points related to the order’s lifecycle, such as the number of previous failed attempts, the original and trailing-adjusted stop-loss and take-profit prices, and the number of entries and partial closes. The `backtest` property is always false, indicating this event only occurs in live trading environments. The event's timestamp is always the time the broker confirmed the order, offering a reliable record of the trade's execution. ## Interface OrderContinueContract This event signals that the trading framework is continuing to monitor an order – it hasn't been confirmed as filled or cancelled. It's a recurring notification you'll receive while an order remains active, especially in live trading where real-time checks are performed. The `type` property tells you whether it's related to an active position ("active") or a pending order ("schedule"). The `attempt` value is key: a zero value means the order check was successful, resetting any error counters. Values greater than zero indicate temporary issues during the check, but the framework is still assuming the order is open and continuing to monitor it; the higher the number, the more consecutive checks have failed before tolerance is reached. The event provides a wealth of information about the order and its context, including details about the trading pair, strategy, exchange, timeframe (which is empty during live trading), and a unique identifier for the signal that triggered the order. You’ll also find data on the order's performance, such as PnL, peak profit, drawdown, entry and exit prices (original and adjusted for averaging or trailing), and timestamps related to its lifecycle. This allows for deep analysis of order behavior and performance in real-time. Remember that this event only occurs in live trading – backtests don't perform these checks. ## Interface OrderContinueCheckNotification This notification lets you know about the ongoing health of an order – think of it as a continuous check-up. It's triggered when an order check isn't immediately resolved, meaning the order is still open or a temporary problem was dealt with, and monitoring continues. The notification provides a ton of details about the order and its performance, including the trading symbol, strategy name, and the direction of the trade (long or short). You’ll find information about the original and current prices, stop-loss and take-profit levels, and how the position has been performing so far – including profit/loss, peak profits, and maximum drawdowns. It also includes data like the number of entries and partials, total cost and multiplier, and creation timestamps, which all contribute to a comprehensive view of the order's status and history. The notification is throttled to avoid overwhelming your system. Remember, these checks are only for live orders – they aren’t used in backtesting. ## Interface OrderCloseContract This event lets you know when a trading signal has been closed, whether it was because of a profit target, a stop-loss, time expiry, or a manual action. It’s designed to help systems outside of the core trading engine stay in sync with what’s happening. Think of it as a notification that a trade is finished, and you can use it to update external systems that track orders, calculate profit and loss, or keep audit logs. The event provides a wealth of information about the closed position, including the current market price, the overall profit and loss, the highest profit reached, the largest drawdown, and the original entry and exit prices – all adjusted for things like averaging and trailing stops. You’ll also find details like when the signal was created, when the position was activated, and the reason for the closure. Finally, it indicates if any averaging or partial closures occurred during the trade's lifecycle. ## Interface OrderCheckContract This event, called "signal-ping," is a crucial check performed by the framework to ensure your orders are still active on the exchange. It's like a periodic confirmation that your buy or sell orders haven’t been filled, canceled, or liquidated unexpectedly. The framework sends this ping during live trading, but *not* during backtesting because there's no real exchange connection then. Essentially, it asks your broker if the order related to an open or pending signal is still present on the exchange. The `type` property tells you whether you're checking an active (open) position or a scheduled (pending) order. When you receive this ping, you need to respond. * If the order is still good, just acknowledge it, and the framework keeps monitoring. * If the order is gone (filled, canceled, liquidated), you *must* report it immediately – this stops the framework from endlessly retrying. * Transient errors, like network glitches, are tolerated for a few attempts before the framework assumes the order is gone. The event provides a wealth of information about the signal, including its details, market conditions, realized profit and loss, and the status of any take profit and stop loss orders. The `attempt` property keeps track of how many times the check has failed recently, so you know how urgently you need to respond. ## Interface MetricStats `MetricStats` provides a collection of statistics related to a particular performance measurement. Think of it as a report card for a specific metric within your trading system. It tracks how many times a certain event occurred (the `count`), and gives you details about its timing. You'll find information about the total time spent, the average time, and the fastest and slowest occurrences. It also includes measures like the standard deviation and percentiles (like the 95th and 99th percentile), to help you understand the distribution of those times and identify any unusual patterns. Finally, the stats will also include wait times which are useful to find out how long events are queued up. ## Interface MessageModel This describes a message within a conversation handled by a large language model. It's designed to hold all sorts of interactions, from the initial instructions to user prompts, the model's responses, and even when tools are used. Each message has a `role` which clarifies who sent it – whether it's the system providing instructions, a user making a request, or the assistant answering. The `content` is the actual text of the message, and sometimes there's additional `reasoning_content` that explains how the model arrived at its answer. If the assistant is calling a tool, you’ll find `tool_calls` detailing that interaction and a `tool_call_id` to identify which tool call this message relates to. Finally, messages can also include images, represented in several formats like Blobs, raw bytes, or base64 strings. ## Interface MaxDrawdownStatisticsModel This model holds information about maximum drawdown events during a trading backtest. It essentially tracks the worst peak-to-trough declines experienced. The `eventList` property gives you access to a detailed chronological record of each drawdown event, presented in reverse order (most recent first). Think of it as a complete log of the worst drops. The `totalEvents` property simply provides a count of how many maximum drawdown events were identified. ## Interface MaxDrawdownEvent This object represents a single instance of a maximum drawdown event encountered during trading. It captures key details about the position that experienced the drawdown, including when it occurred (timestamp), which asset was involved (symbol), and the name of the strategy and signal responsible. You'll find information about the position’s direction (long or short), its total profit and loss (pnl), the highest profit ever achieved (peakProfit), and the magnitude of the drawdown itself (maxDrawdown). Additional details like the price at which the drawdown was recorded, the entry price, and any set take profit or stop loss levels are also included. Finally, it indicates whether the event happened during a simulated backtest. ## Interface MaxDrawdownContract This contract provides information about when a maximum drawdown is reached for a trading position. It's a way for the trading system to tell you the biggest loss experienced by a position, along with important details about the trade. You'll find details like the trading symbol, the current price, and the exact time the drawdown occurred. The contract also includes information about the strategy, exchange, and timeframe involved, as well as the signal that triggered the position. Importantly, it tells you whether this drawdown event happened during a backtest or in live trading. This allows you to handle the information differently depending on the context. By monitoring these drawdown events, you can implement risk management strategies and potentially adjust your trading approach. ## Interface LiveStatisticsModel This model provides a detailed snapshot of your live trading performance, offering a wide range of statistics to analyze your strategies. It tracks everything from individual trade events to overall portfolio metrics, giving you a complete view of your trading activity. You'll find information about the total number of events, including wins, losses, and closed trades. Key performance indicators like win rate, average profit and loss, and total profit are all calculated. Beyond basic profitability, the model dives into risk-adjusted performance with metrics like Sharpe Ratio, Sortino Ratio, and Calmar Ratio, helping you understand the efficiency of your trading. It also offers insights into trade duration, volatility (standard deviation), and even analyzes the pressure from buyers versus sellers in the market. Finally, trend analysis and confidence levels give you a broader understanding of the market context behind your trades, allowing for more informed decision-making. Keep in mind that many of these values can be null if the calculation is unreliable due to market conditions or data issues. ## Interface InitialDispatchScheduleContract This describes the data you get when a resting order is first created – that’s an order that waits for a specific price to be reached. Think of it as the initial information package. The `type` will always be "schedule," confirming it’s a resting order. The `signal` property holds all the details about the scheduled signal that triggered this order, providing a snapshot of the market conditions at the moment the order was placed. This gives you a full picture of *why* this order is waiting. ## Interface InitialDispatchContractBase This interface defines the common information shared between different ways of starting a trade execution. It essentially holds the environment details relevant for a trade, like the trading pair (e.g., BTCUSDT), the name of the strategy making the decision, and where that strategy is running. You’ll also find information about whether this is a backtest (running against historical data) or live trading, the current market price, and the exact time the event occurred. The `when` property is particularly important to understand – in backtests, it represents the time of the candle being analyzed, while in live trading, it's the actual real-time clock time of the event. It provides context for the trade’s decisions, giving strategies the data they need to operate correctly. ## Interface InitialDispatchActiveContract This describes the initial information sent when a trading position first becomes active – essentially, when an order is filled and the system starts tracking it. It's a notification that a position is now open and being monitored. The message confirms the position type is "active." It also includes the complete set of data for that position at the time it became active, which is represented by the `IPublicSignalRow` object. This signal row contains all the details about the trade, like price, quantity, and other relevant factors. ## Interface InfoErrorNotification This component deals with notifications about errors that happen during background processes, but aren't critical enough to stop everything. Think of it as a heads-up about something that needs attention. Each notification has a specific type, a unique ID to track it, and a detailed error object containing information like a stack trace and extra data to help diagnose the issue. A human-friendly message explains the problem, and a flag confirms these notifications originate from the live environment, not the backtest itself. ## Interface IdlePingContract This defines how the backtest-kit framework communicates when a trading strategy isn't actively making decisions. It's like a heartbeat signal, letting you know the strategy is in an idle state, meaning it's not currently responding to any trading signals. This "IdlePingContract" event includes important details like the trading pair involved (e.g., BTCUSDT), the name of the strategy, and the exchange it's operating on. You'll also find the current market price at the time of the ping, whether the execution is a backtest (historical data) or live trading, and a timestamp for accurate timing. The timestamp represents the time of the ping – in live trading it's the current time, and in backtesting, it's the timestamp of the candle being analyzed. You can subscribe to these events to monitor the lifecycle of your strategies and understand their periods of inactivity. ## Interface IWorkerRunParams The `IWorkerRunParams` interface defines the configuration options for running a worker process. Think of it as a way to tell the backtest-kit framework how to set up and execute your trading strategies. You don't have to provide every setting – most properties have reasonable defaults, so you can just pass the settings you want to change. Even an empty object works fine! The `workerPath` specifies where the worker's code lives, which is usually the main script of the process. If you don't provide it, the framework will automatically use the path to the current script being executed. The `workerName` selects which specific trading strategy or worker to run; if you skip it, the first available one will be used. ## Interface IWorkerPaperArgs This interface defines the arguments needed to run a worker process that simulates live trading without actually placing orders. It's specifically used when you want to test your strategies in a "paper trading" environment. The `paper` property, set to `true`, signals that the live pipeline should operate in this paper trading mode, allowing you to observe performance and behavior without risking real funds. Think of it as a dress rehearsal for your trading system. All symbols processed by a single worker will share the same underlying child process for efficiency. ## Interface IWorkerLiveArgs The `IWorkerLiveArgs` interface defines the settings for a worker that processes live market data. Essentially, it's used when you want your backtest-kit to connect to a live data feed and simulate trades in real-time. This setup runs a pipeline for each symbol you're tracking, all within a shared child process for efficiency. The `live` property, set to `true`, signals that this worker should operate in live mode. ## Interface IWorkerCallbacks The `IWorkerCallbacks` interface lets you hook into the lifecycle of a worker process, giving you opportunities to influence its setup. Think of it as a way to subtly adjust how a worker gets ready for action. If you need to load extra configuration or schema definitions *before* the worker fully initializes, the `onWaitForInit` callback is your friend. It’s triggered just before the worker pauses waiting for everything to be ready, giving you a chance to load those resources in the background. This avoids slowing down the initial startup. ## Interface IWorkerBacktestArgs This defines the arguments used when running a backtest in the background, essentially letting the system handle the process for you. The `backtest` property simply confirms that this is a backtest operation. The `frameName` property specifies the timeframe for the backtest. If you have multiple timeframes available, you'll need to tell the system which one to use here; otherwise, it'll pick one automatically. The `cache` property allows you to pre-load candle data into memory. Enabling this can speed up the process, especially if you're using a custom data source; however, be aware it can impact performance and resources. ## Interface IWorkerArgs The `IWorkerArgs` interface defines the core information needed to kick off a backtest worker. Think of it as the initial setup instructions for a simulation run. It’s designed to be straightforward – you specify a worker identifier, the name of a strategy you want to test, and the exchange you'll be using. The symbol list you're trading isn't included here; it's provided separately when the worker actually starts running. If you only have one strategy and one exchange registered, you don't need to specify those – the framework will automatically use them. But if you have multiple, you'll need to tell it exactly which ones you want. You can also provide callbacks to be notified about different stages of the worker's lifecycle. ## Interface IWarmCandlesParams This object defines the information needed to fetch and store historical candle data. Think of it as a blueprint for downloading past price charts. It specifies the trading pair (like BTCUSDT), the exchange where the data comes from, the time frame of the candles (like 1-minute or 4-hour), and the start and end dates you want to cover. This data is often pre-loaded before running a backtest to ensure the backtesting process has all the necessary historical information. ## Interface IWalkerStrategyResult This interface describes the outcome of running a single trading strategy within a backtest comparison. It holds key information about the strategy's performance. You’ll find the strategy's name here, along with a detailed set of statistics summarizing how well it performed – things like profit, drawdown, and Sharpe ratio. A key value, the 'metric,' represents the specific measurement used to compare strategies; it might be null if the strategy wasn’t valid for that metric. Finally, the 'rank' indicates the strategy’s position relative to other strategies in the comparison, with the best strategy ranked as 1. ## Interface IWalkerSchema The IWalkerSchema defines how to set up A/B tests for different trading strategies. Think of it as a blueprint for running experiments to see which strategy performs best. You'll give it a unique name for identification and can add a note to explain what the test is for. It specifies the exchange and timeframe to use for all the strategies in the test, ensuring a level playing field. You also list the names of the strategies you want to compare against each other; these strategies need to be previously registered with the framework. The schema lets you choose a metric like Sharpe Ratio to optimize, helping you determine the best strategy based on risk-adjusted returns. Finally, you can optionally provide callbacks for different stages of the testing process. ## Interface IWalkerResults The `IWalkerResults` object holds all the information gathered when backtest-kit compares different trading strategies. It contains key details about the trading environment, including the specific financial symbol that was tested, the exchange used for data, the name of the strategy comparison process (the "walker"), and the timeframe used for the backtest. Think of it as a central record of everything that happened during a strategy comparison run. ## Interface IWalkerCallbacks The `IWalkerCallbacks` interface lets you hook into different stages of the backtesting process. Think of it as a way to get notified and potentially react to what's happening as the system evaluates various trading strategies. You'll receive a notification when each strategy begins (`onStrategyStart`), when it finishes (`onStrategyComplete`), and if it encounters any errors (`onStrategyError`). The `onStrategyComplete` callback also gives you access to performance statistics and a metric value calculated during the backtest. Finally, when all strategies have been evaluated, the `onComplete` callback will fire, providing a summary of the overall results. This allows you to observe and potentially influence the backtesting workflow. ## Interface ITrailingTakeCommitRow This interface describes a specific action queued within the backtest-kit framework, relating to a trailing take commit strategy. Think of it as a record of an instruction to adjust a trade's stop-loss based on a percentage shift from a defined price. The `action` field clearly identifies this as a "trailing-take" action. The `percentShift` specifies the amount of the percentage shift to be applied when moving the take profit level. Finally, `currentPrice` holds the price at which the trailing was initially established, providing context for the calculation. ## Interface ITrailingStopCommitRow This interface represents a single action that needs to be taken related to a trailing stop order. Think of it as a record of a specific trailing stop adjustment that's been queued for execution. It includes details like the type of action being performed ("trailing-stop"), the percentage change that triggers the stop, and the price at which the trailing stop was initially set. This information is crucial for accurately recreating and verifying a trading strategy's behavior during backtesting. ## Interface ISweepTrade The `ISweepTrade` interface defines the structure of a single trade executed within the backtest-kit framework. Each trade has a unique identifier linked to the original idea that prompted it, along with the trading symbol involved. It also tracks the author of the idea, allowing for easy analysis of performance by individual strategy contributors. The interface records key details about the trade’s lifecycle, including its entry and exit timestamps, and the reason for its closure. You'll also find the actual holding time of the trade, calculated in minutes. Crucially, it stores the percentage profit or loss (PnL) achieved after considering trading fees. Finally, the `absorbedIdeas` property provides a valuable record of any other ideas that were 'absorbed' by this trade – essentially, indicating which ideas were superseded by this one. This allows for a detailed audit trail of how the strategy reacts to multiple signals over time. ## Interface ISweepTrack The `ISweepTrack` represents a detailed record of an author's trading performance under a specific, defined rule set. Think of it as a report card for a trader's strategy, focusing on continuous data rather than simple pass/fail judgments. Each track includes the crucial parameters of the rule being tested – the holding period (`holdMinutes`), the profit-locking level (`profitLockPercent`), the stop-loss level (`hardStopPercent`), and the trailing take percentage (`trailingTakePercent`) – alongside the author's login. The track then quantifies the author's activity with key metrics like `ideas` (total directional trading attempts), `hits` (successful trades where the lock or trailing arm triggered before the stop), and `hitRate` (the percentage of successful trades). These raw numbers offer a continuous view of performance, allowing users to filter and assess trust levels without arbitrary thresholds. It captures how the author performs across various conditions defined by the rule. ## Interface ISweepSchema This schema defines how a sweep, which is a set of trading configurations, is registered and executed. Each sweep needs a unique name for identification. It also specifies which exchange will be used to fetch historical candle data for creating trading profiles; it's important that the data comes in complete sets. You can customize the grid axes – these are the parameters that control how trades are placed and managed – by overriding default values. Freezing an axis with a single value prevents it from being adjusted during the sweep. The order in which sweep results are ranked and reported can be defined. Callbacks provide optional functions that can be triggered at different points in the sweep's lifecycle; these don't impact the core trading logic but can be used for logging or other actions. ## Interface ISweepResult The `ISweepResult` object holds the final outcome of a trading simulation. It bundles together key performance indicators and details about the simulation's progress. You'll find information like the trading symbol involved, the total number of ideas considered, and how many of those were directional trades. It also tracks how many profiles were created using candle data and how many were cut short due to data limitations. The result includes statistics about trade holding times, offering insight into the duration of positions held. Specifically, it provides the average holding time and the 95th and 99th percentile holding times, which can highlight unusually long holds. Finally, the `reports` property contains a comprehensive evaluation of each grid point, using a single "profit-before-stop" metric, and outlines the top-performing points, along with performance data attributed to individual authors. ## Interface ISweepPointReport This report provides a detailed summary of performance for a single grid point within a backtest. It consolidates key metrics related to trades executed at that specific grid level. The report identifies how many trades were skipped due to author availability. It presents overall profitability, calculating the total and average profit percentage across all trades executed at the point. Key performance indicators like win rate, profit factor, and drawdown are also included, providing insight into the risk-reward profile. Furthermore, the report delves into trade durations, offering average holding times and percentile values for how long positions were held. Risk-adjusted return measures like the Calmar and Recovery factors, along with Sharpe and Sortino ratios, offer a comprehensive view of performance relative to risk. A breakdown of trade exit reasons helps understand the common factors leading to position closures. Finally, a complete list of the individual trades at that point is provided, enabling detailed examination of why a particular profit or loss occurred. ## Interface ISweepParams The `ISweepParams` object holds all the settings needed for a sweep run. It includes a logger to help you track what's happening during the process – think of it as a helpful observer. You'll also find the grid axes configuration, which defines how your test parameters are arranged and explored, ensuring all necessary defaults are in place. Finally, the report order dictates how the results will be presented, with default criteria automatically applied. ## Interface ISweepMetricReport This report holds the results for a single pass of your backtesting grid. It summarizes how each combination of parameters performed, specifically looking at profit before the stop-loss. The `reports` section gives you a detailed breakdown of each grid point, ranked from best to worst based on a default ranking like Sharpe ratio. The `best` section highlights the top performers according to four different ranking criteria. If your grid didn’t generate any results, this section will be empty. Finally, the `tracks` provide insights into the rules and parameters used by the system. This section is compact and self-contained, allowing you to quickly identify and analyze trends without needing to combine multiple data points. It gives you the raw performance data (hit rate, ideas, etc.) related to a particular rule combination so you can evaluate which rule authors to trust. ## Interface ISweepIdeaProfile ISweepIdeaProfile represents the performance of a trading idea across a series of candles. It provides a detailed picture of how the idea behaved, including its entry price, the candle data it experienced, and various metrics about its trajectory. Think of it as a historical record of an idea's journey from its inception to its conclusion. This profile includes information like when the idea was entered, the price at entry, and the complete sequence of candles that influenced its outcome. Critically, these profiles are used for evaluating the idea's success without needing to re-analyze the candle data. Several key metrics are calculated and stored within each profile. These diagnostics – such as whether the idea was ultimately successful (hit), the maximum favorable and adverse price movements (MFE/MAE), and a measure of how much the price shook out before a positive move (shakeout) – give a complete assessment of the idea's performance across the entire timeframe. A median movement percentage indicates the typical direction of price movement relative to the entry price, offering another insight into the idea's behavior. ## Interface ISweepIdea This describes a single trading idea – think of it as a public prediction made by someone about a particular asset. Each idea has a unique ID, a timestamp indicating when it was published, and specifies the trading pair (like BTCUSDT) it relates to. It also states the direction the author believes the price will move and identifies the author's username. Importantly, when running simulations, the entire idea is processed for each time step (candle), not individual grid points within a strategy. ## Interface ISweepGridPoint This describes a single point on a grid used for trading strategies. Each point defines specific rules for managing a trade. You'll find settings to determine when a trade should be stopped with a hard stop loss, how a trailing stop loss should work, and the maximum time a position should be held. It also includes a mechanism for profit locking, which allows you to secure profits once the price reaches a certain level. If the price pulls back, the position will be exited at the locked profit level. Setting this to zero disables the profit lock feature. ## Interface ISweepGridAxes The `ISweepGridAxes` defines the ranges of values used for key trading parameters like hard stops, trailing takes, hold durations, and profit locks. Think of it as setting up the boundaries for how a trading strategy will react to different market conditions. Each property – `hardStopPercent`, `trailingTakePercent`, `holdMinutes`, and `profitLockPercent` – represents a different way to control the trade. These values aren’t arbitrary; they're carefully chosen to tune the strategy's behavior concerning risk management (hard stops), profit taking (trailing takes and profit locks), and turnover rate (hold durations). The 'Ignored' sections clarify situations where a particular axis might not be actively used during a trade, and why those conditions are documented. For example, a trade might ignore the trailing take if the price doesn't reach a certain level. The holdMinutes property is particularly important as it dictates both the maximum time a trade can stay open and the time window used for assessing performance. The profitLockPercent creates a zone where the strategy can harvest liquidity without prematurely stopping a potentially profitable trade. Ultimately, the ISweepGridAxes is the foundation for a robust and customizable trading framework. ## Interface ISweepCallbacks This interface, `ISweepCallbacks`, provides a way to monitor the progress of a backtesting simulation. It's essentially a way to get real-time updates on what's happening behind the scenes, similar to the information you’d see printed to the console. You can subscribe to callbacks to track the progress of different stages, like processing ideas or grid points. The `onProgress` callback lets you know how many items have been processed within a stage and how many are left to go. Specific events trigger other callbacks – you’ll receive an `onIdeas` callback when the simulation receives ideas, and an `onProfiles` callback when all profiles have been built. The framework also provides notifications when author tracks are trained for grading rules, when a grid point is evaluated, and when a ranking is computed. Finally, the `onDone` callback signals that the entire simulation has completed, providing the final result. By using these callbacks, you can build custom visualizations or perform actions based on the simulation's real-time status. ## Interface ISweepBest The `ISweepBest` interface represents the top result for a specific ranking criterion within a trading simulation. It focuses solely on identifying the best result based on that criterion and providing access to the full report associated with it. Think of it as a pointer to the detailed information about the winning trade— the trades themselves and other track details aren’t included directly within `ISweepBest` to avoid unnecessary repetition; they’re available in the linked report. The `criterion` property tells you which ranking rule determined this result, while the `report` property gives you access to the complete sweep point report, which is essential for understanding the context of this winning result. If no results were found for a particular criterion, the report will be null. ## Interface ISweepAbsorbedIdea This describes a situation where a trading idea couldn't be acted upon because a previous trade from the same author was already using that slot. Think of it as a signal that got sidelined due to existing commitments. The information includes the unique ID of the suppressed idea and, crucially, the author who created it. This allows for quick analysis of an author’s trading history without needing to combine separate data streams. It essentially links the absorbed idea directly to the author’s previous trade. ## Interface ISweep The `ISweep` interface provides a simple way to execute a complete trading simulation, or "sweep." You provide a stock ticker symbol and a list of trading ideas, and the sweep client will handle the rest. It automatically filters ideas based on predefined profiles, evaluates them based on a scoring system, and then ranks them. The result of running a sweep includes detailed information about how each idea performed. ## Interface IStrategyTickResultWaiting This represents a tick result indicating that a previously scheduled trading signal is currently waiting for the price to reach its entry point. You'll receive this type of result repeatedly as the system monitors the signal. It contains essential information for tracking the signal's status and context, including the signal itself, the current price being monitored, the strategy and exchange names, and the timeframe being used. You’ll also find details like the symbol being traded, progress towards take profit and stop loss (which are always zero in this waiting state), unrealized profit and loss (a theoretical value for the position before activation), whether it's a backtest or live trade, and a timestamp of when the result was generated. This allows you to monitor the signal's progress and understand its environment. ## Interface IStrategyTickResultScheduled This interface represents a specific type of tick result within the backtest-kit framework. It indicates that a trading signal has been generated and is currently "scheduled," meaning it's waiting for the price to reach a certain point before execution. Think of it as a notification that the strategy recognized a potential trade and is patiently waiting for the market conditions to align. The data provided includes details like the strategy's name, the exchange used, the timeframe, the trading pair, the price at the time the signal was generated, and whether the event occurred during a backtest or in a live trading environment. This information is valuable for monitoring strategy performance and debugging. A timestamp marks precisely when the scheduled signal was created. ## Interface IStrategyTickResultOpened This data represents the outcome when a new trading signal is generated and successfully saved. It tells you that a signal has been created, and provides key details about the signal itself and the circumstances surrounding its creation. You'll find information such as the signal's ID, the name of the strategy that generated it, the exchange and timeframe involved, and the symbol being traded. Crucially, it includes the current price at the time the signal was opened, and indicates whether the event occurred during a backtest or in a live trading environment. This information is valuable for monitoring, debugging, and analyzing the performance of your trading strategies. ## Interface IStrategyTickResultIdle This interface represents a specific type of event within the backtest-kit framework: an "idle" state. It signifies that the trading strategy isn't currently generating any buy or sell signals. The data included with this idle event helps you understand the context of the inactivity. You’ll find details like the strategy’s name, the exchange it’s connected to, the timeframe being used, and the trading pair involved. The current price at the time of the idle state is also recorded. Crucially, it indicates whether the event occurred during a backtest or a live trading session. A timestamp provides a precise record of when this idle state began. The signal itself is explicitly null to confirm there's no active trading instruction. ## Interface IStrategyTickResultClosed This interface describes the result you receive when a trading signal is closed, providing a comprehensive view of what happened. It bundles together key details like the reason for the closure – whether it was due to a time limit, hitting a profit or loss target, or a manual close – alongside the final price at which the trade was settled. You'll also find a breakdown of the profit and loss, taking into account any fees or slippage encountered during the closing process. The information includes identifying details like the strategy name, exchange, timeframe, and trading symbol, allowing for easy tracking and analysis. A flag indicates whether the event occurred during a backtest or in live trading, and a unique ID is assigned for closes initiated directly by the user. Finally, the timestamp of the result's creation is recorded, linking it to the candle or execution event that triggered it. ## Interface IStrategyTickResultCancelled This interface describes a scenario where a planned trading signal was cancelled before a trade actually occurred. Think of it as a notification that a signal was scheduled to trigger a trade, but something happened – perhaps the signal itself wasn't activated, or a stop-loss was hit before the trade could even be placed. The `action` property simply confirms this is a cancellation event. You’ll find the details of the cancelled signal under the `signal` property. The `currentPrice` represents the price the market was at when the cancellation took place. The `closeTimestamp` tells you precisely when the cancellation happened, in milliseconds since the epoch. Various tracking details like the `strategyName`, `exchangeName`, and the `frameName` (like "1m" or "5m") are also included, providing context for the cancellation. The `symbol` identifies the trading pair involved, for example, "BTCUSDT". The `backtest` flag indicates whether this event happened during a simulated backtest or in a live trading environment. The `reason` property explains why the signal was cancelled, offering insights into the event's cause. If a user manually cancelled a signal using a cancellation ID, it's stored in the `cancelId` property. Finally, `createdAt` tracks when this particular cancellation record was generated. ## Interface IStrategyTickResultActive This interface describes the result when a strategy is actively monitoring a signal, typically waiting for a take profit (TP), stop loss (SL), or time expiration. It provides detailed information about the signal being monitored, including the current price being watched and the strategy's name and origin. You'll also find data about the trading symbol, percentage progress towards TP and SL, and the current unrealized profit and loss (PNL) of the position, accounting for fees and slippage. Knowing if the data is from a backtest or live trading environment is also included, along with timestamps for tracking and internal processing. The `action` property clearly indicates that the strategy is currently in an "active" state. ## Interface IStrategySchema This interface outlines the structure for defining a trading strategy within the backtest-kit framework. Think of it as a blueprint for how your strategy will generate trading signals. Each strategy needs a unique identifier, and you can add notes to help document its purpose. You can also specify a minimum time interval between signals, helping to control how often your strategy analyzes the market. The core of the strategy is the `getSignal` function, which takes market data (symbol, timestamp, and current price) and determines whether to generate a buy or sell signal. This function can also incorporate price targets, allowing signals to be scheduled and triggered when a specific price is reached. You can also set up callbacks for events like trade opening and closing. Furthermore, it allows for associating risk profiles and actions to a strategy. Finally, there's space for storing custom runtime data, useful for monitoring and external integrations. ## Interface IStrategyResult This interface, `IStrategyResult`, represents a single result from running a trading strategy backtest. Think of it as a row in a table comparing different strategies. It holds the strategy's name so you know which strategy produced the results, and a comprehensive set of backtest statistics detailing its performance. Crucially, it includes a metric value used for ranking strategies; this might be Sharpe Ratio or another key indicator. Finally, it tracks the timing of the first and last signals generated by the strategy, which can be helpful for understanding its activity over the test period. If a strategy didn't generate any signals, these timestamp values will be null. ## Interface IStrategyPnL This interface, IStrategyPnL, represents the outcome of a trading strategy's profit and loss calculation. It gives you a clear picture of how your trades performed, taking into account realistic factors like transaction fees and slippage. Here's what the data tells you: * **pnlPercentage:** This shows your profit or loss as a percentage – a positive number indicates a gain, and a negative number a loss. * **priceOpen:** This is the price you initially bought the asset at, but it's been adjusted to account for fees and slippage. * **priceClose:** This is the price you sold the asset for, also adjusted for fees and slippage. * **pnlCost:** This is the actual dollar amount you gained or lost from the trade. * **pnlEntries:** This represents the total amount of money you invested to get into those trades. ## Interface IStrategyCallbacks This interface allows you to hook into different points in a trading strategy's lifecycle within the backtest-kit framework. Think of them as event listeners that get triggered as your strategy progresses through various stages. You can receive notifications for every tick with `onTick`, giving you a constant stream of price data. Specific signals trigger events too: `onOpen` when a new signal is established, `onActive` when it’s actively being monitored, `onIdle` when there are no active signals, and `onClose` when a signal is finalized. For signals entered on a delayed schedule, `onSchedule` fires when the scheduled signal is created, and `onCancel` is called if a scheduled signal is cancelled. There are also callbacks for specific profit/loss states: `onPartialProfit`, `onPartialLoss`, and `onBreakeven` letting you react to price movements before reaching the full target or stop-loss. The `onWrite` event is primarily for testing and backtesting, allowing you to interact with the data persistence. Finally, `onSchedulePing` and `onActivePing` offer minute-by-minute updates for scheduled and active signals, letting you perform custom monitoring tasks. ## Interface IStrategy The `IStrategy` interface outlines the core methods a trading strategy needs to execute. Think of it as a blueprint for how a strategy interacts with the trading framework. Here's a breakdown of what each method does: * **`tick`**: This is the heart of the strategy; it runs with each new price update. It checks for signals, potential profit targets, and stop-loss triggers. * **`getPendingSignal`**: Finds any signals that are already active but haven't triggered yet. Used for things like monitoring profit targets and time limits. * **`getScheduledSignal`**: Similar to `getPendingSignal`, but for signals that are set to activate in the future. * **`getBreakeven`**: Determines if the price has moved enough to cover transaction costs, allowing the strategy to set a breakeven point. * **`getStopped`**: Checks if the strategy has been paused or halted. * **`getPaused`**: Checks if the strategy is temporarily paused, preventing new trades but keeping existing ones monitored. * **`setPaused`**: Allows pausing and resuming new trades. * **`getTotalPercentHeld`**: Calculates the percentage of the initial investment still in the market. * **`getRemainingCostBasis`**: Figures out how much money is still needed to cover the initial investment. * **`getPositionEffectivePrice`**: Calculates the average entry price when multiple entries have been made (DCA). * **`getPositionInvestedCount`**: Counts how many times entries have been made. * **`getPositionInvestedCost`**: Calculates the total amount invested. * **`getPositionPnlPercent`**: Determines the percentage profit or loss based on current price. * **`getPositionPnlCost`**: Calculates the total profit or loss in dollars. * **`getPositionEntries`**: Lists all the individual entry prices and costs. * **`getPositionPartials`**: Shows how the position has been closed partially over time. * **`backtest`**: Simulates how the strategy would have performed with past data. * **`stopStrategy`**: Stops the strategy from generating any new signals. * **`cancelScheduled`**: Cancels a signal that's scheduled to happen in the future. * **`activateScheduled`**: Forces a scheduled signal to happen immediately. * **`closePending`**: Closes an active position without stopping the strategy. * **`createSignal`**: Allows external signals to be added to the strategy queue. * **`createTakeProfit`**: Reports when a take-profit order was filled. * **`createStopLoss`**: Reports when a stop-loss order was filled. * **`getStatus`**: Provides a snapshot of the strategy's current state. * **`partialProfit`**: Closes a portion of the position at a profit. * **`validatePartialProfit`**: Checks if a partial profit close is possible. * **`partialLoss`**: Closes a portion of the position at a loss. * **`validatePartialLoss`**: Checks if a partial loss close is possible. * **`trailingStop`**: Adjusts the stop-loss based on price movement. * **`validateTrailingStop`**: Checks if a trailing stop adjustment is possible. * **`trailingTake`**: Adjusts the take-profit level. * **`validateTrailingTake`**: Checks if a trailing take adjustment is possible. * **`breakeven`**: Moves the stop-loss to the entry price when certain conditions are met. * **`validateBreakeven`**: Checks if setting a breakeven is possible. * **`averageBuy`**: Adds another entry to the position (DCA). * **`validateAverageBuy`**: Checks if another entry can be added (DCA). * **`hasPendingSignal`**: Checks if an active signal exists. * **`hasScheduledSignal`**: Checks if a scheduled signal exists. * A series of `get...` methods provide information on position status, history, and estimated times. * **`dispose`**: Cleans up resources when the strategy is no longer needed. ## Interface IStorageUtils This interface defines the basic operations a storage adapter needs to support within the backtest-kit trading framework. Think of it as a contract for different ways to store and manage trading signals. The adapter must be able to react to signals being opened, closed, scheduled, or cancelled. Each of these events triggers a corresponding `handleOpened`, `handleClosed`, `handleScheduled`, and `handleCancelled` method. You'll also need a way to retrieve specific signals by their unique ID using `findById`, or to get a list of all signals with `list`. Finally, the adapter needs to handle 'ping' events—specifically `handleActivePing` for signals that are currently open and `handleSchedulePing` for scheduled signals—to keep track of when they were last updated. ## Interface IStorageSignalRowScheduled This interface describes a signal's data when it's scheduled for execution. It holds two key pieces of information: the `status`, which is always "scheduled" to confirm it's a scheduled signal, and the `currentPrice`. The `currentPrice` represents the market price at the time the signal was scheduled—essentially a snapshot of the price from when the decision to execute was made. This helps in later analysis and reconciliation. ## Interface IStorageSignalRowOpened This interface describes a signal event when a trading strategy opens a position. It tells you the signal has transitioned to an "opened" state, and crucially, provides the current VWAP price at the moment the position was initiated. Think of it as a confirmation that a trade has begun, along with the price level that triggered it. Having this price information is valuable for analyzing trade performance and understanding market conditions at the time of entry. ## Interface IStorageSignalRowClosed This interface describes the data associated with a trading signal that has been closed. It's specifically for signals where we have information about the profit and loss (PNL) generated during its lifespan. Each closed signal record includes: * Its status, which will always be "closed." * The calculated profit and loss (PNL) achieved when the signal was closed. * The final price used when the signal was closed. * The reason why the signal was closed. * The exact timestamp of when the signal was closed. Essentially, it provides a complete picture of a trading signal’s performance from start to finish. ## Interface IStorageSignalRowCancelled This interface represents a signal row that has been cancelled. It's a simple way to mark a signal as no longer active or valid. The `status` property clearly indicates that the signal’s current state is "cancelled". This allows you to easily filter and identify signals that should be excluded from further processing. ## Interface IStorageSignalRowBase This interface defines the basic structure for storing signal data, ensuring that all signal types share core information. It includes the exact time the signal was created (`createdAt`) and last updated (`updatedAt`), which helps in tracking its history. A `priority` field is also included, allowing signals to be rewritten in a specific order, essentially acting as a sort key for storage. This ensures signals are processed in a consistent and predictable way whether they're generated during live trading or a backtest. ## Interface IStateInstance The `IStateInstance` interface establishes a standard way for managing data related to trading signals. Think of it as a central place to keep track of information specific to each trade, like its unrealized profit and how long it's been open. This is especially useful when using AI or machine learning models to make trading decisions, as it allows you to monitor and adjust strategies based on real-time performance. The `waitForInit` method is used to get things started, essentially marking the beginning of the data tracking for a particular trade. The `getState` method lets you retrieve this data at a specific point in time. It's designed to prevent looking too far into the future, ensuring you're only seeing information that was available at the time the trade was made. The `setState` method is how you update this data, allowing you to record changes as the trade progresses. Importantly, it prioritizes more recent data, so restarting a backtest won't corrupt ongoing data. When updating, you have access to the existing data (or a default value if it's unavailable). Finally, `dispose` cleans up any resources used by the instance when it's no longer needed. ## Interface ISizingSchemaKelly This schema defines how to size your trades using the Kelly Criterion. It's a strategy for determining how much of your capital to risk on each trade to maximize long-term growth. You’ll specify this by setting the `method` to `"kelly-criterion"` and then defining a `kellyMultiplier`. This multiplier essentially controls your aggressiveness; a lower value like 0.25 represents a more conservative "quarter Kelly" approach, while a higher value risks more capital per trade for potentially greater returns. Remember to carefully consider your risk tolerance when choosing this multiplier. ## Interface ISizingSchemaFixedPercentage This schema defines a trading sizing strategy where you consistently risk a fixed percentage of your capital on each trade. The `method` property will always be "fixed-percentage" to identify this specific sizing approach. The `riskPercentage` property dictates the percentage of your available funds you're willing to lose on a single trade; for example, a value of 2 means you risk 2% of your capital per trade. It’s essential that this value falls between 0 and 100. ## Interface ISizingSchemaBase This interface defines the fundamental structure for sizing schemas within the backtest-kit trading framework. Each sizing schema needs a unique identifier, `sizingName`, to distinguish it from others. You can also add a `note` to provide additional context or documentation for developers. The schema also includes controls for position sizing: `maxPositionPercentage` limits the percentage of your account used for any trade, while `minPositionSize` and `maxPositionSize` set absolute minimum and maximum position sizes. Finally, `callbacks` allow for optional lifecycle hooks to be attached to the sizing process, enabling custom logic to be triggered at various points. ## Interface ISizingSchemaATR This schema defines how to size your trades based on the Average True Range (ATR). It's designed for strategies where you want your position size to react to market volatility, as measured by the ATR. The `method` must be explicitly set to "atr-based" to indicate that you're using this sizing approach. You'll also specify a `riskPercentage`, which represents the portion of your capital you're willing to risk on each trade – think of it as a percentage between 0 and 100. Finally, the `atrMultiplier` determines how far your stop-loss will be placed relative to the ATR value. A higher multiplier means a wider stop. ## Interface ISizingParamsKelly This interface defines how to set up sizing parameters based on the Kelly Criterion when building a trading strategy. It focuses on providing a way to log debugging information related to sizing calculations. Specifically, you'll need to include a logger service to help track and understand how the sizing decisions are being made. This logger helps diagnose any issues and understand the strategy's behavior. ## Interface ISizingParamsFixedPercentage This interface defines the parameters needed to control how much of your capital is used for each trade when using a fixed percentage sizing strategy. It's essentially a way to tell the system how to calculate your position size based on a percentage of your available funds. The `logger` property lets you connect a logging service to monitor and debug the sizing process, providing helpful output during backtesting or live trading. This can be valuable for understanding how sizing decisions are being made. ## Interface ISizingParamsATR This interface defines the settings you'll use when determining trade sizes based on the Average True Range (ATR) indicator. It mainly consists of a `logger` property, which is used to help you debug and understand how the sizing calculations are working. The `logger` allows you to output information and errors, making it easier to troubleshoot your trading strategies. ## Interface ISizingCallbacks This section outlines the callbacks you can use to monitor and potentially influence the sizing process within the backtest-kit framework. Specifically, `onCalculate` is triggered immediately after the framework determines how much to trade based on your sizing strategy. You can use this callback to record the calculated trade size and the parameters used in the calculation, or to ensure the size makes sense given your strategy’s rules. ## Interface ISizingCalculateParamsKelly When you're using the Kelly Criterion to determine how much to bet or trade, you'll need to provide certain parameters. This set of parameters defines specifically that you want to use the Kelly Criterion method for sizing. To do this, you need to tell the system your win rate, expressed as a number between 0 and 1 (like 0.6 for 60%), and also your average win-loss ratio - how much you typically win compared to how much you lose on a winning trade. These two values help the system calculate an appropriate sizing amount based on the Kelly Criterion formula. ## Interface ISizingCalculateParamsFixedPercentage This interface defines the data needed to calculate trade size using a fixed percentage approach. It requires specifying the method as "fixed-percentage" to indicate the sizing strategy. You’ll also need to provide a `priceStopLoss` value, representing the price level at which a stop-loss order will be triggered. This value helps in determining the risk associated with each trade. ## Interface ISizingCalculateParamsBase This defines the basic information needed for calculating how much of an asset to trade. It includes the symbol of the trading pair, like "BTCUSDT" to identify the asset being traded. You’ll also find the current account balance, which is crucial for determining how much capital is available for trading. Finally, the planned entry price, or the price at which you intend to enter the trade, is provided for sizing calculations. ## Interface ISizingCalculateParamsATR This interface defines the settings needed when you're determining how much of your capital to allocate to a trade based on the Average True Range (ATR). You'll provide a `method` which will always be "atr-based" to indicate you’re using this specific sizing technique. Then, you need to specify the `atr` value itself – this is the ATR value you've calculated, and it’s crucial for determining your position size. Think of it as a key input that drives how much risk you're taking. ## Interface ISizing The `ISizing` interface defines how your trading strategy determines the size of each position it takes. Think of it as the engine that figures out how much to buy or sell based on your risk tolerance and the market conditions. It has a single, crucial method called `calculate`. This method takes a set of parameters – essentially the information it needs to make a sizing decision – and returns a promise that resolves to the calculated position size, representing the quantity of an asset to trade. ## Interface ISignalRow This interface, `ISignalRow`, represents a complete trading signal ready to be executed. It bundles a lot of information together, making it easy to handle a signal throughout the trading process. Each signal gets a unique ID automatically assigned. You’ll find details about the trade itself, like its cost, entry price, and the timeframe it's intended to run. It also includes important settings like leverage (multiplier) and whether it uses isolated margin. Custom data can be attached to each signal using the `payload` field. Other information such as the exchange, strategy, frame, and creation/pending timestamps is also included. The `ISignalRow` also keeps track of complex details: * It records partial closes (profit or loss) to calculate accurate PNL. * It holds trailing stop-loss and take-profit prices, which dynamically adjust based on market movements. * It maintains a history of entries if you're using DCA (Dollar Cost Averaging). * It tracks the highest profit and lowest loss points achieved during the position's life. Finally, `timestamp` captures when the signal was initially created, providing a record of its origin. ## Interface ISignalIntervalDto This data structure helps manage signals, especially when you need to group them together and release them at specific intervals. Think of it as a way to bundle multiple signals into one request and control when they become active. Each signal has a unique ID, like a serial number, so you can easily identify and track it. This is useful for situations where you want to wait a certain amount of time before processing several signals. ## Interface ISignalDto This data structure represents a trading signal – essentially, an instruction to buy or sell an asset. It contains all the necessary information to execute a trade, including the ticker symbol, whether it's a long (buy) or short (sell) position, and a description of why the signal was generated. You can provide a unique ID for the signal, but if you don't, the system will automatically create one. The signal also includes details for managing the trade, such as target take profit and stop-loss prices, and an estimated duration. You can optionally add custom data to the signal through a flexible "payload" section. Cost and leverage settings allow for fine-tuning how the trade is executed and the potential profits or losses. Finally, it supports isolated margin, which can affect how and when the position might be closed. ## Interface ISignalCloseRow This interface defines the structure of a signal row when a trade has been closed, specifically when the closure was initiated by the user. It builds upon the basic signal row information, adding details about the closure itself. If a user manually closes a trade, this interface provides fields to record the unique identifier (`closeId`) of that closure and any notes (`closeNote`) the user might have provided during the closure process. These properties are only relevant when a user has explicitly closed the trade. ## Interface ISessionInstance This interface helps manage temporary data during backtesting, providing a way to store and retrieve information specific to a combination of a trading symbol, strategy, exchange, and timeframe. Think of it as a small, isolated notebook for each of these combinations, letting you keep track of things like calculations from complex models or intermediate results from indicators. It allows you to initialize the data, write new information with a timestamp, retrieve existing data, and clean up when the testing is done. Importantly, when reading data, it prevents looking into the future, ensuring a fair and accurate backtest. This is particularly useful for things like caching results from computationally expensive processes or keeping track of states that need to be shared across different calculations during a single backtest run. ## Interface IScheduledSignalRow This interface describes a signal that’s held back until a specific price is reached. Think of it as a signal that’s waiting for a chance to execute – it’s not active yet. It's based on a standard signal but delayed, waiting for the market to hit a particular price, `priceOpen`. Once that price is reached, this delayed signal activates and becomes a regular signal ready for trading. A key aspect is that the time it's been pending will be tracked, starting from the initial scheduling time and updating to the actual time it waits. The `priceOpen` property simply defines that target price. ## Interface IScheduledSignalCancelRow This interface represents a scheduled trading signal, but with extra information for cancellations that a user might initiate. When a user cancels a signal, this interface lets you record a unique ID (`cancelId`) associated with that cancellation, along with a note (`cancelNote`) explaining why the cancellation happened. Think of it as a way to track user-driven changes to your scheduled trading signals. If the signal wasn't cancelled by a user, these fields will not be present. ## Interface IScheduledSignalActivateRow This interface describes a scheduled signal, but with a key addition: it includes information related to how that signal was activated. Specifically, it’s used when a user manually triggers the signal, allowing for tracking and notes. The `activateId` property holds a unique identifier associated with that user-initiated activation, and the `activateNote` field stores any notes the user included when activating the signal. Think of it as a way to link a scheduled signal’s execution back to a specific user action. ## Interface IRuntimeRange This interface, `IRuntimeRange`, essentially tells you the timeframe you’re working with during a backtest. It defines the start and end dates—the “from” and “to” properties—that bracket the period your trading strategy will be tested on. Think of it as setting the boundaries for your historical data analysis. It lets the backtest know exactly what dates to pull data for and run the strategy against. ## Interface IRuntimeInfo The `IRuntimeInfo` interface provides essential details about the current trading scenario. It tells you what symbol you’re trading, like "BTCUSDT," and the timeframe of the backtest if you're analyzing historical data. You'll also get custom information passed in by your strategy, enabling you to track specific metrics. The interface also gives you context about the exchange, the strategy itself, and the data frame being used, and even the precise timestamp of the current candle or tick, along with the current price. A key piece of information is whether the strategy is running in backtest mode or live. ## Interface IRunContext This interface, `IRunContext`, acts as a central hub of information needed when running code within the backtest-kit trading framework. Think of it as a comprehensive package containing everything a function needs to know about its environment. It merges two key pieces of information: details about the trading strategy and exchange you’re using (like exchange name and frame) along with the real-time state of the backtest, such as the symbol being analyzed and the current timestamp. This `IRunContext` is then used to pass all this relevant information to the appropriate services, keeping things organized and efficient. ## Interface IRiskValidationPayload This object holds the information needed for risk validation checks. It builds upon the basic arguments for risk checks by adding details about the current trading situation. You'll find the `currentSignal` which represents the signal that's currently being evaluated - it includes all the necessary price data. Also included are details about the portfolio's current state: the number of open positions (`activePositionCount`) and a list of those positions (`activePositions`). This allows risk checks to consider how existing positions might interact with new trades. ## Interface IRiskValidationFn This defines the blueprint for functions that check if a trade or order is acceptable based on specific risk rules. Think of it as a gatekeeper for your trades. If everything looks good – the trade aligns with your risk parameters – the function simply lets it pass through, returning nothing. But, if something is amiss – perhaps the potential loss is too high – it signals a problem. It can either return a detailed explanation of why the trade was rejected or, alternatively, raise an error that the framework will handle and translate into a rejection message. ## Interface IRiskValidation This interface lets you define how to check if your trading risks are acceptable. Think of it as setting up rules to ensure your trading strategy doesn't take on too much danger. You specify the actual check with the `validate` function, which performs the risk assessment. The `note` property is there to add a helpful explanation of what the validation is doing – it’s like a comment to yourself or others to clarify the logic. ## Interface IRiskSignalRow The `IRiskSignalRow` interface holds information crucial for managing risk during trading. It builds upon the existing `ISignalDto` and adds key details like the entry price (`priceOpen`), the initial stop-loss price (`originalPriceStopLoss`), and the original take-profit price (`originalPriceTakeProfit`). This data is specifically used during risk validation, providing access to the original entry price and initial stop-loss/take-profit levels. Essentially, it allows the system to track and validate risk parameters related to each trade signal. ## Interface IRiskSchema The `IRiskSchema` lets you define and register specific risk controls for your portfolio. Think of it as setting up guardrails to ensure your trading strategy stays within acceptable boundaries. Each risk schema has a unique identifier, a `riskName`, which helps you keep track of different risk profiles. You can also add a note to document your intentions. You can optionally specify callbacks, which are like notifications that trigger at certain points in the risk assessment process (when a trade is blocked or allowed). Most importantly, the `validations` property is where you define the actual rules—the custom logic that determines if a trade is permitted. This is an array, allowing you to layer multiple validations to create complex risk management strategies. ## Interface IRiskRejectionResult This object tells you why a risk check failed. It has a unique ID to help track specific rejections and a clear explanation in plain language describing the reason for the failure. Think of it as a friendly notification letting you know what went wrong during a risk assessment and why. ## Interface IRiskParams The `IRiskParams` object is how you configure the risk management system within backtest-kit. It's essentially a set of settings you provide to ensure your trading decisions are made responsibly. You'll need to specify the `exchangeName` you're working with, like "binance". A `logger` allows you to track what’s happening for debugging purposes. Crucially, you'll get a `time` service that helps keep things accurate – it prevents the system from looking into the future when analyzing past trades or making real-time decisions. The `backtest` flag indicates whether you're running a simulation (backtest) or live trading. Finally, the `onRejected` callback lets you react when a trading signal gets blocked due to risk constraints; this allows you to perform custom actions or emit additional events. ## Interface IRiskCheckOptions To help ensure safety when multiple parts of your trading strategy are trying to adjust positions at the same time, the `IRiskCheckOptions` lets you reserve a placeholder in your position map. Think of it like putting a temporary hold on a position size. This 'reserve' option, when set to `true`, ensures that other checks happening simultaneously will see the updated, reserved size before any actual changes are made. This avoids potential conflicts and ensures a more reliable trading environment, especially in complex strategies. It's all about preventing unexpected overlaps in position adjustments. ## Interface IRiskCheckArgs This interface, `IRiskCheckArgs`, bundles all the information needed to decide whether a new trade should be allowed. Think of it as a set of validation checks run *before* a trading signal is actually generated. It includes details like the trading pair being considered (symbol), the pending signal itself, the name of the strategy initiating the request, and information about the exchange and risk profile involved. You'll also find details like the current price and timestamp, providing context for the risk assessment. Essentially, it’s a snapshot of the situation right before a potential trade happens, ensuring everything aligns with your pre-defined rules. ## Interface IRiskCallbacks This interface defines optional functions that your trading strategies can use to react to risk management decisions. Specifically, you can provide an `onRejected` function that gets called whenever a trading signal is blocked because it exceeds defined risk limits. Conversely, the `onAllowed` function is triggered when a signal successfully passes all risk checks and is approved for execution. These callbacks allow your strategy to log, monitor, or take other actions based on the risk assessment results. ## Interface IRiskActivePosition This interface describes a single, active trading position that's being monitored for risk management. Think of it as a snapshot of a trade happening right now. It tells you which strategy placed the trade, on which exchange, and what frame (like a 5-minute chart) it was based on. You’ll find the symbol being traded (like BTCUSDT), whether the position is a long or short, and the price at which the trade was initiated. It also includes the stop-loss and take-profit prices set for the trade to protect and secure profits. Finally, you can see the estimated duration and a timestamp showing precisely when the trade started. ## Interface IRisk The `IRisk` interface is responsible for managing and enforcing risk limits when executing trading strategies. It allows you to verify if a proposed trade should be allowed based on predefined risk parameters. The `checkSignal` function determines if a trade can proceed based on the current risk profile. A safer, atomic version called `checkSignalAndReserve` does this and immediately reserves space for the potential new position – preventing other strategies from exceeding limits concurrently. It’s essential to follow up a successful `checkSignalAndReserve` with either `addSignal` (to finalize the position) or `removeSignal` (to cancel it), to avoid accumulating incorrect reservation data. You use `addSignal` to register a new, opened trading position within the system. Conversely, `removeSignal` allows you to clean up a closed or cancelled position. ## Interface IReportTarget This interface lets you fine-tune what information gets logged during your backtesting process. Think of it as a control panel for detailed reporting. You can choose to specifically enable logging for things like strategy execution, risk management decisions, breakeven points, partial trade closures, performance data, scheduled events, live trading activity, or significant milestones like achieving highest profit or hitting maximum drawdown limits. Each property (strategy, risk, breakeven, etc.) is a simple on/off switch for a different type of reporting. By enabling only the reports you need, you keep your logs clean and focused on the aspects most important to you. ## Interface IReportDumpOptions This interface helps you control how data is written for reports, letting you specify key details about the trading activity. You can use it to define things like the trading pair (like BTCUSDT), the name of the strategy being used, and the exchange where the trades occurred. It also includes the timeframe, a unique identifier for the signal, and the name of the walker used for optimization. By providing these details, you ensure your reports are well-organized and easy to understand. ## Interface IRecentUtils This interface defines how different systems can store and manage recent trading signals. It's designed to ensure that backtesting and live trading use the same signal data, preventing look-ahead bias. The `handleActivePing` method lets you receive and save new signal data. `getLatestSignal` fetches the most recent signal for a specific trading setup (symbol, strategy, exchange, timeframe, and whether it’s a backtest). Crucially, it avoids using signals from the future – if a signal’s timestamp is later than the date you're requesting, it won’t be returned. Finally, `getMinutesSinceLatestSignalCreated` calculates how long ago the last signal was generated, useful for understanding signal frequency and potential delays. ## Interface IPublicSignalRow This interface, IPublicSignalRow, is designed to give you a clear view of a trading signal, especially its initial risk management settings. It builds upon the standard signal information by including the original stop-loss and take-profit prices that were set when the signal was first created. This is helpful because even if you’re using trailing stops or take-profits that adjust those levels, you can still see what the initial plan was. Beyond the basics, it also provides insight into how the position has evolved. You'll find details about the cost of entering the trade, how much of the position has been closed through partial exits, and how many entries and partials were involved. The signal’s original entry price is also included, along with its current unrealized profit/loss (PNL), the highest profit reached so far (peak profit), and the maximum drawdown experienced – all calculated at the time the signal was generated. Essentially, IPublicSignalRow offers a comprehensive snapshot of a signal’s history and current status. ## Interface IPublicCandleData This interface defines the structure for a single candlestick representing price data over a specific time interval. Each candlestick contains key information like when it began (timestamp), the opening price, the highest and lowest prices reached during that period, the closing price, and the total trading volume. Essentially, it’s a snapshot of market activity encapsulated within a single data point for charting and analysis. ## Interface IPositionSizeKellyParams The `IPositionSizeKellyParams` interface defines the settings you'll use when calculating position sizes based on the Kelly Criterion. This criterion helps determine how much of your capital to risk on each trade. You'll provide two key pieces of information: your win rate, which is a value between 0 and 1 representing the percentage of winning trades, and your win/loss ratio, which describes the average profit you make on a winning trade compared to the average loss on a losing trade. These parameters together let the framework calculate a suggested position size to optimize for long-term growth. ## Interface IPositionSizeFixedPercentageParams This interface defines the settings needed for a trading strategy that uses a fixed percentage of your capital for each trade, and includes a stop-loss price. Specifically, you'll use this to tell the backtest system how much of your funds to risk on each trade and at what price you want to limit potential losses. The `priceStopLoss` property represents the price at which you'll automatically exit a trade to prevent further losses. ## Interface IPositionSizeATRParams The `IPositionSizeATRParams` interface holds the settings needed to determine your position size using the Average True Range (ATR) method. It's a simple way to manage risk by adjusting your trade size based on market volatility. The key piece of information it contains is the current ATR value. This number reflects the average range of price movement over a specific period, providing a sense of how volatile the market is. You'll use this ATR value within your trading strategy to calculate the appropriate position size. ## Interface IPositionOverlapLadder This configuration defines how to detect overlapping positions when using dollar-cost averaging (DCA). It lets you set boundaries, expressed as percentages, around each DCA level. The `upperPercent` property specifies a percentage above each DCA level where any position would be considered an overlap. Similarly, the `lowerPercent` property defines a percentage below each DCA level that also triggers an overlap flag. Think of these as zones of tolerance—if a position falls within these zones around a DCA level, it's considered to be overlapping. This helps you fine-tune how strictly you want to identify potential conflicts between your DCA positions. ## Interface IPersistStrategyInstance This interface helps you manage how strategy data is saved and loaded for specific combinations of a trading symbol, the name of the strategy being used, and the exchange involved. Think of it as a way to customize where and how a strategy remembers its progress between sessions. You'll use this if you want to go beyond the default file-based storage. The `waitForInit` method prepares the storage area specifically for your strategy. `readStrategyData` retrieves any previously saved strategy data. And `writeStrategyData` is how you save the current state of your strategy, which can also be used to erase the saved data by passing null. ## Interface IPersistStorageInstance This interface defines how your custom storage solutions interact with the backtest-kit framework. Think of it as a way to manage and save the data related to trading signals, but specifically for either the backtesting phase or live trading. It allows you to replace the default file-based storage with something else, like a database or in-memory store, if you need to. The `waitForInit` method is used to prepare your storage when the framework starts up, setting everything up correctly for either backtesting or live mode. `readStorageData` retrieves all the previously saved signals, returning them as a collection. Finally, `writeStorageData` saves the current set of signals, organizing them by their unique identifier. ## Interface IPersistStateInstance This interface helps manage how your trading strategy's data is saved and loaded, especially important for strategies that might crash or need to recover. Think of it as a way to ensure your strategy remembers where it left off. It's specifically tied to a combination of a signal and a bucket, meaning it handles storage separately for different data streams. If you want to customize how your strategy’s state is stored – maybe you don't want to use files – you can create your own adapter that implements this interface. The `waitForInit` method is used to get the storage ready to go at the start. `readStateData` fetches any previously saved state. `writeStateData` handles saving the current state, including a timestamp. Finally, `dispose` releases any resources being used, though this might not always need to be customized. ## Interface IPersistSignalInstance This interface lets you customize how signal data is saved and loaded for a specific trading setup – think of it as a dedicated storage space for signals related to a particular symbol, strategy, and exchange. If you want to move beyond simple file storage, you can create your own adapter that implements this interface. The `waitForInit` method allows you to prepare the storage area when it's needed, providing an initial state if necessary. `readSignalData` retrieves any previously saved signal information, and `writeSignalData` lets you store new or updated signal data, or even clear the data entirely by sending null. This gives you control over how your trading system remembers and uses historical signal information. ## Interface IPersistSessionInstance This interface defines how a system can reliably store and retrieve session information related to a specific trading strategy, exchange, and frame. Think of it as a way to save progress or state for a particular setup, so you can pick up where you left off even if things go wrong. If you're building a custom solution for managing this data – perhaps not wanting to use a file-based approach – you’ll need to implement this interface. Here's what you'll need to do: * **waitForInit:** A way to prepare the storage space when things start up. You'll tell the system whether it's the first time the storage is being initialized. * **readSessionData:** A method to load any previously saved data associated with the current strategy, exchange, and frame combination. * **writeSessionData:** A way to save the current state or data related to the current session. This ensures any progress is saved. * **dispose:** A way to clean up and release any resources that are being held by your custom solution. This might not be needed if your implementation doesn't actually manage any resources. ## Interface IPersistScheduleInstance This interface defines how your custom code interacts with the backtest-kit framework to save and load scheduled signals for a specific trading setup. Think of it as a way to manage the data that tells your strategy when to execute, allowing you to use a database or other storage method besides the default file system. It provides three key functions: `waitForInit` which prepares the storage space, `readScheduleData` which retrieves a previously saved signal, and `writeScheduleData` which stores a new signal. You’ll need to implement this interface if you’re building a more sophisticated system for persisting your scheduled signals. The context being referred to is determined by the unique combination of symbol, strategy name, and exchange name. ## Interface IPersistRiskInstance This interface defines how to manage and store the active risk positions for a specific trading context. Think of it as a way to save and load the state of your risk management for a particular combination of risk name and exchange. If you want to use a different storage method than the default file-based system—perhaps a database or in-memory store—you can create an adapter that implements this interface. The `waitForInit` method allows you to initialize the storage when needed, providing a way to set up any necessary resources. The `readPositionData` method retrieves the saved risk positions for a given time, letting you load the state from storage. Finally, `writePositionData` is used to save the current risk positions, ensuring that the system remembers the active positions. ## Interface IPersistRecentInstance This interface defines how to manage and store the most recent trading signal for a specific setup, like a particular symbol, strategy, or exchange. It helps keep track of the last signal used so you can easily resume from where you left off, whether you're backtesting or running a live strategy. If you want to use a different way to store this information – perhaps a database instead of a file – you can create a custom adapter that implements this interface. The `waitForInit` method sets up the storage space for your specific context. `readRecentData` retrieves the last saved signal. `writeRecentData` saves the current signal, along with a timestamp. ## Interface IPersistPartialInstance This interface lets you manage how partial profit and loss information is saved and loaded. Think of it as a way to keep track of a trading strategy's progress at specific points in time, but only for a particular combination of asset, strategy name, and exchange. Each signal, representing a trade or decision, has its own dedicated space for storing this information. If you want to change where and how this data is stored - for example, using a database instead of files - you can build your own adapter that follows this interface. The `waitForInit` method prepares the storage area for your specific setup. `readPartialData` retrieves previously saved partial data for a particular signal and time. Finally, `writePartialData` saves the current partial data for a signal to persist across sessions. ## Interface IPersistNotificationInstance This interface lets you customize how trading notifications are saved and loaded. Think of notifications as important events that happen during a trade, and you want to keep a record of them. This interface defines a way for you to create your own system for managing these notifications, rather than relying on the default file-based storage. It essentially provides a set of tools to initialize, read, and write these notifications, ensuring they're available when you need them, whether you're running a backtest or a live trading session. Each trading mode (backtest or live) will have its own separate instance of this. ## Interface IPersistMemoryInstance This interface defines how memory data is stored and retrieved for specific contexts within the backtest-kit framework, particularly for Large Language Model (LLM) memory. Think of it as a way to manage individual pieces of information, each labeled with a unique identifier. It allows you to read, write, and delete memory entries – although deletion is actually a "soft delete," meaning the data remains on disk but is hidden from normal searches. You can also check if a specific memory entry exists. The `listMemoryData` function provides a way to get all currently available memory entries, which is useful for rebuilding indexes. Finally, `dispose` allows for releasing any resources used by this storage. If you’re creating custom ways of managing this memory, you’ll need to implement this interface to control how memory data is handled. ## Interface IPersistMeasureInstance This interface defines how to store and retrieve cached data for backtest measures. Think of it as a way to save results from external APIs so you don't have to repeatedly fetch them. It allows for a "soft delete" feature, meaning when you remove data, it's not actually erased from disk, but marked as removed, allowing for potential recovery or auditing. If you need to customize how this caching works – for example, if you wanted to store data in a database instead of a file – you would implement this interface. Here’s what the methods do: * `waitForInit`: Sets up the storage area for the bucket. * `readMeasureData`: Retrieves a cached data entry using a unique key. * `writeMeasureData`: Saves a data entry to the cache along with a timestamp. * `removeMeasureData`: Marks a data entry as removed, making it unavailable for regular retrieval. * `listMeasureData`: Provides a way to see a list of all the keys of the data that haven't been marked as removed. ## Interface IPersistLogInstance This interface lets you customize how backtest-kit stores its log data. Instead of relying on the default file-based storage, you can build your own adapter to persist logs somewhere else, like a database. The log storage itself is global – meaning there’s only one instance running for the entire backtest-kit process. Each log entry is identified by a unique ID. You’ll need to provide an implementation for `waitForInit` to set up your logging mechanism and `writeLogData` to save the log entries, making sure to avoid duplicates based on their IDs. `readLogData` handles retrieving all the stored log data. ## Interface IPersistIntervalInstance This interface lets you customize how backtest-kit remembers which intervals have already run for a specific data bucket. Think of it as a way to track whether a particular trading strategy has already executed for a given time period and data. If you're building your own storage solution instead of relying on the default file-based system, you'll implement this interface. The methods allow you to: * Initialize storage when needed. * Retrieve existing interval markers based on a unique key. * Save new interval markers, associating them with a key and timestamp. * "Soft-delete" markers – essentially telling the system that the interval can run again. This is how you'd re-trigger an interval if needed. * List all the interval markers that haven’t been soft-deleted. ## Interface IPersistDictionaryInstance This interface helps manage how dictionaries of data are stored and retrieved, especially when dealing with potentially unstable situations. Think of it as a way to make sure your dictionaries don’t get lost if something unexpected happens during a backtest. It defines how to initialize, load existing data, save new data, and clean up resources related to a specific dictionary – this is tied to a particular signal and dictionary name. If you need to change how these dictionaries are stored (perhaps not using files), you can create a custom adapter that follows this interface. Here's a breakdown of what's involved: * `waitForInit`: Sets things up for the storage of the dictionary. * `readDictionaryData`: Loads any previously saved dictionary data. * `writeDictionaryData`: Saves the current state of the dictionary. * `dispose`: Cleans up any resources used by the storage. ## Interface IPersistCandleInstance This interface defines how to store and retrieve candle data for a specific trading symbol, time interval, and exchange. It’s like a dedicated storage area for candles related to a particular combination of these factors. The `waitForInit` method prepares the storage space when needed. The `readCandlesData` method is your way to get a set of cached candles from the storage within a defined time range, and importantly, it returns `null` if even one candle is missing – this signals you need to go back to the source to fetch those missing candles. The `writeCandlesData` method lets you write new or updated candle data back into this storage. Implementations might choose to ignore incomplete or already existing candles to ensure data integrity. ## Interface IPersistBreakevenInstance This interface helps manage where your trading strategy's breakeven points are saved – those crucial calculations that tell you when you've recovered your initial investment. Think of it as a personalized storage space for each signal, tied to a specific trading combination like a symbol, strategy, and exchange. You don't always need to interact with this directly. The framework has a default way to store this information, usually in a file. However, if you want to control exactly how these breakeven points are saved, like maybe using a database instead of a file, you can build your own adapter that implements this interface. Essentially, it provides two key functions: * `waitForInit` sets up the storage area for a particular trading context. * `readBreakevenData` retrieves a previously saved breakeven point for a specific signal. * `writeBreakevenData` saves a new or updated breakeven point. ## Interface IPersistBase This interface is designed to let you build your own ways of storing and retrieving data for backtesting. Think of it as a set of basic rules for how your storage system should behave. It outlines the essential actions you'll need: preparing the storage space, reading data, checking if data exists, writing data, and getting a list of all the data you have. The `waitForInit` method handles initial setup and makes sure it only runs once. `readValue` and `hasValue` let you fetch existing data. `writeValue` ensures data is saved correctly, and `keys` provides a way to list all the data identifiers in a sorted order, which is useful for checks and looping through everything. You'll implement this interface to connect your backtest kit to your specific storage solution, whether it's a file system, a database, or something else entirely. ## Interface IPartialProfitCommitRow This represents a single instruction to take a partial profit on a trade. It's like a message saying "close a portion of this position." The `action` property confirms this is a partial profit instruction. `percentToClose` tells you what percentage of the existing position should be closed. Finally, `currentPrice` records the price at which this partial profit closing occurred. ## Interface IPartialLossCommitRow This represents a single instruction to partially close a position as part of a backtesting process. Think of it as a record of one specific action: reducing the size of a trade, but not closing it entirely. It tells you the percentage of the position to close, the price at which the partial closing occurred, and confirms that the action being taken is a partial loss. These details are crucial for accurately reconstructing the trading logic and analyzing results. ## Interface IPartialData This data structure helps save and restore important information about a trading signal. Specifically, it stores the profit and loss levels that have been hit. Think of it as a snapshot of the signal's performance – it remembers how far it’s progressed toward profit or loss. The `profitLevels` and `lossLevels` properties are lists that hold this data. They're designed to be easily saved to a file or database, and then loaded back into the system later to resume a backtest. These lists represent what were originally sets of levels. ## Interface IPartial The `IPartial` interface manages how your trading signals track profit and loss. It’s responsible for keeping tabs on milestones like reaching 10%, 20%, or 30% profit or loss. The `profit` method is triggered when a signal is making money, and it figures out which profit levels have been achieved, sending out notifications for each new level. Similarly, the `loss` method handles situations where a signal is losing money, identifying and reporting when different loss levels are hit. Finally, the `clear` method cleans up the tracking when a signal is finished, ensuring that old data is removed and resources are freed. This happens when a signal hits a target price or time limit. ## Interface IParseArgsResult The `IParseArgsResult` object holds the outcome when you process command-line arguments for your trading application. It essentially combines the original input arguments with flags that determine the trading mode – whether you’re simulating a backtest using historical data, practicing with paper trading, or executing real trades. The object clearly indicates whether backtest mode, paper trading mode, or live trading mode is enabled based on how you launched the application. This makes it easy to understand the intended operation of your trading system. ## Interface IParseArgsParams This interface describes the basic information needed to run a backtest. Think of it as a recipe – it tells the backtest-kit what it needs to know to get started. It includes things like the trading pair you're interested in (like BTCUSDT), the name of the trading strategy you want to test, which exchange you're connecting to (like Binance or Bybit), and the timeframe of the data you'll be using (like hourly or daily candles). Providing these values helps the system understand exactly what to test and where to get the necessary data. ## Interface IOrderBookData This interface represents the data you'll receive for an order book, which shows the current buying and selling interest for a specific trading pair. It contains three key pieces of information: the `symbol` which identifies the trading pair (like BTC/USD), a list of `bids` representing buy orders, and a list of `asks` representing sell orders. Each bid and ask includes details like price and quantity, giving you a snapshot of what buyers and sellers are offering. ## Interface INotificationUtils This interface defines how different systems can receive updates and notifications from the backtest-kit trading framework. Think of it as a central point for delivering information about strategy events, order status, and potential issues. It includes methods for reacting to various signals like when a strategy initiates a trade (opens), closes a trade, or needs to adjust profit targets. You'll also find ways to be notified about partial profit or loss opportunities, and when strategies are committed to specific actions. The framework also keeps you informed about the status of your orders – whether they're being checked, filled, rejected, continuing, or stopped – and about potential risks or pauses in the strategy. Error and validation events have dedicated handlers too. Finally, you can retrieve a record of all past notifications and clear this history when needed. This is useful for debugging or auditing purposes. ## Interface INotificationTarget This interface lets you pick and choose exactly which types of notifications you want to receive from the backtest or live trading environment. Instead of getting everything, you can specify which events are important for your needs, making the process cleaner and more efficient. Here's a breakdown of the different notification categories you can enable: * **Signal Events:** These relate to the creation, scheduling, and cancellation of trading signals. * **Partial Profit/Loss & Breakeven:** Get notified when the price hits predefined profit, loss, or breakeven levels before a trade is committed. * **Strategy Commitments:** Track when different types of actions (profit taking, loss limiting, order activations) are executed. * **Order Synchronization:** Monitor the status of orders placed with the exchange – when they're opened, filled, or confirmed. * **Order Checks:** Verify that orders remain active on the exchange. This is crucial for live trading. * **Order Fills & Rejects:** Receive notifications for order confirmations or rejections from the broker. * **Order Continuation/Stopping:** Track the resolution of order checks, whether they continue or stop. * **Risk Management:** Be alerted if your trades are blocked by risk rules. * **Informational Messages:** Get extra notes and information related to signals. * **Strategy Pause:** Know when the strategy is paused and no new trades are being initiated. * **Errors:** Handle both recoverable errors and critical, potentially fatal errors, along with validation errors during configuration. By selectively enabling these categories, you fine-tune the information flow and avoid being overwhelmed by unnecessary alerts. ## Interface IMethodContext The `IMethodContext` interface acts like a little packet of information that gets passed around during backtesting. It holds the names of the schemas – think of them as blueprints – for the exchange, strategy, and frame being used. Essentially, it ensures that the backtest kit knows *exactly* which strategy, exchange, and data frame it's working with. This helps it pick out the correct versions of those components and run the backtest smoothly. The frame name will be empty if you're running in live mode, not historical. ## Interface IMemoryInstance The `IMemoryInstance` interface sets the rules for how memory is managed within the backtest-kit framework. Think of it as a blueprint for different ways data can be stored and accessed during a backtest. It provides methods for initializing the memory, writing new data points, searching for specific information, listing all entries, and removing data. You can use it to build different storage solutions, whether that's storing data in local memory, a persistent database, or even a dummy setup for testing. The `waitForInit` method lets you ensure the memory is ready before you start. `writeMemory` lets you add new data, including details like a description and timestamp. `searchMemory` lets you find what you need using a full-text search, while `listMemory` provides a way to view everything stored up to a certain point in time. If something becomes obsolete, you can remove it with `removeMemory`. `readMemory` is for retrieving specific data points. Finally, `dispose` cleans up any resources when you are finished. ## Interface IMarkdownTarget This interface lets you pick and choose which detailed reports you want to see when using the backtest-kit framework. You can turn on or off reports for things like strategy signals, risk management decisions, breakeven points, partial profits, portfolio heatmaps, strategy comparison, performance bottlenecks, scheduled signals, live trading activity, or the full backtest results. Each property controls a specific type of reporting, so you can focus on the areas most relevant to your analysis. For example, if you’re primarily interested in how your strategy generates signals, you could enable the `strategy` property and disable others. ## Interface IMarkdownDumpOptions This interface, `IMarkdownDumpOptions`, helps organize how information is presented when generating documentation. Think of it as a container for details about a specific piece of data you want to document, like a trading strategy’s performance. It provides structured data regarding the location and context of that data, ensuring consistency across your documentation. It includes things like the path to the file, the filename, the trading pair (symbol) involved, the name of the strategy, the exchange being used, the timeframe (frameName), and a unique identifier for a signal. Having all this information together makes it easy to locate and understand the source of the documentation being generated. ## Interface IMCPTextMessage This interface defines a simple text message used within the Model Context Protocol (MCP). Each message has a unique ID to help with tracking and ensuring it's delivered correctly. The `type` property clearly indicates that this is a text message, and the `text` property holds the actual message content – the words being sent. Essentially, it's a standardized way to send plain text within the MCP system. ## Interface IMCPSignalNotifyCommand This command is used to send a notification related to a specific trading symbol. It's part of a system called MCP, which handles communication and context within the trading framework. Essentially, when a trade is about to happen, this command broadcasts an informational message ("signal.info") about the position being prepared. The notification includes the symbol being traded (like "BTCUSDT"), the name of the system that triggered the notification, and a custom note to provide more details about the situation. Think of it as a way to keep everyone informed about what's happening before a trade executes. ## Interface IMCPSchema This defines a way to connect a specific trading strategy to a control system, called an MCP. Think of it as a blueprint for how a system manages and interacts with a strategy. Each blueprint (IMCPSchema) gives a unique name to the strategy it controls and links it to specific settings. If multiple strategies are involved, you *must* clearly specify which strategy the blueprint applies to, to avoid confusion. You can customize how much money is risked on each trade (positionCost) and how much leverage is used (multiplier). There are also default values if you don't provide these. It’s possible to restrict which actions can be taken by a connected system, setting permissions for different commands. The system can also generate messages summarizing the portfolio’s status. These messages are sent to the connected system. Finally, you can specify certain "callbacks" - functions that will run at specific points in the process, though these are completely optional. ## Interface IMCPPositionOpenCommand This interface defines the information needed to open a new trading position using the backtest-kit framework. It’s used when a strategy wants to execute a trade – either buying (long) or selling (short) a specific cryptocurrency pair. The command includes the symbol being traded (like BTCUSDT), the direction of the trade, a name identifying which strategy is making the request, and a note to explain why the trade is happening. Essentially, it's a structured way to tell the system "open a position for this asset, in this direction, with this reason." ## Interface IMCPPositionCloseCommand This interface defines the data needed to tell the system to close an existing position for a specific trading pair. Think of it as the instruction to shut down a trade. It includes the symbol of the asset being traded, like "BTCUSDT," and the name of the underlying strategy or system that's initiating the closure request. A descriptive note is also required, allowing you to add a reason for why you're closing the position – useful for record-keeping and understanding your trading decisions. ## Interface IMCPImageMessage This describes a message used within a system to transmit image data, like a visual chart or graph. Each image message has a unique ID to ensure it's delivered correctly and isn't processed multiple times. The message clearly identifies itself as an "image" type, and includes the image's mime type, such as "image/png," to specify the format of the data. Finally, the message carries the actual image data, which is encoded as a base64 string. ## Interface IMCPContext The `IMCPContext` is like a quick picture of your trading portfolio at a specific moment. It’s delivered to your strategy's functions so you can make decisions based on what you own. Think of it as a record, organized by the symbol of the asset being traded, providing a snapshot of the portfolio's state for each active trading instance. ## Interface IMCPCallbacks This section describes callbacks you can use to monitor the actions of a Model Context Protocol (MCP) instance. Think of them as ways to peek under the hood and see what the system is *actually* doing after certain operations complete. They don't change how things work; they just let you observe. Here's a breakdown of the available callbacks: * `onStatus`: This callback is triggered when the status of a portfolio is refreshed. It gives you access to the data the system used to create the snapshot and any messages generated during that process. * `onPositionOpen`: You'll receive this when a new position is opened successfully. The data includes the original signal details and the specific parameters used for the order. * `onPositionClose`: This gets fired when a position is closed. It provides the ID of the signal that prompted the closure. * `onAverageBuy`: This callback is invoked when a DCA (Dollar-Cost Averaging) entry is accepted. It includes the signal ID associated with the average buy. * `onSignalNotify`: Triggered when a notification is sent regarding a signal, providing the signal’s ID and any associated data. If you don’t need a specific callback, you can simply omit it. If a callback encounters an error, it will be logged but won't halt the overall process. ## Interface IMCPAverageBuyCommand This command lets you add a dollar-cost averaging (DCA) buy order to an existing, active trading position. It's used within the backtest-kit framework to automatically place these orders. The `symbol` property specifies which trading pair – like BTCUSDT – the order applies to. The `mcpName` identifies the specific trading strategy or model that's issuing the command. Essentially, it tells the system *who* wants to make this buy order. ## Interface ILogger The `ILogger` interface defines how different parts of the backtest-kit framework communicate about what's happening. It’s a central place to record events and details. You can use it to keep track of just about anything—from when agents start and stop, to the results of policy checks, to errors that might occur when saving data. The logger provides several levels of logging: * `log`: For general important messages. * `debug`: For very detailed information used mostly during development. * `info`: For regular updates and successful operations. * `warn`: For situations that aren't critical failures but should be investigated. These logging functions all take a `topic` to describe the event and then any number of arguments to provide details about it. ## Interface ILogEntry Each log entry, representing a single event recorded during a backtest, has a unique identifier. These entries are categorized by their log level – whether they’re standard logs, debug messages, informational updates, warnings, or messages specifically from agents. A timestamp indicates when the log was generated, and another timestamp is derived from the backtest context, which makes it easier for users to understand the timing of events. Optionally, you can associate context details with each log, like the method being executed (methodContext) or broader execution details (executionContext). The topic field clarifies what the log entry is about, often corresponding to the method or function that generated it. Finally, any extra arguments passed during the logging process are included as a list, allowing for more detailed information to be captured. ## Interface ILog The `ILog` interface gives you a way to track and review all the logging events that happen during your backtesting or trading simulations. It builds on the standard logging system and adds the ability to see a complete history of what's been logged. You can use the `getList` method to retrieve every log entry, which is helpful for debugging, analyzing performance, or just understanding exactly what happened during a trade. Essentially, it allows you to review the full log of events and their severity levels, combined with any agent-related information. ## Interface ILauncherPaperArgs This interface defines the settings for running the backtest system in a paper trading mode. It essentially instructs the system to simulate live trading conditions. The `paper` property, always set to `true`, signals that the system should execute the full live pipeline without actually submitting orders to a real exchange. This allows you to observe how your strategies would perform in a realistic environment without risking capital. ## Interface ILauncherLiveArgs This interface defines the arguments needed to launch the live trading pipeline. It's essentially a flag that tells the system to execute trades in a real-time environment. The `live` property, set to `true`, signifies that the backtest should proceed with actual trading operations, rather than just simulating them. It's designed to ensure type safety when choosing between backtesting and live trading modes. ## Interface ILauncherCallbacks The `ILauncherCallbacks` interface lets you hook into the lifecycle of a launcher. Think of it as a way to be notified about key moments in the launcher's process. You don’t have to provide all the callbacks; if you don’t need a specific one, just leave it out, and it won’t be triggered. Specifically, `onWaitForInit` gets called just before the launcher pauses, waiting for things to be ready. This is a good opportunity to load additional configuration or register components that might not be immediately available, allowing the launcher to wait without blocking on those slower tasks. ## Interface ILauncherBacktestArgs The `ILauncherBacktestArgs` interface defines the settings for running a backtest across multiple symbols. It essentially tells the backtest system how to execute and what timeframe to use. You can specify whether you want to initiate a full backtest by setting `backtest` to `true`. The `frameName` property lets you define the timeframe for the backtest; if you have multiple timeframes available, you need to explicitly tell the system which one to use. Otherwise, it will default to the first registered timeframe. Finally, you can choose to pre-populate the 1-minute candle cache before the backtest starts, which is helpful for quicker results, with `cache` defaulting to `true`. ## Interface ILauncherArgs ILauncherArgs defines the core information needed to kick off a backtest or live trading run. Think of it as a set of instructions for the system. It specifies which symbols (like BTCUSDT) the system will trade. You can optionally tell it which specific strategy and exchange to use. If you have only one of each registered, the system will pick them automatically. Finally, you can provide callbacks to hook into certain events happening during the run, like when the run starts or ends, but these are not required. The `launcherName` uniquely identifies the launcher itself, linking it to its configuration in the schema registry. ## Interface IHeatmapRow This interface represents a row of data within a portfolio heatmap, providing a comprehensive snapshot of a single trading symbol's performance. It bundles together a wealth of metrics to give you a clear picture of how a trading strategy is performing. You’ll find key indicators like total profit/loss, Sharpe Ratio (measuring risk-adjusted return), and maximum drawdown (the biggest loss from peak to trough). It also breaks down the performance with details like the number of winning and losing trades, win rate, and average profit/loss per trade. Beyond the basics, it offers deeper insights with metrics like expectancy (the average profit you’d make if you executed the strategy many times), duration of trades, and various ratios to assess risk and reward. You can also see how frequently prices are moving up versus down, and how strong those trends are. Finally, it includes a trend classification – whether the market is generally bullish, bearish, sideways, or neutral – along with a measure of its strength and confidence. This gives a good overview of the trading conditions. ## Interface IGetCandlesFilledParams This interface defines the parameters needed to request historical candlestick data. To get candles, you'll need to specify the trading symbol, the time interval (like 1 minute, 1 hour, or 1 day), and the starting date you want data from. You can also set a limit to control how many candles are returned in a single request, useful for managing large datasets. Think of it as building blocks to fetch the past price action for a particular asset. ## Interface IFrameSchema The `IFrameSchema` helps you define the boundaries and structure of your backtesting periods. Think of it as setting up the stage for your trading simulation – you specify the start and end dates, and how frequently data points (like prices) will be generated. Each frame gets a unique name to identify it, and you can add notes to explain its purpose. You can also customize the interval (e.g., 1 minute, 1 hour) at which data is generated, and even include lifecycle callbacks to trigger specific actions during the backtest process. It includes details like: * **frameName:** A unique name to identify your frame. * **note:** An optional description to explain what this frame represents. * **interval:** How often data will be generated within the frame (defaults to 1 minute). * **startDate:** The first date your backtest will cover. * **endDate:** The last date your backtest will cover. * **callbacks:** Functions you can use to react to events happening within the frame. ## Interface IFrameParams The `IFramesParams` object is what you pass when you create a frame within the backtest-kit framework. Think of a frame as a self-contained unit of work during your backtest. It bundles together things like a logger to help you keep track of what's going on, and a unique identifier called an interval that clearly labels this particular frame. This interval is like a name tag for your frame, making it easier to manage and understand its purpose in the larger backtest process. ## Interface IFrameCallbacks The `IFrameCallbacks` interface lets you hook into key moments in how your backtest framework handles time periods for trading. Specifically, you can register a function to be run when a new set of timeframes is created. This is a great opportunity to check that the timeframes look right or to record information about them for later analysis. The function receives the generated timeframes, the start and end dates of the backtest, and the interval used, allowing for detailed inspection and potential adjustments. ## Interface IFrame The `IFrames` interface is a key part of how backtest-kit manages the timing of your trading simulations. Think of it as the system's way of knowing when each piece of data should be used. Specifically, the `getTimeframe` function is what generates the list of dates and times your backtest will run through. You give it a symbol (like "AAPL") and a timeframe name (like "daily"), and it returns an array of timestamps, spaced according to your defined interval. These timestamps drive the backtest process, ensuring data is processed in the correct order. ## Interface IExecutionContext The `IExecutionContext` provides the necessary information for your trading strategies and exchange interactions to run correctly. Think of it as a shared container of data that’s passed around to give your code a sense of time and context. It includes the symbol you're trading, like "BTCUSDT," the current timestamp of the operation, and whether the code is running in a backtesting environment or in live trading. This context is automatically supplied, so you don't need to explicitly manage it; it’s readily available when you need it for actions like fetching historical data or processing ticks. ## Interface IExchangeSchema This schema defines how backtest-kit interacts with a specific cryptocurrency exchange. Think of it as a blueprint for connecting to a data source and understanding its quirks. It tells backtest-kit where to get historical price data (candles), how to format trade quantities and prices to match the exchange’s rules, and potentially how to retrieve order book information or aggregated trades. Each exchange needs its own instance of this schema, outlining its unique features and data formats. You can also add notes to describe exchange specific details. The schema also allows you to specify callbacks for things like receiving candle data as it arrives. ## Interface IExchangeParams The `IExchangeParams` interface defines the essential configuration needed to connect to and interact with a cryptocurrency exchange within the backtest-kit framework. It’s a blueprint for how the framework understands your exchange's capabilities. To use this, you need to provide functions for retrieving historical candle data, formatting order quantities and prices to match the exchange's rules, fetching order books, and retrieving aggregated trades. These functions let the backtest-kit simulate realistic trading scenarios by interacting with your exchange’s data. Also included are mechanisms for logging and managing the context of the backtest execution, helping to track and understand what's happening during the testing process. ## Interface IExchangeCallbacks If you're building a custom exchange integration, you can define what happens when candle (OHLCV) data arrives. The `onCandleData` callback lets you react to this incoming data, handling things like storing the new candles or triggering other actions based on the symbol, time interval, and the actual candle data received. You'll receive a list of candles fetched, and you can process them synchronously or asynchronously using `Promise`. ## Interface IExchange The `IExchange` interface defines how your backtesting framework interacts with an exchange to get historical and future market data. It provides functions to retrieve candle data – both looking back in time and into the future for backtesting purposes – and to format order quantities and prices to match the exchange's specific requirements. You can use it to calculate the average price (VWAP) using the most recent trade data, retrieve the closing price for a given time interval, access the order book, and fetch aggregated trades. The `getRawCandles` method gives you extra flexibility in how you retrieve historical candle data, allowing you to specify start and end dates or a limit, and automatically calculating other necessary parameters. It's designed to ensure the backtest doesn't look into the future and avoids any issues related to look-ahead bias. ## Interface IEntity This interface serves as the foundation for all objects that are saved and retrieved from storage within the backtest-kit framework. Think of it as the common ancestor for all persistent data – whether it's trade records, account details, or other important information. Any class implementing this interface promises to have a consistent structure for storage and retrieval purposes. ## Interface IDumpInstance The `IDumpInstance` interface defines how different parts of the backtest-kit framework can store information about what's happening during a simulation. Think of it as a set of tools for saving snapshots of key events and data. Each instance is tied to a specific signal and storage location, meaning it's responsible for saving data related to that particular signal. You can use these tools to capture various types of data: * Full conversation histories between agents. * Simple key-value records. * Tables of data, automatically figuring out the column headers. * Raw text or markdown output. * Error messages. * JSON data, even if it's complex and nested. * Status updates from the Model Context Protocol (MCP). Finally, when you're done, the `dispose` method allows you to clean up any resources used by the dump instance. ## Interface IDumpContext This `IDumpContext` object provides the necessary information to identify and categorize data dumps. Think of it as a label that attaches to each piece of data being saved. It contains details like a unique signal identifier, a bucket name to group related data, and a unique ID for the dump itself. There's also a descriptive label to help understand the data, and a flag to indicate whether the data originates from a backtest or a live trading environment. This context helps organize and find dumps later on, especially when searching through large datasets. ## Interface IDictionaryInstance This interface defines a specialized dictionary designed for use within trading strategies, particularly in backtesting scenarios. Think of it as a way to store and retrieve small pieces of information – like annotations from an AI model or flags indicating specific conditions – that are tied to a particular signal and its time. Crucially, this dictionary protects against looking into the future: you can only access data that was available at the time you're evaluating it. If a piece of data wasn't known yet, you won't see it. You can initialize it, read values, write new values or update existing ones, and check if a key exists. It also allows for deletion of individual entries or a complete clear of the dictionary. Furthermore, you can retrieve lists of keys, values, entries (key-value pairs), or count the number of available entries. Finally, when you're finished with the dictionary, you can dispose of it to release any resources it's using. ## Interface ICommitRowBase This interface defines the basic structure for events that represent commitments, like orders or trades, that are queued up to be processed later. Think of it as a foundational template for tracking actions that need to happen within the trading system. Each commitment includes information about the trading pair, identified by its symbol, and a flag indicating if the operation is part of a backtesting scenario. It ensures that these events are handled correctly and in the right order, even if they initially occur outside the main execution flow. ## Interface ICheckCandlesParams This interface defines the information needed to check if we have the necessary historical candle data already stored. Think of it as a way to quickly verify if your backtesting data is complete for a specific trading pair, exchange, and timeframe. You'll specify the symbol like "BTCUSDT," the exchange name, the candle interval (like 1-minute or 4-hour candles), and a date range to cover. This helps avoid unnecessary file scanning and speeds up the process of confirming your data's availability. ## Interface ICandleData This interface describes a single candlestick, which is a standard way to represent price data over a specific time interval. Each candlestick includes the timestamp of when it started, the opening price, the highest and lowest prices reached during that time, the closing price, and the total trading volume. You'll find this data structure essential when working with VWAP calculations and when performing backtests of trading strategies. It's the basic building block for historical price information. ## Interface ICandle This interface describes a single candlestick, a common way to represent price data over a specific time period. Each candlestick contains key information: the time it represents (timestamp), the price at which it opened (open), the highest price reached (high), the lowest price reached (low), the price at which it closed (close), and the volume of trading during that time. Think of it as a snapshot of market activity for a given interval. It’s a foundational structure for analyzing price movements and building trading strategies. ## Interface ICacheCandlesParams The `ICacheCandlesParams` object helps manage how your backtesting framework handles cached historical data. It lets you define specific settings for validation and pre-warming the cache, and crucially, includes callback functions you can use to respond to different stages of this process. Think of it as a way to customize what happens before validation and warm-up begin, allowing you to log events, perform checks, or adjust configurations as needed. You can specify functions that will be called right before the validation check begins, and again before the warm-up process starts if validation fails. ## Interface IBrokerOrderVerdictTransient This object represents a temporary setback encountered while trying to place or manage an order. It’s used internally by the backtest-kit framework to handle situations like brief network issues or temporary problems on an exchange. Think of it as a signal that something went wrong, but it's not necessarily a permanent problem. The system will automatically attempt to retry the order a limited number of times because it assumes the problem is temporary. It contains details about the specific error that occurred, though that detail might not always be clear. If a more specific error like an order rejection or deletion occurs, the framework will handle it differently, but this transient verdict handles the cases where the cause is uncertain. ## Interface IBrokerOrderVerdictRejected When an order can't be filled due to a business-level issue, this tells you why and provides details about the error. This isn't something you create; instead, the system uses it to communicate a permanent rejection. If an order is rejected, it means there's a problem that prevents it from being filled, and retrying won't help. For open orders, the system simply drops them; for closing orders, the system immediately closes the order. The `error` property contains the specific reason for the rejection, so you can understand what went wrong. ## Interface IBrokerOrderVerdictDeleted This object signals that an order has been removed – essentially, the system knows the order doesn't exist anymore. It's used when an order check or synchronization fails because the order was already deleted, like if a user canceled it directly on the exchange. Crucially, your adapters and listeners don't create this object directly; they just let the backtest-kit know about the deletion through error handling. The framework then packages this information into the `IBrokerOrderVerdictDeleted` object. The `reason` property will always be "deleted" in this case, and it carries the original `OrderDeletedError` that triggered the removal. ## Interface IBrokerOrderVerdictConfirmed This interface represents a decision made about an order, either allowing it to proceed or confirming its status. Think of it as a signal from the trading system saying "yes, this order is good to go" or "this order is still valid." It's not something you build directly; instead, it's a message passed along within the framework to indicate the outcome of a check or gate. The `reason` property is simple: it just tells you that the order was confirmed, meaning the system approves of the order's current state. ## Interface IBrokerOrderVerdictBase The `IBrokerOrderVerdictBase` acts as a foundational building block when your trading strategy interacts with the broker. It's used to signal the outcome of a request to the broker, whether that’s confirming an order can proceed or verifying its details. This base type ensures consistency in how the framework handles these decisions, focusing on the 'why' behind the verdict – the reason for approval or rejection – rather than the verdict itself. The `__type__` property is a special identifier that helps the framework understand the specific type of verdict being returned. ## Interface IBroker This interface, `IBroker`, is how the backtest-kit framework connects to live trading platforms like exchanges or brokers. It's essentially a translator between the framework's internal logic and the actual trading environment. The `waitForInit` method is crucial for initial setup – think connecting to the exchange, loading credentials, and most importantly, cleaning up any old, lingering orders or positions that might have been left over from previous sessions. This prevents trading against potentially mismatched data. `onOrderCloseCommit` handles closing trades (take-profit, stop-loss, or manual close). It's a critical gatekeeper – you place the real closing order here and handle potential errors. If an error happens during closing, the framework will retry the close, but it can force-close if retries fail. Similarly, `onOrderOpenCommit` manages opening new positions. This is the gate for placing real orders, and errors are handled with retries. The `clientOrderId` needs to be carefully managed to prevent duplicate orders. `onOrderActiveCheck` regularly polls the exchange to confirm a position's status. Errors here are tolerated with retries, but repeated failures can lead to forced position closure. `onOrderScheduleCheck` does the same for pending, scheduled orders. `onSignalActivePing` and `onSignalSchedulePing` are purely informational hooks; they let you react to real-time exchange data and adjust your strategy accordingly. `onSignalIdlePing` provides a periodic pulse when nothing is actively happening - use it for housekeeping. The `onSignalScheduleOpen`, `onSignalPendingClose`, `onSignalPendingOpen`, and their counterparts (schedule/cancelled) are lifecycle hooks for signaling transitions - used for placing and clearing orders. Finally, the `onPartialProfitCommit`, `onPartialLossCommit`, `onTrailingStopCommit`, `onTrailingTakeCommit` and `onAverageBuyCommit` hooks are used for handling specific profit-taking and DCA strategies. ## Interface IBreakevenData This interface defines a simple data structure used to store whether a breakeven point has been achieved for a particular trading signal. It's designed to be easily saved and loaded, typically as a boolean value, making it compatible with JSON serialization. Think of it as a snapshot of the breakeven status – just a true or false indicating if the target has been hit. The data is used within the framework to track progress and can be retrieved later for analysis or restoration. ## Interface IBreakevenCommitRow This object represents a commitment related to breakeven calculations during a backtest. It signifies an action, specifically a "breakeven" event. The `currentPrice` field within this object tells you the price level at which the breakeven point was determined. Essentially, it's a record of a breakeven calculation occurring at a specific price. ## Interface IBreakeven The `IBreakeven` interface helps track when a trade's stop-loss order should be moved to the entry price, essentially breaking even on the trade. It's used by different components to manage this process. The `check` method is responsible for determining if the breakeven point has been reached. It verifies if breakeven hasn’t already been triggered, if the price has moved enough to cover transaction fees, and if it's safe to move the stop-loss. If everything lines up, it marks the trade as having reached breakeven, notifies interested listeners, and saves this status. The `clear` method resets the breakeven state when a signal is closed, whether it’s due to hitting a take-profit, stop-loss, or time expiry. This ensures that the breakeven tracking is cleaned up and memory is freed. ## Interface IBidData This interface defines the structure of a single bid or ask price point within an order book. It includes two key pieces of information: the `price` at which the order is available, and the `quantity` of orders currently present at that price. Both price and quantity are represented as strings. ## Interface IAverageBuyCommitRow This interface represents a single step in a queued average-buy (DCA) process. It tracks a purchase made as part of a larger averaging strategy. Each record includes the price at which the purchase was made (`currentPrice`), the total cost of that specific purchase in dollars (`cost`), and the cumulative number of purchases (`totalEntries`) that have been made up to that point. Essentially, it's a snapshot of a single averaging transaction. ## Interface IAggregatedTradeData IAggregatedTradeData holds information about a single trade that took place. Think of it as a record of one transaction, containing details like the price at which it happened, how much was traded, and precisely when it occurred. The `id` gives this record a unique identifier, while the `price` and `qty` properties tell you the value and volume of the trade. The `timestamp` tells you exactly when it occurred, and `isBuyerMaker` indicates whether the buyer was the one setting the price – this can be helpful for understanding the flow of trading. ## Interface IAgentLogger The `IAgentLogger` interface provides a way to log information specifically about what your AI agent is doing. Think of it as a separate channel for recording the agent's actions, like its reasoning process, any tools it uses, and the final results. This is distinct from general framework logging, which focuses on the health and stability of the backtest-kit itself. Keeping these separate ensures that user-provided logging implementations aren't affected by agent-specific logging, giving you more control over how you track your agent's behavior. You'll primarily use the `agent` method to send these agent-related log messages, providing a topic and any relevant details you want to record. ## Interface IActivityEntry An `IActivityEntry` represents a single instance of a trading activity, whether it's a backtest or a live trade. Think of it as a record keeping track of what's currently running. These entries are automatically created when an activity begins and removed when it finishes, whether successfully or with an error. They’re crucial for managing workloads and ensuring that multiple activities don't run at the same time, preventing conflicts. Each entry contains key information: the trading symbol (like "BTCUSDT"), details about the strategy and exchange being used (including the timeframe), and a flag indicating whether it’s a backtest or a live trade. ## Interface IActivateScheduledCommitRow This interface represents a task that's been added to a queue to activate a previously scheduled commitment. Essentially, it's a notification that something that was planned to happen in the future is now being triggered. The `action` property simply confirms this is an activation-related task. You’ll find the unique identifier of the signal being activated in the `signalId` property. If a user manually initiated the activation, the `activateId` will contain the ID associated with that action; otherwise, it will be omitted. ## Interface IActionStrategy The `IActionStrategy` interface allows your action handlers to peek at the current signal state before they take action. Think of it as a way to check if a signal is ready to be used. It lets you know if there's an active signal currently affecting a trade – like whether a breakeven, profit target, or loss stop is waiting. You can also use it to see if a signal is scheduled to appear in the future. Essentially, this interface provides a safe way to prevent actions from happening prematurely or unnecessarily when the signal isn't quite ready. It’s used by components like `ActionProxy` to avoid executing certain actions when no signal is present. ## Interface IActionSchema The `IActionSchema` lets you extend your trading strategies with custom functionality, like connecting to external services or adding logging. Think of it as a way to hook into the core strategy execution and react to events in a personalized way. You define these custom pieces, called "actions," using this schema to register them with the backtest kit. Each action has a unique name for identification and optionally, a note for documentation. The most important part is the `handler`, which determines how your action will function—it's essentially a blueprint for creating your custom logic. Finally, `callbacks` allow you to specify lifecycle methods that run at different points during the strategy's operation. These actions are created separately for each strategy and the timeframe it's running on, providing a highly tailored experience. You can add several of these actions to a single strategy to build complex integrations. ## Interface IActionParams The `IActionParams` object is what gets passed to your actions, essentially containing all the important information they need to function correctly. Think of it as a package of context. It includes a `logger` to help you track what your actions are doing and spot any issues. You’ll also find the `strategyName` and `frameName` to identify the specific strategy and timeframe the action belongs to. Crucially, it tells you whether you’re in a `backtest` or live trading environment. Finally, the `strategy` property provides access to the current market signals and any existing positions, giving your actions the information they need to make informed decisions. ## Interface IActionCallbacks This API provides a way to hook into different stages of a trading strategy’s lifecycle, giving you fine-grained control over what happens at various points. Think of it as a series of event listeners for your trading bot. You can set up initialization and cleanup routines with `onInit` and `onDispose` to manage resources like database connections or buffers. These run when the action handler is started and stopped, respectively. Several callbacks handle signal events. `onSignal`, `onSignalLive`, and `onSignalBacktest` are triggered when a strategy generates a signal, with the latter two specific to live trading and backtesting. You can use these to log events or monitor performance. Specialized callbacks exist for specific events like breakeven, partial profit/loss, scheduled events, and risk rejections. These provide data-rich notifications related to those specific conditions. For scheduled events, `onPingScheduled` lets you monitor a pending order, while `onScheduleEvent` alerts you to the creation or cancellation of scheduled signals. `onPendingEvent` provides insights into the opening and closing of pending positions. `onPingActive` monitors active positions and `onPingIdle` is triggered when nothing’s happening. `onOrderSync` and `onOrderCheck` are crucial for managing order flow and handling potential errors. `onOrderSync` allows you to influence order openings and closings, while `onOrderCheck` is designed to proactively verify order status, preventing unexpected shutdowns. These callbacks use exception-based logic, offering strong error handling capabilities. Essentially, these callbacks provide the building blocks to customize your trading system’s behavior in response to a wide range of events and conditions. ## Interface IAction This interface, `IAction`, is your central hub for integrating custom logic into the backtesting and live trading framework. Think of it as a set of event listeners – it provides methods that get triggered by various occurrences within the system. You can use these methods to connect your own systems, like a dashboard, logging system, or to manage your trading state using tools like Redux or Zustand. The framework will "call" these methods to notify you about different events. There's a method for nearly everything – from when a signal is generated (`signal`, `signalLive`, `signalBacktest`) to when profit or loss levels are triggered (`partialProfitAvailable`, `partialLossAvailable`) or even when a scheduled signal is about to activate (`pingScheduled`). You'll find specific methods dealing with order management too, like `orderSync` which lets you react to attempts to open or close positions via limit orders, and `orderCheck` which verifies pending orders still exist on the exchange. Finally, the `dispose` method ensures clean cleanup when your integration is no longer needed. Using these callbacks helps you react to what’s happening in your strategy execution. ## Interface HighestProfitStatisticsModel This model keeps track of all the times your trading strategy achieved the highest profit. It stores a complete list of these profitable events, sorted from the most recent to the oldest. You can also see the total number of times your strategy reached this peak profit level, giving you a sense of how frequently it happens. Essentially, it's a record of your best-performing moments. ## Interface HighestProfitEvent This data represents the single most profitable moment observed for a specific trade. It tells you exactly when that highest profit was achieved, what asset was being traded (the symbol), and which strategy was responsible. You'll find a unique identifier for the signal that triggered the trade, along with details on whether it was a long or short position. The record includes a breakdown of the position's overall profit and loss (PNL), along with the highest profit point reached and the largest drawdown experienced during the trade. You'll also see the price at which the peak profit occurred, the initial entry price, and the designated take profit and stop-loss prices. Finally, it indicates if this event happened during a simulated backtest. ## Interface HighestProfitContract The HighestProfitContract provides information when a trading strategy reaches a new peak profit level. It gives you details like the trading symbol involved (e.g., "BTC/USDT"), the price at that moment, and the exact time it happened. You’ll also get the strategy's name, the exchange used, and the timeframe (like "1m" or "5m"). Critically, it includes the signal data that triggered the trade, helping you understand the conditions leading to the profit. A key piece of information is whether this profit update comes from a backtest (historical data) or a live trading scenario. This contract lets you build custom actions based on these profit milestones, like setting trailing stops or taking partial profits. The 'when' property will represent either the virtual time during a backtest or the real-time clock when the event happens. ## Interface HeatmapStatisticsModel This data structure provides a comprehensive overview of your portfolio's performance across all the assets it holds. It aggregates key metrics to give you a holistic view of how your trading strategy is performing. You'll find details like the total number of assets in your portfolio, the overall profit and loss, and key risk-adjusted return measures such as the Sharpe and Sortino ratios. The structure also includes metrics related to peak profit, maximum drawdown, and average trade durations, allowing you to understand the risk profile of your portfolio. Beyond these standard measures, it also provides insights into win and loss streaks, durations of winning and losing trades, and more advanced ratios like the Calmar and Recovery Factor, offering a deeper understanding of your portfolio’s efficiency and resilience. Finally, it delivers annualized returns and expected yearly returns projections for a long-term perspective. ## Interface DoneContract This interface represents the information passed when a background process finishes, whether it's a backtest or a live trading session. It tells you which exchange and strategy were involved, and importantly, whether it was a backtest or a live execution. You’ll also get the trading symbol and a timestamp indicating when the process concluded. For backtests, this timestamp marks the end of the last candle analyzed; for live environments, it's based on the last tick processed. ## Interface CronHandle The `CronHandle` is like a ticket you get when you schedule a task using the cron functionality. Think of it as a way to keep track of your scheduled job. When you’re done with the job, or want to cancel it, you use this handle to tell the system to remove it – it's essentially the same as manually removing the task from the cron schedule. It gives you a simple way to manage your scheduled events. ## Interface CronEntry This describes how to schedule tasks within your backtesting framework. Each scheduled task, or "CronEntry," needs a unique name to identify it, and this name can't contain colons. You specify the time interval for the task to run, like every minute or every hour. If you skip the interval, the task will execute just once immediately. A whitelist of symbols controls how the task is distributed across different backtests. If the whitelist is empty, the task runs only once for all backtests at each interval. If you provide symbols, the task runs once for each symbol on the list at each interval. Finally, there’s a handler function that actually performs the task. The handler will run whenever the task's conditions are met, and if an error occurs, it will retry. ## Interface CriticalErrorNotification This notification signals a critical error that requires the trading process to stop immediately. It's a special kind of notification designed to ensure you're aware of severe problems. Each notification has a unique identifier (`id`) and a human-friendly explanation (`message`) to help you understand the issue. The `error` property provides detailed information about the error, including its stack trace and any related data. Importantly, the `backtest` flag will always be false because these errors originate from the live trading environment, not a simulated backtest. ## Interface ColumnModel This describes how to define a column when you're creating a table to display data. Think of it as setting up a blueprint for each column you want to show. You'll need to give each column a unique identifier, which is its `key`. A friendly `label` lets you choose what to show as the column header. The `format` function is where you tell the system how to turn your data into a readable string for that specific column – it handles the transformation. Finally, `isVisible` allows you to control whether a column is shown or hidden based on some condition, giving you flexible table customization. ## Interface ClosePendingCommitNotification This notification signals that a pending trade was closed before it fully activated. It provides a wealth of information about the trade, including a unique ID, the exact time of the closure, and whether it occurred during backtesting or live trading. You'll find details like the trading pair, the strategy and exchange involved, and a unique identifier for the signal itself. The notification breaks down the specifics of the trade, revealing the trade direction (long or short), the original and effective entry, take profit, and stop-loss prices, and the number of entries and partial closes. It also includes comprehensive performance data: total profit and loss (PNL), peak profit achieved, maximum drawdown, and related prices and percentages. You'll see the original entry price, the cost of the initial position, and various flags indicating settings like leverage and margin isolation. Timestamps pinpoint the signal's creation and activation. A field allows for a custom note to describe the reason for the closure. Finally, a creation timestamp for the notification itself is also present. ## Interface ClosePendingCommit This signal indicates that a previously opened position is now being closed. It provides details about the closing event, including a user-defined identifier for the reason behind the closure. You’ll also find comprehensive information about the position's performance, such as the total profit or loss (PNL) accumulated throughout its existence. The signal also reports the highest profit reached by the position and the largest loss experienced at any point during its lifecycle. This helps in understanding the risk and reward profile of the closed trade. ## Interface CancelScheduledCommitNotification This notification signals that a scheduled trade signal has been cancelled before it could be executed. It provides a wealth of information about the cancelled signal, allowing you to understand why it wasn't triggered and analyze its potential impact. The notification includes details like a unique ID, the timestamp of the cancellation, and whether it occurred during backtesting or live trading. You’ll find specifics about the trading pair, the strategy involved, and the exchange used. It breaks down the planned trade, detailing the intended position (long or short), the target entry price, and the planned take profit and stop-loss levels – both as originally set and as they would have adjusted with trailing. Furthermore, it provides a comprehensive view of the potential trade's performance, including PNL calculations, peak profit, maximum drawdown, and cost information. A user-provided note can offer additional context for the cancellation, and the creation timestamp gives a full timeline of the signal's lifecycle. This allows you to debug signal behavior or understand trade flow issues. ## Interface CancelScheduledCommit This interface represents a request to cancel a previously scheduled signal event. It's used when you need to retract a signal that was planned for future execution. The `action` property confirms that the intention is to cancel a scheduled event. You can provide a `cancelId` to help track why the cancellation happened, which is useful for debugging or user feedback. Along with the cancellation request, it also includes data about the position being closed, such as total profit and loss (`pnl`), the highest profit ever reached (`peakProfit`), and the largest loss experienced (`maxDrawdown`). This information gives context to the cancellation and helps assess the impact of the change. ## Interface BreakevenStatisticsModel This model gives you a breakdown of breakeven events that occurred during a backtest. Think of it as a record of when your trading strategy reached a point where it could have potentially broken even. It includes a list of all the individual breakeven events, each with its own specific information, and a count of just how many such events took place. You can use this to understand how frequently your strategy hits these critical milestones. ## Interface BreakevenEvent The BreakevenEvent provides a standardized record whenever a trading signal reaches its breakeven point. This event gathers key details about the trade, including the exact time it happened, the symbol being traded, the name of the strategy used, and the unique identifier of the signal. It also tracks critical pricing information like the current market price, the initial entry price, and both take profit and stop loss levels, along with their original values set when the signal was created. If a dollar-cost averaging (DCA) strategy was used, the event includes details about the number of entries and partial closes. Furthermore, it captures the profit and loss (PNL) status at the time of breakeven, a human-readable explanation of why the signal was triggered, timestamps for activation and signal creation, and an indicator of whether the trade occurred during a backtest or live trading session. This comprehensive data allows for detailed analysis and reporting of trading performance. ## Interface BreakevenContract This interface represents a breakeven event, which occurs when a trading signal's stop-loss is adjusted to the original entry price. It's a way to track when a strategy has reduced its risk by covering transaction costs and reaching a point where no further loss can occur. Each breakeven event is specific to a trading pair (symbol), a strategy, an exchange, and a timeframe. It also includes all the original data of the signal that triggered it, along with the current price at which breakeven was achieved. You'll find a flag indicating if the event is from a backtest (using historical data) or live trading. A timestamp and date are provided to indicate precisely when the event occurred, using either the candle time in backtests or the real-time clock during live trading. This information helps in building reports or responding to breakeven milestones. ## Interface BreakevenCommitNotification This notification signals that a breakeven point has been reached and a commitment action has been executed, like closing a position. It provides a wealth of information about the trade, including a unique identifier, the timestamp of the event, and whether it occurred during backtesting or live trading. You'll find details about the trading pair, the strategy involved, and the exchange where the trade happened. The notification also includes specifics about the trade itself: entry price, take profit levels, stop-loss levels, and the position direction (long or short). Detailed financial information is included, such as the cost of the trade, the applied leverage (multiplier), and potentially relevant margin settings. The notification also gives insights into performance metrics like peak profit, maximum drawdown, and profit/loss expressed as both percentages and in USD. Additional properties like `note` offer optional context, while `scheduledAt`, `pendingAt`, and `createdAt` track the signal’s lifecycle from creation to notification. This notification provides a comprehensive snapshot of a breakeven trade. ## Interface BreakevenCommit This interface represents an event triggered when a breakeven action is taken within a trading strategy. It signals that the strategy has adjusted a position to break even, protecting some initial capital. The event provides detailed information about the position at the time of this adjustment. You'll find the current market price, the overall profit and loss (pnl) of the trade, and details of the peak profit and maximum drawdown it experienced. It also includes key price points like the original entry price, the initial take profit and stop-loss levels, and how those levels have potentially changed due to trailing mechanisms. The trade direction (long or short) is specified along with timestamps for when the signal and position were initiated. Essentially, it's a snapshot of a position’s state when a breakeven was triggered, useful for analysis and understanding the strategy’s behavior. ## Interface BreakevenAvailableNotification This notification signals that your trading position's stop-loss can now be moved to your entry price, essentially allowing you to break even. It provides a wealth of details about the position, including its unique identifier, the timestamp of the event, whether it's from a backtest or live trading, and the trading pair involved. You'll find important information like the strategy name, exchange, signal ID, current price, and your initial entry price. The notification also includes information about take profit and stop loss levels, both original and adjusted. The notification details the cost of the initial position, leverage (multiplier), and margin type (isolated), alongside the number of entries and partial closes. It offers a comprehensive view of the position’s performance including P&L, peak profit, maximum drawdown, and associated prices. Finally, it includes optional notes and timestamps to give full context to the event. ## Interface BeforeStartContract This event signals the very beginning of a trading strategy's run, right before the actual trading simulation or live execution begins. Think of it as a "get ready" signal for your strategy. It's a crucial point to set things up, like initializing logs, resetting counters, or sending a notification that a new run has started. You're guaranteed this event will only happen once per run and will always be followed by a corresponding event marking the end of the run, even if something goes wrong during the process. Any errors that occur during your setup will be handled separately so they won’t interrupt the overall run. The information included provides details about the trading symbol, the strategy being used, the exchange providing data, the timeframe, and whether it's a backtest or live run. A current price for the symbol and a timestamp are also given for convenience. In backtest mode, the timestamp represents the intended start of the historical data; in live mode, it’s the current time. ## Interface BacktestStatisticsModel This model encapsulates all the key statistical data generated from a backtest, offering a comprehensive view of your trading strategy's performance. It organizes information into categories like total signals, win/loss metrics, and risk-adjusted return ratios. You'll find details on individual trade performance in the `signalList` array, and higher-level summaries like average P&L, standard deviation, and Sharpe Ratio, all of which help gauge profitability and risk. The framework also provides insights into trade durations, consecutive win/loss streaks, and market pressure – helping you understand not just *if* you're making money, but *how* and *why*. It includes metrics like expectancy and Calmar Ratio to evaluate overall trading efficiency. Finally, the trend analysis provides a broad market direction indicator based on price action. Many of these values will be null if the calculation couldn't be performed safely due to data issues. ## Interface AverageBuyCommitNotification This notification lets you know when a new averaging (DCA) order has been added to an existing position. It provides a wealth of information about that averaging step, including the price it was executed at, the total cost, and how it impacts the overall position. You’ll find details like the current price, the number of averaging entries made so far, and the strategy that generated the signal. The notification also includes comprehensive performance metrics for the entire position, such as peak profit, maximum drawdown, and overall profit/loss – both in percentage and dollar terms. It also shows the original entry price, and how the effective entry price has changed as more averaging orders are placed. Crucially, it helps track how the position has evolved over time with signals such as the schedule and pending timestamps. This provides a complete view of your DCA strategy's progress and performance. ## Interface AverageBuyCommit This event, called `AverageBuyCommit`, signals a new average-buy (often referred to as dollar-cost averaging or DCA) has been added to an existing position. It provides a snapshot of the position's status immediately after this averaging purchase. You’ll find details about the price at which the new buy occurred (`currentPrice`), and the overall cost of that specific averaging transaction (`cost`). The `effectivePriceOpen` property tells you the new, averaged entry price after this purchase. The event also contains comprehensive information about the position's performance, including unrealized profit and loss (`pnl`), the highest profit ever achieved (`peakProfit`), and the largest drawdown experienced (`maxDrawdown`). You can access information like the original entry price (`priceOpen`), the current take profit and stop loss levels (`priceTakeProfit`, `priceStopLoss`), and their original values before any trailing adjustments were applied. Finally, timestamps (`scheduledAt`, `pendingAt`) show when the signal was created and the position was activated. ## Interface AfterEndContract This interface signals the completion of a trading strategy run, providing essential information for cleanup and reporting. It’s designed to be triggered exactly once for each strategy execution, ensuring reliable teardown processes. Think of it as a notification that the strategy has finished, whether it ran successfully, encountered an error, or was stopped early. The `when` property, representing the event time, has different meanings depending on whether you're in backtest or live trading mode. In backtest mode, it reflects the time of the last candle processed, or the frame's start time if no candles were processed. In live mode, it's the current time rounded to the nearest minute. You’ll find key details like the trading symbol, the strategy's name, the exchange, and the timeframe used. A `backtest` flag indicates if the run was a simulation or a live trade. The `currentPrice` offers a quick reference to the average price observed during the run. The `timestamp` provides the same information as `when` but as a number, simplifying data serialization and logging. This lets you perform tasks like flushing data buffers, finalizing calculations, or notifying other systems about the run's completion, all with confidence that these actions happen reliably at the end of each run. ## Interface ActivePingContract This describes a special notification, called an "active ping," that your trading system sends out regularly while it's actively waiting for a trading signal to become a confirmed trade. Think of it as a heartbeat signal confirming the signal is still active and being watched. Each active ping contains a lot of useful information about the signal being monitored, including the trading pair (like BTCUSDT), the strategy name, the exchange involved, and the timeframe being considered. You'll get the full details of the pending signal itself, along with the current price of the asset. The `backtest` property tells you whether the ping is coming from a historical simulation (backtest) or from live trading. Importantly, the `when` timestamp represents either the candle timestamp during a backtest or the actual time during live trading. You can use these active ping notifications to create custom logic – for example, to adjust your strategy based on how the price moves, or to handle signals in a specific way. The system provides ways to listen for these pings – either continuously or just once – allowing you to react to the signal’s lifecycle. ## Interface ActivateScheduledCommitNotification This notification signals that a scheduled trading signal has been activated, meaning the trading plan is now in motion. It provides a wealth of detail about the trade, including when it was activated, the specific strategy and exchange involved, and the trade's parameters like position size, take profit, and stop loss levels. You’ll find information about the trade’s cost, leverage, and any partial closes that have occurred. The notification also contains extensive performance metrics, such as peak profit, maximum drawdown, and profit/loss percentages. You can see how the position has performed since its inception, including the entry and exit prices used for PNL calculations. Finally, timestamps indicate when the signal was originally created and when it transitioned into a pending state. A note field allows for a short, human-readable explanation for the trade’s activation. ## Interface ActivateScheduledCommit This data structure represents an event triggered when a scheduled signal is activated, marking the start of a trade. It provides a snapshot of the trade’s key details at the moment of activation. You'll find information like the activation reason identifier provided by the user, the current market price, and crucial performance metrics for the position like total profit and loss (PNL), peak profit, and maximum drawdown. It also outlines fundamental aspects of the trade, including its direction (long or short), entry price, take profit levels (both original and adjusted), stop-loss levels (original and adjusted), when the signal was initially created, and the time the position was actually activated. This comprehensive set of data gives a complete picture of the activated trade and its associated context.