Skip to main content

Documentation Index

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

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

Position management in backtest-kit is split across three adapters, each capturing a different dimension of an open trade. The Risk adapter tracks the full set of active positions for an exchange-level risk controller. The Partial adapter records per-signal profit-taking levels. The Breakeven adapter records whether a signal has moved its stop to breakeven. All three accept a when: Date parameter on writes, which is stored alongside the payload to support look-ahead bias detection during backtesting.

​
The when Parameter

Every write method in these three adapters accepts a when: Date argument. This timestamp is stored in MongoDB alongside the payload and represents the bar time at which the write occurred. During backtesting, the framework uses this value to verify that a read at time T never retrieves data written at a time T' > T, preventing look-ahead bias.

​
Risk Adapter

The Risk adapter operates at the exchange level rather than the symbol level. A single (riskName, exchangeName) context tracks all positions managed by a named risk controller on a given exchange.

​
Constructor

class implements IPersistRiskInstance {
  constructor(
    readonly riskName: string,
    readonly exchangeName: string,
  ) {}
}
​
riskName
string
required
The name of the risk controller, e.g. "default-risk".
​
exchangeName
string
required
The exchange identifier, e.g. "binance".

​
readPositionData

Reads the stored position array for this risk context. The _when parameter is accepted for interface compatibility but is not used during reads. 
async readPositionData(_when: Date): Promise<RiskData> {
  const row = await ioc.riskDbService.findByContext(
    this.riskName, this.exchangeName,
  );
  return row ? row.positions : [];
}
​
_when
Date
required
The current bar time. Accepted for interface compatibility; not used in the read query.
Returns: RiskData — an array of position objects, or an empty array [] when no data exists.

​
writePositionData

Upserts the full position array for this context, storing when alongside the payload. 
async writePositionData(positions: RiskData, when: Date): Promise<void> {
  await ioc.riskDbService.upsert(
    this.riskName, this.exchangeName, positions, when,
  );
}
​
positions
RiskData
required
The complete array of current positions to persist.
​
when
Date
required
The bar time at which this write is occurring.

​
Partial Adapter

The Partial adapter records partial take-profit state per individual signal. Each signal is identified by a signalId, making the context key a four-tuple. The payload type PartialData is a record of level identifiers to fill states.

​
Constructor

class implements IPersistPartialInstance {
  constructor(
    readonly symbol: string,
    readonly strategyName: string,
    readonly exchangeName: string,
  ) {}
}
​
symbol
string
required
The trading pair symbol.
​
strategyName
string
required
The strategy that owns the signal.
​
exchangeName
string
required
The exchange on which the signal is active.

​
readPartialData

Fetches the partial fill state for a specific signal ID. Returns an empty object {} when no record exists. 
async readPartialData(signalId: string, _when: Date): Promise<PartialData> {
  const row = await ioc.partialDbService.findByContext(
    this.symbol, this.strategyName, this.exchangeName, signalId,
  );
  return row ? row.payload : {};
}
​
signalId
string
required
The unique ID of the signal whose partial state is being read.
​
_when
Date
required
Accepted for interface compatibility; not used in the read query.
Returns: PartialData — the stored partial fill record, or {} if absent.

​
writePartialData

Upserts the partial fill record for a specific signal. 
async writePartialData(data: PartialData, signalId: string, when: Date): Promise<void> {
  await ioc.partialDbService.upsert(
    this.symbol, this.strategyName, this.exchangeName, signalId, data, when,
  );
}
​
data
PartialData
required
The partial fill state to store.
​
signalId
string
required
The unique ID of the signal.
​
when
Date
required
The bar time at which this write is occurring.

​
Breakeven Adapter

The Breakeven adapter records whether a signal has had its stop moved to breakeven. It shares the same constructor shape as Partial and uses the same four-part context key.

​
Constructor

class implements IPersistBreakevenInstance {
  constructor(
    readonly symbol: string,
    readonly strategyName: string,
    readonly exchangeName: string,
  ) {}
}
​
symbol
string
required
The trading pair symbol.
​
strategyName
string
required
The strategy that owns the signal.
​
exchangeName
string
required
The exchange on which the signal is active.

​
readBreakevenData

Fetches the breakeven state for a specific signal. Returns an empty object {} when no record exists. 
async readBreakevenData(signalId: string, _when: Date): Promise<BreakevenData> {
  const row = await ioc.breakevenDbService.findByContext(
    this.symbol, this.strategyName, this.exchangeName, signalId,
  );
  return row ? row.payload : {};
}
​
signalId
string
required
The unique ID of the signal whose breakeven state is being read.
​
_when
Date
required
Accepted for interface compatibility; not used in the read query.
Returns: BreakevenData — the stored breakeven record, or {} if absent.

​
writeBreakevenData

Upserts the breakeven state for a specific signal. 
async writeBreakevenData(data: BreakevenData, signalId: string, when: Date): Promise<void> {
  await ioc.breakevenDbService.upsert(
    this.symbol, this.strategyName, this.exchangeName, signalId, data, when,
  );
}
​
data
BreakevenData
required
The breakeven state to store.
​
signalId
string
required
The unique ID of the signal.
​
when
Date
required
The bar time at which this write is occurring.

​
Collection Summary

AdapterCollectionContext KeyEmpty Default
Riskrisk-items(riskName, exchangeName)[]
Partialpartial-items(symbol, strategyName, exchangeName, signalId){}
Breakevenbreakeven-items(symbol, strategyName, exchangeName, signalId){}
Risk uses a two-part context key (riskName, exchangeName) — it operates at the exchange level, not the symbol level. Partial and Breakeven both extend to a four-part key by adding signalId, scoping each record to a single open trade.

Build docs developers (and LLMs) love

Get started for freeTalk to us