Functions

Script Definition

Define an indicator's metadata and surface user-configurable inputs. Plus debugging and data-source helpers.

Overview

Functions for defining script metadata, input parameters, data sources, and output formatting — the foundations for creating well-structured, user-friendly kScript indicators.

CategoryDescription
Script MetadataDefine script properties including name, chart placement, axis configuration, and title customization for professional indicator presentation. Supports chart placement control, custom titles, and axis configuration.
User InputsCreate configurable parameters that users can adjust — numbers, sliders, colors, booleans, and constrained selections — for flexible indicators. Supports multiple input types, default values, and validation constraints.
Data ManagementAccess market data sources, manage data feeds, and use debugging tools for robust indicator development and troubleshooting. Supports OHLCV access, multi-source data, and debug output.
FunctionDescription
defineRegister the indicator
inputDeclare a user-configurable parameter
sourceOpen a data feed (OHLCV, orderbook, etc.)
printWrite a value to the script console
printTimeSeriesWrite a timeseries to the script console

define

define(title, position, showPriceAxis?, customTitle?, format?) — declares the indicator's display name, chart placement, and optional axis behavior.

ParameterTypeDescription
titlestringDisplay name of the indicator
position'onchart' | 'offchart''onchart' overlays on the price chart; 'offchart' opens its own panel below
showPriceAxisbooleanShow an independent Y-axis. When true, format controls axis-value formatting.
customTitlestringCustom title suffix appended after title (e.g. ($period) reads as RSI (14) once period resolves). Use variable interpolation like ($period) to show current settings.
format'price' | 'abbreviated' | 'percentage'Axis-value formatting style. 'price' (default) shows raw values, 'abbreviated' uses K/M/B notation, 'percentage' adds the % symbol. Only applies when showPriceAxis=true.

Returns: void.

define() examples
// Basic indicator definition — simple case
define("My Indicator", "offchart", true);

// Onchart overlay (draws on main price chart)
define("Moving Average", "onchart", false);

// Offchart with axis (separate panel below chart)
define("Momentum %", "offchart", true);

// With customTitle to show dynamic parameters
var period = input("period", "number", 14, "Period");
define("RSI", "offchart", true, " ($period)");
// Result: "RSI (14)" — displays parameter value in chart title

// Multiple parameters in customTitle
var fastPeriod = input("fast", "number", 12, "Fast Period");
var slowPeriod = input("slow", "number", 26, "Slow Period");
define("MACD", "offchart", true, " ($fastPeriod, $slowPeriod)");
// Result: "MACD (12, 26)"

// === FORMAT PARAMETER EXAMPLES ===

// Price format (default) — shows raw values without abbreviation
define("Price Indicator", "offchart", true, " ($period)", "price");
// Y-axis shows: 10000000, 5000000, etc.

// Abbreviated format — uses K/M/B notation for large numbers
define("Volume", "offchart", true, "", "abbreviated");
// Y-axis shows: 10M, 5M, 1.5K, etc.

// Percentage format — adds % symbol after values
define("RSI", "offchart", true, " ($period)", "percentage");
// Y-axis shows: 70%, 50%, 30%, etc.

input

input(name, type, defaultValue?, label, constraints?, options?, group?) — declares a user-configurable parameter.

ParameterTypeDescription
namestringIdentifier referenced in code
typestringOne of 'number', 'slider', 'boolean', 'color', 'color[]', 'string', 'text', 'select', 'multiSelect'
defaultValueanyInitial value
labelstringUser-friendly label shown in the settings panel
constraintsobjectValidation rules for 'number'/'slider': {min, max, step?}. step defines the increment value.
optionsstring[]Choices for 'select' and 'multiSelect' (required for those types)
groupstringGroup name to organize related inputs into sections in the settings panel

Returns: the current parameter value.

input() examples
// NUMBER INPUTS — for periods, thresholds, multipliers
var period = input("period", "number", 14, "RSI Period");

// NUMBER WITH CONSTRAINTS — min/max limits range, step controls increments
var smoothing      = input("smoothing",      "number", 3,  "Smoothing Factor",  {min: 1, max: 10});
var rsiPeriod      = input("rsi_period",     "number", 14, "RSI Period",        {min: 2, max: 100});
var threshold      = input("threshold",      "number", 70, "Overbought Level",  {min: 50, max: 100});
var numberWithStep = input("numberWithStep", "number", 14, "Number With Step",  {min: 1, max: 50, step: 1});

// SLIDER INPUTS — visual range selection with draggable handle
var integerSlider    = input("integerSlider",    "slider", 20,  "Integer Slider",    {min: 5,   max: 100, step: 5});
var decimalSlider    = input("decimalSlider",    "slider", 2.0, "Decimal Slider",    {min: 0.5, max: 5.0, step: 0.5});
var percentageSlider = input("percentageSlider", "slider", 70,  "Percentage",        {min: 0,   max: 100, step: 5});

// BOOLEAN INPUTS — on/off toggles and feature flags
var showSignals  = input("showSignals",  "boolean", true,  "Show Buy/Sell Signals");
var enableAlerts = input("enableAlerts", "boolean", false, "Enable Alerts");

// COLOR INPUTS — customize visual appearance
var lineColor    = input("lineColor", "color", "#2196f3", "Line Color");
var bullishColor = input("bullColor", "color", "#00ff00", "Bullish Color");

// COLOR ARRAY INPUTS — multiple color selections
var colorPalette = input("colors", "color[]", ["#00ff00", "#ff0000"], "Color Scheme");

// STRING INPUTS — free text input
var alertMessage = input("alertMessage", "string", "Signal detected!", "Alert Message");

// TEXT INPUTS — multi-line text (notes, descriptions)
var notes = input("notes", "text", "Add your notes here", "Strategy Notes");

// SELECT INPUTS — dropdown selections with predefined options
var plotType  = input("mode", "select", "line", "Plot Type", {options: ["line", "bar", "candle"]});
var timeframe = input("tf",   "select", "1h",   "Timeframe", {options: ["5m", "15m", "1h", "4h", "1d"]});

// MULTISELECT INPUTS — multi-select dropdowns (returns string[])
var indicators = input("indicators", "multiSelect", [],            "Select Indicators", {options: ["RSI", "MACD", "EMA", "SMA", "Bollinger Bands", "Stochastic"]});
var timeframes = input("timeframes", "multiSelect", ["1H", "4H"],  "Select Timeframes", {options: ["5M", "15M", "30M", "1H", "4H", "1D", "1W"]});

// GROUPED INPUTS — organize related inputs into sections via the group parameter
var rsiPeriod     = input("rsi_period", "number", 14, "RSI Period",       null, null, "RSI Settings");
var rsiOverbought = input("rsi_ob",     "number", 70, "Overbought Level", null, null, "RSI Settings");
var rsiOversold   = input("rsi_os",     "number", 30, "Oversold Level",   null, null, "RSI Settings");

var maPeriod = input("ma_period", "number", 20,    "MA Period", null,                          null, "Moving Average");
var maType   = input("ma_type",   "select", "SMA", "MA Type",   {options: ["SMA", "EMA"]},     null, "Moving Average");

var bullColor = input("bull_color", "color", "#00ff00", "Bullish Color", null, null, "Colors");
var bearColor = input("bear_color", "color", "#ff0000", "Bearish Color", null, null, "Colors");

source

source(src, symbol, exchange) — open a data feed. Returns a TimeSeries.

ParameterTypeDescription
srcDataSourceData-source identifier (e.g. "ohlcv", "orderbook", "liquidations", "funding_rate", etc.)
symbolstringSymbol — typically currentSymbol
exchangestringExchange — typically currentExchange

Returns: TimeSeries.

source() examples
// Load current chart data
timeseries ohlcvData = source("ohlcv", currentSymbol, currentExchange);

// Load specific symbol data
timeseries btcData = source("ohlcv", "BTCUSDT", "BINANCE");

// Load alternative data sources
timeseries liquidations = source("liquidations", currentSymbol, currentExchange);
timeseries funding      = source("funding_rate", currentSymbol, currentExchange);

// Cross-exchange arbitrage
timeseries binanceData  = source("ohlcv", "BTCUSDT", "BINANCE");
timeseries coinbaseData = source("ohlcv", "BTC-USD", "COINBASE");

See Data Sources for the full list of available feeds.

print

print(message) — write a value to the script console.

ParameterTypeDescription
messageanyValue to log

Returns: void.

print() examples
print("RSI value: " + rsiValue);
print("Debug info:", someVariable);

printTimeSeries

printTimeSeries(source, priceIndex?) — log a timeseries (or one of its columns) to the script console.

ParameterTypeDescription
sourceTimeSeriesThe timeseries to inspect
priceIndexnumberOptional column index — log only that column

Returns: void.

printTimeSeries() examples
timeseries ohlcvData = source("ohlcv", currentSymbol, currentExchange);
printTimeSeries(ohlcvData);    // full OHLCV
printTimeSeries(ohlcvData, 4); // close prices only

Best Practices

Naming Convention

Use descriptive names for scripts and inputs. Clear, consistent naming makes your indicators more professional and easier for end users to understand.

  • Match the script title to what the indicator actually shows (e.g. "RSI Divergence", not "My Script").
  • Keep input name identifiers short and lowercase (rsi_period); use label for the human-readable form ("RSI Period").
  • Use customTitle to surface the most important parameters in the chart title (e.g. " ($period)").
Chart Placement

Pick the position that matches the indicator's value range and reading style.

  • 'onchart' — overlays that share the price axis: moving averages, Bollinger Bands, VWAP, support/resistance.
  • 'offchart' — separate panels for indicators with their own scale: RSI, MACD, volume, funding rate.
  • Set showPriceAxis=true and pick the right format ('price', 'abbreviated', 'percentage') when the offchart values need their own axis labels.
Group Related Inputs
Use the group parameter to organize inputs in the settings panel. Strategies with multiple sub-components (e.g. RSI settings, MA settings, color settings) become much easier to configure when grouped.
Debug Before Shipping
Use print() and printTimeSeries() while developing — log key values, intermediate calculations, and edge cases — then remove or comment out the calls before publishing the indicator.