---
title: Script Definition
description: 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.

| Category | Description |
| --- | --- |
| **Script Metadata** | Define 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 Inputs** | Create 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 Management** | Access 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. |

| Function | Description |
| --- | --- |
| [`define`](#define) | Register the indicator |
| [`input`](#input) | Declare a user-configurable parameter |
| [`source`](#source) | Open a data feed (OHLCV, orderbook, etc.) |
| [`print`](#print) | Write a value to the script console |
| [`printTimeSeries`](#printtimeseries) | Write 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.

| Parameter | Type | Description |
| --- | --- | --- |
| `title` | string | Display name of the indicator |
| `position` | `'onchart' \| 'offchart'` | `'onchart'` overlays on the price chart; `'offchart'` opens its own panel below |
| `showPriceAxis` | boolean | Show an independent Y-axis. When `true`, `format` controls axis-value formatting. |
| `customTitle` | string | Custom 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`.

```javascript title="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.

| Parameter | Type | Description |
| --- | --- | --- |
| `name` | string | Identifier referenced in code |
| `type` | string | One of `'number'`, `'slider'`, `'boolean'`, `'color'`, `'color[]'`, `'string'`, `'text'`, `'select'`, `'multiSelect'` |
| `defaultValue` | any | Initial value |
| `label` | string | User-friendly label shown in the settings panel |
| `constraints` | object | Validation rules for `'number'`/`'slider'`: `{min, max, step?}`. `step` defines the increment value. |
| `options` | string[] | Choices for `'select'` and `'multiSelect'` (required for those types) |
| `group` | string | Group name to organize related inputs into sections in the settings panel |

**Returns:** the current parameter value.

```javascript title="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.

| Parameter | Type | Description |
| --- | --- | --- |
| `src` | DataSource | Data-source identifier (e.g. `"ohlcv"`, `"orderbook"`, `"liquidations"`, `"funding_rate"`, etc.) |
| `symbol` | string | Symbol — typically `currentSymbol` |
| `exchange` | string | Exchange — typically `currentExchange` |

**Returns:** `TimeSeries`.

```javascript title="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](/kscript/core-concepts/data-sources) for the full list of available feeds.

## print

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

| Parameter | Type | Description |
| --- | --- | --- |
| `message` | any | Value to log |

**Returns:** `void`.

```javascript title="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.

| Parameter | Type | Description |
| --- | --- | --- |
| `source` | TimeSeries | The timeseries to inspect |
| `priceIndex` | number | Optional column index — log only that column |

**Returns:** `void`.

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

## Best Practices

<table data-view="cards"><tbody>
<tr><td>Naming Convention</td><td><p>Use descriptive names for scripts and inputs. Clear, consistent naming makes your indicators more professional and easier for end users to understand.</p><ul><li>Match the script <code>title</code> to what the indicator actually shows (e.g. <code>"RSI Divergence"</code>, not <code>"My Script"</code>).</li><li>Keep <code>input</code> <code>name</code> identifiers short and lowercase (<code>rsi_period</code>); use <code>label</code> for the human-readable form (<code>"RSI Period"</code>).</li><li>Use <code>customTitle</code> to surface the most important parameters in the chart title (e.g. <code>" ($period)"</code>).</li></ul></td><td></td></tr>
<tr><td>Chart Placement</td><td><p>Pick the <code>position</code> that matches the indicator's value range and reading style.</p><ul><li><strong><code>'onchart'</code></strong> — overlays that share the price axis: moving averages, Bollinger Bands, VWAP, support/resistance.</li><li><strong><code>'offchart'</code></strong> — separate panels for indicators with their own scale: RSI, MACD, volume, funding rate.</li><li>Set <code>showPriceAxis=true</code> and pick the right <code>format</code> (<code>'price'</code>, <code>'abbreviated'</code>, <code>'percentage'</code>) when the offchart values need their own axis labels.</li></ul></td><td></td></tr>
<tr><td>Group Related Inputs</td><td>Use the <code>group</code> 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.</td><td></td></tr>
<tr><td>Debug Before Shipping</td><td>Use <code>print()</code> and <code>printTimeSeries()</code> while developing — log key values, intermediate calculations, and edge cases — then remove or comment out the calls before publishing the indicator.</td><td></td></tr>
</tbody></table>