---
name: hyperprop-script
description: >-
Write custom chart indicators for the Hyperprop trading terminal using
Hyperprop Script (JavaScript). Use when building, porting, or debugging a
Hyperprop indicator or script, when converting a TradingView Pine Script to
Hyperprop, or when the user mentions Hyperprop Script, the Hyperprop script
editor, or custom indicators on Hyperprop charts.
---
# Writing Hyperprop Script indicators
Hyperprop Script is **plain JavaScript**, not Pine. A script declares its
settings at the top level and defines one function, `compute`, that receives
the full bar series and returns everything to draw. There is no per-bar
execution model and no persistent state between runs — `compute` is a pure
function of `(bars, inputs)`.
Scripts are created in the web terminal: **Indicators → My scripts → Create
script**. Errors never break the chart; they render as a red inline message in
the pane. Scripts sync to the user's other devices (including mobile)
automatically.
## The contract
```js
// Top level: declare settings. The settings dialog is generated from these.
const length = input.int('Length', 14, { min: 1, max: 500 });
const color = input.color('Line color', '#f59e0b');
// Called on every data change with the FULL series.
function compute(bars, inputs, hp) {
// bars: Array<{ time: Date, o, h, l, c, v? }>
// inputs: resolved settings values (rarely needed — the declared consts
// above already hold live values)
// hp: TA helper bundle (see below)
return {
plots: [ /* required key, may be [] */ ],
boxes: [], labels: [], lines: [], markers: [], bg: [], // all optional
range: { min: 0, max: 100 }, // optional: fix a separate pane's scale
guides: [30, 70], // optional: dashed horizontal levels
decimals: 2, // optional: axis/legend precision
};
}
```
Pane type is chosen at save time: **overlay** (drawn over price, y = price)
or **separate** (own pane below price, y = the script's own value scale).
## Input declarations
All return the resolved live value. `opts` = `{ key?, min?, max?, step? }`.
Keys default to a slug of the label; pass `key` to keep saved settings stable
across label renames.
| Declaration | Returns |
|---|---|
| `input.int(label, default, opts?)` | integer |
| `input.float(label, default, opts?)` | number |
| `input.bool(label, default?)` | boolean |
| `input.color(label, default)` | color string (hex or `rgba()`) |
| `input.string(label, default?)` | string |
| `input.select(label, default, choices)` | string (`choices`: `string[]` or `{value,label}[]`) |
| `input.source(label?, default?)` | one of `open/high/low/close/hl2/hlc3/ohlc4` |
## TA helpers (`hp`)
All series helpers take and return `Array<number | null>` aligned to `bars`.
Nulls mark "no value yet" — always null-check before arithmetic.
| Helper | Notes |
|---|---|
| `hp.sma / ema / rma / stdev (values, length)` | moving averages / deviation |
| `hp.highest / lowest (values, length)` | rolling extremes |
| `hp.change(values, length = 1)` | difference vs N bars back |
| `hp.atr(bars, length)` | takes **bars**, not values |
| `hp.rsi(values, length)` | 0–100 |
| `hp.linreg(values, length)` | least-squares regression value (Pine `ta.linreg` offset 0) |
| `hp.cum(values)` | running sum |
| `hp.vwap(bars)` | day-anchored VWAP (resets on UTC date change) |
| `hp.pivothigh / pivotlow (values, left, right = left)` | pivot VALUE emitted **at the pivot bar itself** (`null` elsewhere). Unlike Pine, which reports it `right` bars later — a pivot at index `p` is only knowable from bar `p + right` onward; account for that in signal logic. |
| `hp.crossover / crossunder (a, b)` | returns `boolean[]`; `b` may be a series or a constant |
Anything else is ordinary JavaScript — write your own loops and math freely.
## Drawing primitives
X coordinates are **bar indices** into `bars`. Fractional values and indices
past the last bar are fine (the axis extrapolates), so zones and rays can
extend into the future. Y is a price (overlay) or the script's own value
(separate pane). Boxes and `bg` bands render **under** the series; lines,
markers, and labels render **on top**. Everything clips to the pane. Hard cap:
**2000 items per type** — return only what is currently visible/alive, never
the full history.
```js
boxes: [{ x1, y1, x2, y2, bg?, border?, borderWidth?, text?, textColor? }]
labels: [{ x, y, text, color?, textColor?, anchor?, size? }]
// anchor: 'up' (bubble above point) | 'down' | 'left' | 'right' | 'center'
lines: [{ x1, y1, x2, y2, color?, width?, style? }] // style: solid|dashed|dotted
markers: [{ x, y, shape?, color?, text?, textColor? }]
// y: number, or 'above'/'below' → anchors to the bar's high/low
// shape: triangle-up|triangle-down|circle|square|arrow-up|arrow-down
bg: [{ x1, x2, color }] // vertical band, full pane height
```
Use `rgba()` colors for translucent zone fills. Plots:
```js
plots: [{ title?, values, color?, width?, style?: 'line' | 'histogram', negativeColor? }]
```
## Hard limits — design around these
- **1000 ms execution budget** per `compute`, enforced with loop guards. A
script that exceeds it is circuit-broken until edited. Keep hot loops
O(bars); avoid O(bars²) rescans.
- **Synchronous only.** No `async`, no `fetch`, no timers — `compute` must
return its result directly.
- **Single symbol.** Scripts only receive the chart's own bars. No
cross-symbol or cross-timeframe data (Pine `request.security` cannot be
ported).
- **No main-series restyling.** Pine `plotcandle` / `barcolor` have no
equivalent.
- **No persistence.** Model "current state" by replaying the rules over the
series inside `compute` (see the signal recipe).
## Recipes
### Oscillator (separate pane)
```js
const length = input.int('Length', 14, { min: 2, max: 100 });
function compute(bars, inputs, hp) {
const rsi = hp.rsi(bars.map(b => b.c), length);
return {
plots: [{ title: 'RSI', values: rsi, color: '#ab47bc' }],
range: { min: 0, max: 100 },
guides: [30, 70],
};
}
```
### Zones / order blocks (overlay, boxes + markers)
The core pattern for supply/demand, FVG, and session-level indicators: build
each zone's lifecycle (created / mitigated), then emit boxes only for zones
still alive at the last bar.
```js
const lookback = input.int('Lookback (bars)', 10, { min: 3, max: 50 });
function compute(bars, inputs, hp) {
const highs = bars.map(b => b.h), lows = bars.map(b => b.l);
const ph = hp.pivothigh(highs, lookback), pl = hp.pivotlow(lows, lookback);
const boxes = [], last = bars.length - 1;
for (let p = 0; p < bars.length; p += 1) {
if (pl[p] == null && ph[p] == null) continue;
const bull = pl[p] != null;
const top = highs[p], bottom = lows[p];
let mitigated = null;
for (let j = p + lookback; j <= last; j += 1) {
if (bull ? lows[j] < bottom : highs[j] > top) { mitigated = j; break; }
}
if (mitigated != null) continue; // only zones still alive
boxes.push({
x1: p, y1: top, x2: last + 20, y2: bottom, // extends into the future
bg: bull ? 'rgba(0,200,83,0.18)' : 'rgba(211,47,47,0.18)',
border: bull ? '#00c853' : '#d32f2f',
text: bull ? 'demand' : 'supply',
});
}
return { plots: [], boxes };
}
```
### Signal engine (entry/SL/TP with history)
Pine keeps `var` state across bars; here, replay the state machine in one
sequential loop. One active signal at a time; finished signals become faded
markers.
```js
let active = null; const history = [];
for (let i = 1; i < bars.length; i += 1) {
if (active) {
const slHit = active.bull ? lows[i] <= active.sl : highs[i] >= active.sl;
const tpHit = active.bull ? highs[i] >= active.tp : lows[i] <= active.tp;
if (slHit || tpHit) { history.push(active); active = null; }
}
if (!active && /* entry condition at bar i */ false) {
const entry = closes[i], sl = lows[i] - 3, tp = entry + (entry - sl) * 2;
active = { bull: true, entry, sl, tp, bar: i };
}
}
// history → translucent markers; active → dashed entry line + SL/TP lines
// + labels anchored at active.bar and active.bar + 55.
```
### Session shading (bg bands)
`Intl.DateTimeFormat` is available for timezone math:
```js
const fmt = new Intl.DateTimeFormat('en-US',
{ timeZone: 'America/New_York', hour: 'numeric', minute: 'numeric', hour12: false });
const minutesNY = t => {
const p = fmt.formatToParts(t);
return (Number(p.find(x => x.type === 'hour').value) % 24) * 60
+ Number(p.find(x => x.type === 'minute').value);
};
// Walk bars, open a band when entering the window, close it when leaving:
// bg.push({ x1: openBar, x2: closeBar, color: 'rgba(230,81,0,0.09)' })
// Limit to recent history (e.g. last ~900 bars) to stay under the 2000 cap.
```
## Porting from Pine Script
| Pine | Hyperprop Script |
|---|---|
| `input.int(14, "Length")` | `input.int('Length', 14, { min, max })` |
| `ta.sma/ema/rma/stdev/atr/rsi/linreg` | `hp.` equivalents (note `hp.atr(bars, len)`) |
| `ta.pivothigh(high, l, r)` | `hp.pivothigh(highs, l, r)` — value at the **pivot bar**, not confirmation bar |
| `ta.crossover / crossunder` | `hp.crossover / crossunder` → `boolean[]` |
| `close[3]` (history operator) | `closes[i - 3]` inside your own loop |
| `var x = …` + per-bar mutation | sequential `for` loop over bars inside `compute` |
| `box.new / label.new / line.new` | push to `boxes` / `labels` / `lines` arrays |
| `plotshape` | push to `markers` |
| `bgcolor` / session boxes | push to `bg` |
| `fill(p1, p2)` | no fill — plot the two boundary lines, or per-segment boxes |
| `plotcandle` / `barcolor` | not supported |
| `request.security` | not supported (single symbol only) |
| `alertcondition` | not supported (price alerts are a separate terminal feature) |
| `xloc.bar_time` timestamps | bar indices (extrapolate past the last bar for "future" x) |
Pine's per-bar drawing mutation (create → move → delete) collapses into one
question: **what should be visible right now?** Compute final state once.
## Workflow
1. Write the script (top-level `input.*` declarations + `compute`).
2. In the terminal: **Indicators → My scripts → Create script**, paste, choose
**Overlay** or **Separate pane**, then **Save & add to chart**.
3. Compile or runtime errors appear inline in the pane in red — fix and
resave. A budget-exceeded script stays disabled until edited.
4. Settings changes in the UI re-run `compute` live; verify inputs by watching
the legend values update.
