First Steps

Welcome. If you have never written a line of kScript, you are in exactly the right place. By the end of this short primer you will have a working indicator drawing on a live chart. Let's start from zero.

What is kScript?

kScript is a small language for building chart indicators on real market data. You write a few lines, hit run, and your code draws on the chart: a moving average, a momentum signal, a custom study of order flow. The engine feeds your script real candles, runs your math, and renders whatever you tell it to plot.

You don't need to set up a project, install anything, or manage a server. You write the script in the browser, and it runs against live and historical market data immediately.

Where you write it

Everything happens in the script editor on the chart. Open the editor, type your script, and click Apply to run it. Your indicator appears on (or below) the chart right away. Change a line, hit Apply again, and the chart updates. That tight loop is the whole workflow: write, apply, look at the chart, repeat.

The shape of every script

Before we write anything, here is the mental model. Almost every kScript has the same three moving parts:

1. 1

   A definition

   A define(...) call near the top. It gives your indicator a name and tells the engine where to draw it: on the price chart, or in its own panel below.

2. 2

   Some data

   A call to ohlcv(...) to load the chart's candles. This is your raw material: open, high, low, close, and volume for every bar.

3. 3

   A plot

   A plot* call (like plotLine) that draws something. No plot, nothing on the chart.

There is one more rule, and it is easy: every script starts with //@version=2 on the very first line. That marker tells the engine which version of the language you are writing. Forget it and the script won't run, so make it a habit: line 1 is always //@version=2.

Your first script

Here it is. This is the smallest useful kScript there is. It loads the chart's candles and draws the closing price as a blue line. Type it into the editor and click Apply.

//@version=2
define(title="Hello kScript", position="onchart", axis=false)

timeseries d = ohlcv(symbol=currentSymbol, exchange=currentExchange)
plotLine(value=d.close, colors=["#2563eb"], width=2, label=["Close"], desc=["the closing price of each candle"])

Five lines, and every one of the three parts is there. Let's walk through them.

• //@version=2 is the version marker. Always line 1.
• define(title="Hello kScript", position="onchart", axis=false) names your indicator "Hello kScript" and places it onchart, meaning it draws right on top of the price candles rather than in a separate panel. axis=false keeps it on the chart's own price axis instead of adding a new one.
• timeseries d = ohlcv(symbol=currentSymbol, exchange=currentExchange) loads the candles. timeseries is the type for data that has a value at every bar. We store the result in d. The currentSymbol and currentExchange values mean "whatever symbol and exchange this chart is currently showing," so your indicator follows the chart automatically.
• plotLine(value=d.close, ...) draws the line. d.close is the closing price of each candle, pulled from the data we just loaded. colors sets the line color, and width sets its thickness.

What you'll see

A blue line tracing the close of every candle, sitting right on the price chart. Because the close is already part of the candle, this line will hug the top of each bar. It is not a fancy indicator, but it proves the whole pipeline works: your code received real data and drew it. That is the foundation for everything else.

One small thing to notice

Look at the plotLine call again. It ends with label=["Close"]. Every plot needs a label: a short, unique name shown in the chart legend (and the name you pick when you set an alert on this output). It is an array because a single plot can draw more than one line at once (you will see that on the next page), one label per line. The desc=["..."] you can add next to it is an optional longer description. Get into the habit now: give every plot* call a clear, unique label=.

Next

Now let's turn this into something you would actually use. On the next page we build a real indicator step by step: a moving-average crossover signal.

Build Your First Indicator →