Helpers

Utility functions and constants that are already in scope in agent code, next to the indicators. Like everything in scope, never import or redeclare them. Signatures are generated from the engine source.

calculateFibonacciRetracements

calculateFibonacciRetracements(start: number, end: number): FibonacciLevels

Returns the retracement levels between two prices: { level0, level236, level382, level500, level618, level786, level1000 }, where level0 is start and level1000 is end.

down

down(candle: Candle): boolean

true when a candle closed below its open (open > close).

ensureSymbolSingleTrade

ensureSymbolSingleTrade(manager: V2Manager, symbol: string, position: Position): boolean

Closes every open trade on symbol in the opposite direction, and returns true when no trade in the requested direction is open (so a new one can be opened).

const symbol = 'BTC';
const hourly = manager.getIntervalData(symbol, 60);
const cross = new Crossover(new EMA(hourly.close, 20), new EMA(hourly.close, 50));

manager.onIntervalCandle(symbol, 60, () => {
  if (!cross.hasValue()) return;
  const signal = cross.getValue();
  if (signal === null) return;
  const side = signal === 'firstUp' ? 'buy' : 'sell';
  if (ensureSymbolSingleTrade(manager, symbol, side)) {
    manager.openTrade({ symbol, position: side, type: 'MARKET', positionSize: { type: 'proportion', proportion: 0.1 }, comment: `EMA20/EMA50 cross, going ${side}` });
  }
});

generateStoploss

generateStoploss(request: StoplossRequest | Stoploss): Stoploss

Turns a stop request ({ type, value, delta? }) into the stop object stored on a trade ({ type, initial, absolute, delta? }). The engine does this for you in openTrade; you rarely need it.

generateTakeprofit

generateTakeprofit(request: TakeprofitRequest): Takeprofit

Validates a take-profit request and returns it as stored on a trade. The engine does this for you in openTrade.

getStoploss

getStoploss(trade: StoplossTrade, key: StoplossKey = stoplossMainKey): number

The initial price of one of a trade's stops (key defaults to the main stoploss); 0 for a buy and twice the entry for a sell when the trade has no such stop.

getStoplossDistance

getStoplossDistance(trade: StoplossTrade, key: StoplossKey = stoplossMainKey): number

The same distance as a fraction of the entry price (0.05 for a stop 5% away).

getStoplossRisk

getStoplossRisk(trade: StoplossTrade, key: StoplossKey = stoplossMainKey): number

The distance between a trade's entry and its initial stop, in price units.

rebalance

rebalance(manager: V2Manager, target: Record<string, number>): void

Places market orders that bring each symbol to a target weight of the wallet's market value.

• Only symbols with a current price take part, and their weights are re-normalised to sum to 1: { SPY: 0.5 } invests the whole wallet in SPY, so this helper cannot hold cash.
• Sells run before buys. Orders are plain MARKET orders without inhibitAutoInvest, so on a paper wallet a buy larger than the free cash tops up invested capital, and quantities ignore futures contract sizes.
• For a budget-controlled rebalance, write the cycle yourself as described in Rebalancing to target weights.

up

up(candle: Candle): boolean

true when a candle closed above its open (open < close).

updateStoploss

updateStoploss(manager: V2Manager, trade: Trade, stoploss: Stoploss, value: number): void

Moves an existing stop of an open trade to a new absolute price.

• Pass the trade's own stop object (trade.stoploss, trade.stoploss2, …), after checking it is not undefined: the helper changes the object it receives, so a fresh object literal moves nothing (the validator refuses it: TS9018).
• The price is clamped to the market: a buy stop is never set above the current price, a sell stop never below. It does not ratchet by itself: compare with stop.absolute before calling if the stop must only tighten.
• Throws when the symbol has no current price. To give a trade a stop it does not have, set it in openTrade.

const symbol = 'ETH';
manager.onPreciseCandle(symbol, () => {});

manager.cron('*/5 * * * *', () => {
  const price = manager.getCurrentPrice(symbol);
  if (price === undefined) return;
  for (const trade of manager.getSymbolPendingTrades(symbol)) {
    const stop = trade.stoploss;
    if (trade.position !== 'buy' || stop === undefined) continue;
    const trailed = price * 0.95;
    if (trailed > stop.absolute) updateStoploss(manager, trade, stop, trailed); // only tighten
  }
});

Constants

• stoplossKeys: StoplossKey[]: The names of a trade's stop fields: stoploss, stoploss2, stoploss3, stoploss4. Useful to loop over every stop of a trade.
• stoplossMainKey: StoplossKey: The main stop field name, 'stoploss'.
• takeprofitKeys: TakeprofitKey[]: The names of a trade's take-profit fields: takeprofit to takeprofit4.

Types named in these signatures (Trade, Stoploss, StoplossKey, …) are in Types. StoplossTrade is any object with a trade's position, enterPrice and stop fields, such as a Trade.