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.

Position query functions are read-only utilities for inspecting the state of the currently open position without mutating it. They all operate within the current execution context (symbol, strategy, exchange, frame), automatically reading the correct backtest timestamp or live wall-clock time. Functions that depend on the current price — such as PNL queries — call getAveragePrice internally, so no explicit price argument is needed. All functions return null when no pending or scheduled signal exists for the given symbol.

​
Signal Access

​
getPendingSignal

Returns the currently active pending signal for the strategy, or null if no position is open. 
getPendingSignal(symbol: string): Promise<IPublicSignalRow | null>
​
symbol
string
required
Trading pair symbol (e.g., "BTCUSDT").
IPublicSignalRow extends ISignalRow with originalPriceStopLoss, originalPriceTakeProfit, originalPriceOpen, partialExecuted, totalEntries, totalPartials, and real-time pnl, peakProfit, maxDrawdown snapshots.

​
getScheduledSignal

Returns the currently waiting scheduled signal (limit entry order), or null. 
getScheduledSignal(symbol: string): Promise<IScheduledSignalRow>
​
symbol
string
required
Trading pair symbol.

​
hasNoPendingSignal

Returns true if no active pending signal exists. Inverse of an internal hasPendingSignal check. Use as a guard before opening a new position. 
hasNoPendingSignal(symbol: string): Promise<boolean>
​
symbol
string
required
Trading pair symbol.

​
hasNoScheduledSignal

Returns true if no scheduled signal is waiting. Use as a guard before scheduling a new limit entry. 
hasNoScheduledSignal(symbol: string): Promise<boolean>
​
symbol
string
required
Trading pair symbol.

​
Price & PNL

​
getPositionEffectivePrice

Returns the cost-weighted harmonic mean of all DCA entry prices. With no DCA entries, equals priceOpen. Returns null if no pending signal exists. 
getPositionEffectivePrice(symbol: string): Promise<number | null>
​
symbol
string
required
Trading pair symbol.
The effective price is recalculated after each partial close using costBasisAtClose snapshots, then blended with any entries added after the last partial. This is the price used in all internal PNL calculations.

​
getPositionPnlPercent

Returns the current unrealized PNL as a percentage. Accounts for partial closes, DCA entries, slippage, and fees. 
getPositionPnlPercent(symbol: string): Promise<number | null>
​
symbol
string
required
Trading pair symbol.

​
getPositionPnlCost

Returns the current unrealized PNL in dollars: pnlPercentage / 100 × totalInvestedCost. 
getPositionPnlCost(symbol: string): Promise<number | null>
​
symbol
string
required
Trading pair symbol.

​
getPositionInvestedCost

Returns the total invested cost basis in dollars — the sum of all _entry.cost values. 
getPositionInvestedCost(symbol: string): Promise<number | null>
​
symbol
string
required
Trading pair symbol.

​
getPositionInvestedCount

Returns the number of DCA entries. 1 = original entry only; increments by 1 with each successful commitAverageBuy. 
getPositionInvestedCount(symbol: string): Promise<number | null>
​
symbol
string
required
Trading pair symbol.

​
Timing

​
getPositionEstimateMinutes

Returns the minuteEstimatedTime set in the signal DTO — the maximum expected hold duration before time_expired. 
getPositionEstimateMinutes(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionCountdownMinutes

Returns the remaining minutes before time_expired, clamped to 0. Computes minuteEstimatedTime − elapsedMinutes. 
getPositionCountdownMinutes(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionActiveMinutes

Returns the number of minutes the position has been active since pendingAt. 
getPositionActiveMinutes(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionWaitingMinutes

Returns the number of minutes the scheduled signal has been waiting for activation (since scheduledAt). 
getPositionWaitingMinutes(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
Peak Profit & Max Drawdown

​
getPositionHighestProfitPrice

Returns the best price reached in the profit direction during this position’s life. For LONG: maximum VWAP seen above effective entry. For SHORT: minimum VWAP seen below effective entry. 
getPositionHighestProfitPrice(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestProfitTimestamp

Returns the timestamp (milliseconds) when the best profit price was recorded during this position’s life. 
getPositionHighestProfitTimestamp(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestPnlPercentage

Returns the PNL percentage at the moment the best profit price was recorded. 
getPositionHighestPnlPercentage(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestPnlCost

Returns the PNL cost (in quote currency) at the moment the best profit price was recorded during this position’s life. 
getPositionHighestPnlCost(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestProfitBreakeven

Returns whether breakeven was mathematically reachable at the highest profit price, using the same threshold formula as getBreakeven. Returns null if no pending signal exists. 
getPositionHighestProfitBreakeven(symbol: string): Promise<boolean>
​
symbol
string
required
Trading pair symbol.

​
getPositionDrawdownMinutes

Returns the number of minutes elapsed since the highest profit price was recorded — measuring how long the position has been pulling back from its peak. 
getPositionDrawdownMinutes(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestProfitMinutes

Alias for getPositionDrawdownMinutes. Returns the number of minutes elapsed since the last profit peak. 
getPositionHighestProfitMinutes(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionMaxDrawdownMinutes

Returns the number of minutes elapsed since the worst loss price was recorded — how long ago the deepest drawdown occurred. 
getPositionMaxDrawdownMinutes(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionMaxDrawdownPrice

Returns the price at the worst drawdown point. For LONG: minimum VWAP below effective entry. For SHORT: maximum VWAP above effective entry. 
getPositionMaxDrawdownPrice(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionMaxDrawdownTimestamp

Returns the timestamp (milliseconds) when the worst loss price was recorded during this position’s life. 
getPositionMaxDrawdownTimestamp(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionMaxDrawdownPnlPercentage

Returns the PNL percentage at the worst price seen during this position’s life (deepest drawdown from entry). 
getPositionMaxDrawdownPnlPercentage(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionMaxDrawdownPnlCost

Returns the PNL cost (in quote currency) at the worst price seen during this position’s life. 
getPositionMaxDrawdownPnlCost(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestProfitDistancePnlPercentage

Returns the distance in PNL percentage between the current price and the highest profit peak. Computed as max(0, peakPnlPercentage − currentPnlPercentage). 
getPositionHighestProfitDistancePnlPercentage(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestProfitDistancePnlCost

Returns the distance in PNL cost between the current price and the highest profit peak. Computed as max(0, peakPnlCost − currentPnlCost). 
getPositionHighestProfitDistancePnlCost(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestMaxDrawdownPnlPercentage

Returns the recovery distance in PNL percentage between the current price and the worst drawdown trough. Computed as max(0, currentPnlPercentage − fallPnlPercentage). 
getPositionHighestMaxDrawdownPnlPercentage(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getPositionHighestMaxDrawdownPnlCost

Returns the recovery distance in PNL cost between the current price and the worst drawdown trough. Computed as max(0, currentPnlCost − fallPnlCost). 
getPositionHighestMaxDrawdownPnlCost(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getMaxDrawdownDistancePnlPercentage

Returns the peak-to-trough PNL percentage distance between the position’s highest profit and deepest drawdown. Computed as max(0, peakPnlPercentage − fallPnlPercentage). 
getMaxDrawdownDistancePnlPercentage(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
getMaxDrawdownDistancePnlCost

Returns the peak-to-trough PNL cost distance between the position’s highest profit and deepest drawdown. Computed as max(0, peakPnlCost − fallPnlCost). 
getMaxDrawdownDistancePnlCost(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

​
DCA & Partial History

​
getPositionLevels

Returns the list of DCA entry prices for the current pending signal. The first element is always the original priceOpen; each subsequent element is a price added by commitAverageBuy. Returns null if no pending signal exists. 
getPositionLevels(symbol: string): Promise<number[] | null>
​
symbol
string
required
Trading pair symbol.

​
getPositionPartials

Returns the history of partial close events for the current pending signal. Each record includes type ("profit" or "loss"), percent, currentPrice, costBasisAtClose, entryCountAtClose, and timestamp. Returns null if no pending signal exists; returns an empty array if no partials have been executed. 
getPositionPartials(symbol: string): Promise<Array<{
  type: "profit" | "loss";
  percent: number;
  currentPrice: number;
  costBasisAtClose: number;
  entryCountAtClose: number;
  timestamp: number;
}> | null>
​
symbol
string
required
Trading pair symbol.

​
getPositionEntries

Returns the list of DCA entry records (price and cost) for the current pending signal. The first element is the initial open; each subsequent element is added by commitAverageBuy. Returns null if no pending signal exists. 
getPositionEntries(symbol: string): Promise<Array<{
  price: number;
  cost: number;
  timestamp: number;
}> | null>
​
symbol
string
required
Trading pair symbol.

​
Entry Overlap Guards

​
getPositionEntryOverlap

Returns true if currentPrice falls within the tolerance zone of any existing DCA entry level. Use this to prevent duplicate DCA entries at the same price area. 
getPositionEntryOverlap(
  symbol: string,
  currentPrice: number,
  ladder?: IPositionOverlapLadder
): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
currentPrice
number
required
Price to check against existing DCA levels.
​
ladder
IPositionOverlapLadder
Tolerance zone config with upperPercent and lowerPercent (0–100 format). Default: 1.5% both sides.
Returns false if no pending signal exists.

​
getPositionPartialOverlap

Returns true if currentPrice falls within the tolerance zone of any existing partial close price. Use this to prevent duplicate partial closes at the same price area. 
getPositionPartialOverlap(
  symbol: string,
  currentPrice: number,
  ladder?: IPositionOverlapLadder
): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
currentPrice
number
required
Price to check against existing partial close prices.
​
ladder
IPositionOverlapLadder
Tolerance zone config. Default: 1.5% both sides.
Returns false if no pending signal exists or no partials have been executed yet.

​
getBreakeven

Returns true if the current price has moved far enough in the profit direction to cover transaction costs. Uses the formula (CC_PERCENT_SLIPPAGE + CC_PERCENT_FEE) * 2. 
getBreakeven(symbol: string, currentPrice: number): Promise<boolean>
​
symbol
string
required
Trading pair symbol.
​
currentPrice
number
required
Current market price to check against the breakeven threshold.

​
Totals

​
getTotalPercentClosed

Returns the total percentage of the position already closed via partial closes (0–100). 0 means nothing has been closed; 100 means fully exited via partials. 
getTotalPercentClosed(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.
Correctly accounts for DCA entries added between partial closes.

​
getTotalCostClosed

Returns the cost basis in dollars currently held (not yet closed by partials). Equals totalInvestedCost when no partials have been executed; decreases with each partial close and increases with each commitAverageBuy. 
getTotalCostClosed(symbol: string): Promise<number>
​
symbol
string
required
Trading pair symbol.

Build docs developers (and LLMs) love

Get started for freeTalk to us