kScript v2 overview
A domain-specific scripting language (DSL) for building custom trading indicators that run entirely in the browser (and Web Workers).
kScript compiles to JavaScript, is optimized for per-bar execution, and provides immutable timeseries plus ergonomic plotting via keyword arguments (kwargs).
Introduction
kScript is inspired by Pine Script but tailored for performant, deterministic, and secure execution inside the charting runtime. The language emphasizes:
Per-bar execution
with a clear three-phase lifecycle (Init → Calculate → Plot)
Immutable, historical timeseries
objects with indexing (e.g., ts[1])
Ephemeral var values
that are recalculated each bar
Plot-first APIs
that accept kwargs for clarity and flexibility
All built-in functions support kwargs, and this documentation uses kwargs in every example.
(Some functions may also offer positional shorthand, but kwargs are the recommended style and are used throughout.)
Execution Model (v2 Per-Bar)
Every script runs through three phases:
Initialization (runs once)
define(...)— required (exactly one call)- User inputs via
input(...) - Data subscriptions via
source(...)/ or dedicated type functions likeohlcv(...) - Declare timeseries in global scope only
Calculation (runs once per bar)
- Indicator math (
rsi(...),ema(...), etc.) - Expressions and control-flow using
varvariables - No
timeseriesdeclarations here
Plotting (runs once per bar, after calculation)
- Render via
plotLine(...),plotCandle(...),plotBar(...),plotShape(...), …
Types & Variables
var — Ephemeral, per-bar
- Type inference:
vartypes are inferred from the assigned value. - Scope:
varcan be declared in any scope (global, insideif/for/while, or insidefunc). - Mutability:
varvalues are mutable within the current bar. - No history:
varcannot persist across bars. You cannot accessvar[1]or previous-bar values. - Plotting:
varstrings can be used to plot labels/text; numericvarcan be used as per-bar scalars (rebuilt each bar).
timeseries — Immutable, historical
- Immutable:
timeseriesvalues are immutable snapshots of historical data. - Historical access:
ts[0]is current bar;ts[1]is previous bar;ts[n]is n bars ago. - Global only:
timeseriesmay be declared only in global scope (not insideif/for/whileor withinfuncbodies). - Multi-field sources: Some
timeseriesexpose multiple fields per bar, e.g., OHLCV:.open,.high,.low,.close,.volume. - Indicators require timeseries: Functions like
rsi,ema,marequire atimeseriessource.
Functions & Declarations
Script definition
Exactly one define(...) is required per script.
title: string shown in the UIposition:"onchart"|"offchart"axis: whether to show price axis for the indicatorcustomTitle: custom title override
Inputs (unified input(...))
Use the unified input(...) API to collect user inputs. Bind the result to a var.
Implementations may support additional constraints (e.g., min, max, step, options) but are optional and UI-dependent.
User-defined functions (keyword: func)
Declare custom functions using the func keyword.
Constraints:
- You may accept
varand/ortimeseriesarguments. - You must not declare a
timeseriesinside afuncbody (timeseries are global-only).
DSL vs General-Purpose Languages
- Ephemeral locals:
vardoes not retain history across bars (novar[1]). - Immutable history: Use
timeseriesfor historical indexing and indicator inputs. - Global timeseries only: Cannot declare
timeseriesin control blocks or insidefunc. - Sandboxed: No arbitrary I/O, filesystem, or network from scripts.
- Deterministic & bounded: Runtime enforces a 500 ms evaluation budget (excluding data fetch).
- Plot-centric: APIs focus on timeseries analysis + plotting, not general-purpose computation.
Data Sources
Subscribe to datasets with source(...) or convenience aliases like ohlcv(...). All source functions return a timeseries.
Plotting APIs (kwargs in all examples)
The rendering context is injected by the runtime; do not pass ctx. Multiple plot calls are allowed in a single script.
plotLine(...)
Draw a line from a numeric timeseries or scalar.
plotBar(...)
Plot vertical bars (e.g., volumes, histograms).
plotCandle(...)
Render candlesticks from OHLC timeseries.
plotShape(...)
Plot shapes/markers using booleans and optional text. var strings can be plotted as labels (per-bar).
Standard Library (selected)
All functions accept kwargs. Indicators require a timeseries source.
Definition & Inputs
Data Sources
Indicators
Helpers
Debugging
Use the Data Table to inspect values of outputs and data series.
Quick Start
Example: RSI Off-Chart Grid
Demonstrates kwargs, per-bar flow, and a line plot with threshold cues.
Rules & Gotchas (Read Carefully)
define(...)
Exactly one define(...) is required; otherwise the script will not run.
var
- Types are inferred;
varis mutable and can be declared anywhere. vardoes not persist across bars (no historical access likevar[1]).varstrings can be plotted (labels/text).
timeseries
- Immutable, with historical indexing via
[n]. - Global-scope only — not allowed in loops, conditionals, or inside
func. - Indicator functions require a
timeseriesas source. - Multi-field sources (e.g. OHLCV) expose
.open/.high/.low/.close/.volume.
Data sources
via source(dataType=..., symbol=..., exchange=...) or aliases like ohlcv(symbol=..., exchange=...)
→ All source functions return a timeseries.
Plotting & kwargs
- Use kwargs; do not pass
ctx(injected at runtime). - You may call multiple plot functions in one script.
Performance
Execution must complete within ≤ 500 ms (excluding data fetch) or the script is suspended with an error.
Debugging
Use print(...), printTimeSeries(...), and the Data Table to inspect values at runtime.