Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/theonetrade/backtest-kit/llms.txt

Use this file to discover all available pages before exploring further.

Commit functions are the primary mechanism for dynamically managing an open position during its lifetime. Each function is context-aware: in backtest mode it applies mutations against the virtual timeline, while in live mode it routes through the registered Broker adapter before mutating internal state. If the adapter throws — for example because the exchange rejected an order — the state mutation is skipped and the framework retries automatically on the next tick. All commit functions return false gracefully when no open position exists, making them safe to call without pre-checking signal state.
Never call commit functions at the top level of a module or outside an execution context. They must be called from within getSignal, an onActivePing callback, an onPartialProfit / onPartialLoss handler, or any other event callback that runs inside the framework’s execution context.

​
commitAverageBuy

Add a new Dollar Cost Averaging (DCA) entry to the current open position. 
commitAverageBuy(symbol: string, cost?: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol (e.g., "BTCUSDT").
​
cost
number
Dollar amount for this DCA entry. Defaults to CC_POSITION_ENTRY_COST (default $100).
The call is silently rejected and returns false when the current price is not below the lowest previous entry price (anti-record not broken). Set CC_ENABLE_DCA_EVERYWHERE: true via setConfig to allow averaging at any price below priceOpen. The effective entry price is the cost-weighted harmonic mean of all accepted DCA entries.

​
commitPartialProfit

Close a percentage of the position while price moves toward take-profit. 
commitPartialProfit(symbol: string, percentToClose: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
percentToClose
number
required
Absolute percentage of position to close, 0–100.
Returns false if the price is not currently in the profit direction or if closing percentToClose would exceed 100% total closed.

​
commitPartialLoss

Close a percentage of the position while price moves toward stop-loss. 
commitPartialLoss(symbol: string, percentToClose: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
percentToClose
number
required
Absolute percentage of position to close, 0–100.
Returns false if the price is not currently in the loss direction or would over-close the position.

​
commitPartialProfitCost

Close a dollar amount of the position at profit. Convenience wrapper that converts a dollar value to a percent and calls commitPartialProfit. 
commitPartialProfitCost(symbol: string, dollarAmount: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
dollarAmount
number
required
Dollar value of position to close (e.g., 150 closes $150 worth).
Automatically fetches current price via getAveragePrice and invested cost via getPositionInvestedCost.

​
commitPartialLossCost

Close a dollar amount of the position at loss. Convenience wrapper that converts a dollar value to a percent and calls commitPartialLoss. 
commitPartialLossCost(symbol: string, dollarAmount: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
dollarAmount
number
required
Dollar value of position to close.

​
commitTrailingStop

Shift the stop-loss by a percentage of the original SL distance. 
commitTrailingStop(symbol: string, percentShift: number, currentPrice: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
percentShift
number
required
Percentage adjustment to the original SL distance. Negative values tighten (move SL closer to entry); positive values loosen. Range: -100 to 100, excluding 0.
​
currentPrice
number
required
Current market price used for price-intrusion validation. The new SL is rejected if currentPrice has already crossed it.
Always calculates from the original SL, not the current trailing SL, preventing error accumulation across repeated calls. Uses an absorption rule: subsequent calls only update the SL if the new position offers better protection (higher for LONG, lower for SHORT).

​
commitTrailingTake

Shift the take-profit by a percentage of the original TP distance. 
commitTrailingTake(symbol: string, percentShift: number, currentPrice: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
percentShift
number
required
Percentage adjustment to the original TP distance. Negative values bring TP closer to entry (more conservative); positive values push it further.
​
currentPrice
number
required
Current market price used for price-intrusion validation.
Absorption rule: subsequent calls update the TP only if the new value is more conservative (lower for LONG, higher for SHORT).

​
commitTrailingStopCost

Set the stop-loss to an absolute price level. Convenience wrapper that converts newStopLossPrice to a percentShift and calls commitTrailingStop. 
commitTrailingStopCost(symbol: string, newStopLossPrice: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
newStopLossPrice
number
required
Desired absolute stop-loss price.
Automatically fetches current price and the original SL from the open signal.

​
commitTrailingTakeCost

Set the take-profit to an absolute price level. Convenience wrapper that converts newTakeProfitPrice to a percentShift and calls commitTrailingTake. 
commitTrailingTakeCost(symbol: string, newTakeProfitPrice: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
newTakeProfitPrice
number
required
Desired absolute take-profit price.

​
commitBreakeven

Move the stop-loss to the effective entry price (breakeven), locking in a zero-loss exit. 
commitBreakeven(symbol: string): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
The call is silently rejected if the price has not moved far enough to cover transaction costs. The threshold is (CC_PERCENT_SLIPPAGE + CC_PERCENT_FEE) * 2 + CC_BREAKEVEN_THRESHOLD. Idempotent: safe to call repeatedly; the SL is moved only once per signal. Fetches the current price automatically via getAveragePrice.

​
commitClosePending

Force-close the current active pending signal at the current market price. 
commitClosePending(symbol: string, payload?: Partial<CommitPayload>): Promise<void>
​
symbol
string
required
Trading pair symbol.
​
payload
Partial<CommitPayload>
Optional commit payload. id — correlation identifier for the close operation; note — human-readable reason string.
Does not stop the strategy. After closing, the strategy will continue calling getSignal on the next tick and can open a new position.

​
commitCancelScheduled

Cancel a pending scheduled signal without waiting for price to reach priceOpen. 
commitCancelScheduled(symbol: string, payload?: Partial<CommitPayload>): Promise<void>
​
symbol
string
required
Trading pair symbol.
​
payload
Partial<CommitPayload>
Optional commit payload with id and note fields.
Does not affect any active pending signal. The strategy can schedule a new signal on the next tick.

​
commitActivateScheduled

Activate a scheduled signal early without waiting for price to reach priceOpen. 
commitActivateScheduled(symbol: string, payload?: Partial<CommitPayload>): Promise<void>
​
symbol
string
required
Trading pair symbol.
​
payload
Partial<CommitPayload>
Optional commit payload with id and note fields.
The actual activation occurs on the next tick when the strategy detects the activation flag.

​
commitSignalNotify

Broadcast a user-defined informational note for the current active pending signal without affecting position state. 
commitSignalNotify(symbol: string, payload?: Partial<SignalNotificationPayload>): Promise<void>
​
symbol
string
required
Trading pair symbol.
​
payload
Partial<SignalNotificationPayload>
Optional notification payload. notificationNote — human-readable message (falls back to signal.note if omitted); notificationId — optional correlation ID for external systems.
Emits a SignalInfoContract via signalNotifySubject. Useful for annotating strategy decisions, triggering external alerts, or logging mid-position events such as indicator crossings. Throws if called outside an execution context or when no pending signal exists.

​
stopStrategy

Stop a live strategy from generating new signals. The currently open position (if any) continues to monitor TP/SL until natural closure — the strategy is not force-closed. 
stopStrategy(symbol: string): Promise<void>
​
symbol
string
required
Trading pair symbol to stop signal generation for.
Sets an internal flag that prevents getSignal from being called on subsequent ticks. The strategy can be stopped gracefully in a SIGINT handler without abandoning open positions.

​
shutdown

Emit a framework-wide shutdown signal to all components listening to shutdownEmitter. Use in SIGINT / SIGTERM handlers for a clean process exit. 
shutdown(): void

process.on('SIGINT', () => {
  shutdown();
  process.exit(0);
});
All commit functions return false (or resolve without error) when no open position exists for the given symbol, making them safe graceful no-ops in edge cases. They never throw for missing signals — only for invalid argument values.

Build docs developers (and LLMs) love

Get started for freeTalk to us