fintech-algorithms

Supertrend

Trace ATR Bands, Ratchets, and Direction Flips

Install and import

bash
npm install fintech-algorithms
ts
import { supertrend } from "fintech-algorithms/technical-indicators/trend-systems/supertrend";

Signature

supertrend(high, low, close, period, multiplier)

An ATR-scaled band around the median price that ratchets in the direction of the trend and only flips when close crosses it. The band never loosens while the trend holds.

Parameters

NameTypeNotes
highnumber[]Per-bar high prices, chronological.
lownumber[]Per-bar low prices, chronological.
closenumber[]Per-bar closing prices, chronological.
periodnumberATR lookback.
min: 1 · integer: true
multipliernumberNumber of ATRs the band sits away from the median price.
min: 0

Returns

Record<string, (number | null)[]> · length same-as-input

Parallel series: atr, upper_band, lower_band, supertrend and trend.

Warm-up

The first period positions are null. The band cannot be placed until ATR is defined.

Errors

  • When period < 1, is not an integer, or multiplier is negative — throws RangeError
  • When the input series are not all the same length — throws RangeError

Complexity: time O(n), space O(n).

Worked example

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input

high
[121.59, 122.253519, 122.988989, 123.733544, 124.428602, 125.029237]

Showing 6 of 180 elements.

low
[119.167, 119.311841, 119.836426, 120.513403, 121.303676, 122.141567]

Showing 6 of 180 elements.

close
[120.42, 120.967246, 121.618347, 122.333586, 123.062426, 123.75067]

Showing 6 of 180 elements.

period
10
multiplier
3

Call

supertrend(high, low, close, period, multiplier)

Returns

object with 9 fields: true_range, atr, basic_upper, basic_lower, final_upper, final_lower, supertrend, direction, …

{
  "true_range": [
    2.423000000000002,
    2.941677999999996,
    3.1525630000000007,
    3.220140999999998,
    3.124926000000002,
    2.88767
  ],
  "atr": [null, null, null, null, null, null],
  "basic_upper": [null, null, null, null, null, null],
  "basic_lower": [null, null, null, null, null, null],
  "final_upper": [null, null, null, null, null, null],
  "final_lower": [null, null, null, null, null, null],
  "supertrend": [null, null, null, null, null, null],
  "direction": [null, null, null, null, null, null],
  "reversal": [null, null, null, null, null, null]
}

Diagrams

Supertrend — canonical trace
Supertrend — failure boundary
Supertrend — mechanism map

Calculation flow

Supertrend calculation flow 
flowchart LR
    A["Validated finalized bar"] --> B["Causal window or recursive state"]
    B --> C["Explicit seed and boundary rule"]
    C --> D["Aligned Supertrend output"]
    D --> E["Diagnostics and audit evidence"]

How it works

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References