WHALE ENGINE
Documentation

SuperTrend

[[supertrend]] produces a volatility-adjusted trailing line from bands built around price with Average True Range (ATR). During an upward phase, the active band lies below price; during a downward phase, it lies above price. When the close crosses the active band, the line switches sides and the direction changes.

The main output is the value of that line. When direction_id is set, the block also exposes a direction series: -1 for an upward phase and 1 for a downward phase. length sets the ATR horizon, while factor controls how far the bands sit from price.

Block declaration

A strategy can contain multiple [[supertrend]] blocks. Each block outputs the SuperTrend line and, when direction_id is set, a direction series (1 = downtrend, -1 = uptrend). This block has no source key because it always uses high, low and close.

Examples

Minimal setup

This block uses length = 10 and factor = 3.0. It exposes both the line and the direction series.

[[supertrend]]
id           = "st"
direction_id = "st_dir"
# length     = 10
# factor     = 3.0

Custom fixed setup

This block uses custom length and factor values.

[[supertrend]]
id           = "st"
direction_id = "st_dir"
length       = 14
factor       = 2.5

Search for the optimal length

This block explores a range of values for length while keeping factor = 3.0.

[[supertrend]]
id           = "st"
length.start = 7
length.stop  = 21
# length     = 10
# factor     = 3.0

Search for the optimal factor

This block keeps length = 10 and explores a range of values for factor.

[[supertrend]]
id           = "st"
length       = 10
factor.start = 1.0
factor.stop  = 5.0
factor.step  = 0.5

Parameters

ParameterDescription
id
 String
 Required		Identifier of the SuperTrend line.
direction_id
 String
 Optional		Identifier of the direction (1 = downtrend, -1 = uptrend).
length
 Integer
 Optional		Window used for ATR calculation and band smoothing; must be >= 1 when provided.
Default value: 10.

Usage:
• Fixed: length = 10
• Grid search:
- length.start = min_value
- length.stop = max_value
- length.step = value (optional, default 1)
factor
 Decimal
 Optional		Multiplier applied to the ATR when computing bands, must be > 0.

Usage:
• Fixed: factor = 3.0
• Grid search:
- factor.start = min_value
- factor.stop = max_value
- factor.step = value (optional, default 1)

Default value: 3.0.
symbol
 String
 or Array
 Optional		Market symbol(s) from which this block reads its candles (high, low, close). If symbol is omitted, the block uses the primary symbol defined in [backtest]. For symbol format, arrays, and alignment rules, see Exchanges, Symbols and Timeframes.
timeframe
 String
 or Array
 Optional		Timeframe on which this indicator is computed.
If timeframe is omitted, the computation uses the grid’s main timeframe defined in [backtest].
For accepted formats and timeframe alignment rules, see Exchanges, Symbols and Timeframes.

Available variables

Use the identifiers below directly in your expressions. The SuperTrend block exposes the line and, when configured, the direction (1 = downtrend, -1 = uptrend), along with parameters (length, factor), input sources, symbol, and timeframe.

Assume the block is configured as:

[[supertrend]]
id           = "st"
direction_id = "st_dir"

Then:

VariableDescription
st or
st[0]
Decimal		Current SuperTrend value.
st[n]
Decimal		SuperTrend value from n candles ago.
st_dir or
st_dir[0]
Decimal		Current direction (1 = downtrend, -1 = uptrend).
st_dir[n]
Decimal		Direction from n candles ago.
st.length
Decimal		Length in use.
st.factor
Decimal		Factor applied.
st.high_src
st.low_src
st.close_src
st_dir.high_src
st_dir.low_src
st_dir.close_src
String		Names of the input sources used (high, low, and close) on each output.
st.symbol
st_dir.symbol
String		Market symbol used for each output.
st.timeframe
st_dir.timeframe
String		Timeframe used for each output.

Notes

  • Numeric variables support arithmetic, comparisons, and logical operators.
  • Text variables are strings intended for equality/inequality checks only.
Prev
Stochastic RSI (stoch_rsi)
Next
Variance