LitScript Manual (v1)


Before You Start

Intro

The idea of LitScript is to be as close to PineScript, we want to make the experience of switching from one to another as effortless as possible. It's intended to be a resource for people who already have some familiarity with PineScript or any other basic programming languages.

💡

If you wish to help us improve these docs, then please reach us out on Discord.

Version 1

At this moment by default LitScript uses an old version, and these docs are aimed for version=1

Please write //@version=1 in front of every script you make.

Quickstart Script

Same quickstart script as PineScript.

//@version=1
study("My Script")
var fast = 12, slow = input("Slow", 26)
var fastMA = ema(close, fast)
var slowMA = ema(close, slow)
seq macd = fastMA - slowMA
var signal = sma(macd, 9)
plot(macd, color=color.blue)
plotshape(signal, shape.up, 10, color=color.yellow)

Basics

Main Functions

Function that you'll be using the most is study() which is mandatory for any script.

Afterwards input() in order to able to change script settings on the fly without editing the script itself.

Built-in function limitations

Currently the way functions receive their properties is a mix between named and unnamed values.

For instance, you can write input("test", 123) but you can't write input(title="test", value=123) but as for most optional arguments, this is is different.

(e.g you can write input("test", 123, min=0) but not input("test", 123, 0) because LitScript doesn't know what that last 0 refers to.)

How to Plot on Chart

Plotting something on the chart is fairly straightforward:

plot(open, color=#FFF)

You can find various other plot drawing functions here such as histogram, shapes, fill, and more.

Language Basics

Differences & Limitations

LitScript is still in experimental phase, issues may arise and syntax could change in the future.

Variable Definitions

Simple variable definition

You can define a variable using the keyword var in front of your variables.

var myValue = 5

Series/Sequence definition

You can define a series variable, although we call them sequences in LitScript.

RULE OF THUMB: If you don't know if you need to use this, just simply use var unless compiler complains

seq series = open + 10

This sequence can be access it by writing series (which is equivalent to series[0]) or series[1] if you want to lookup previous value.

Global variable definition

You can define a variable that persists between bars, this allows for a more advanced algorithms.

//@version=1
global total_counter=0, realtime=0

if (barstate.isnew) total_counter++
plot(total_counter,color=#AF0)

if (barstate.isrealtime) realtime++
plotshape(total_counter, shape.circle, realtime)

Multiple definitions on a single line

Multiple definitions can be stacked on one line using a comma

seq seriesA = open, seriesB = close, something = 99
var test = 10, something = 20

Constants

Constants are values that are defined once and can no longer be redefined afterwards.

const myValue = 5

Self-referencing values

In order to self reference you need to first define then set it to something.

seq test = 0
test = test + 1

NaN / na

NaN (Not A Number) values are supported, written as na

Conditional Statements

if else statements

if (condition1) {
} else if (condition2) {
} else { }

Scopes are optional for single line statements. e.g.

if (test==2) test=1
else test=2

Shorthand conditional expressions

You can use ternary conditional operators

var test = condition ? true : false

you can also use iff() function

var test = iff(condition,true,false)

Iterators & Loops

It is pretty close to JavaScript, with some minor differences and restrictions:

🔧

Loops are limited to 1000 iterations for your own safety.

for()

for(i=0;i<10;i++) { // simple loop to 10
    /* code */ 
}

for(j=1;j>0;j-=0.05) { // reverse loop with fractions
    /* code */ 
}  

while()

while(condition) { 
    /* code */ 
}

switch()

switch(somevariable){ // switch statements !
    case 0:
        /* code */
        break
    case 1:
    case 2:
        /* code */
        break
    default:
        /* code */
        break
}

Function Declarations

Explicit variable type definition for functions

  • ⚠ Functions are still experimental, so bugs may arise

  • ⚠ Defining series variables INSIDE a function might not work as expected

Single line functions

//@version=1
study("My Script")
func zigzag(val:seq) => val[2] == 0 ? 50 : 0
seq test = 0
test = zigzag(test)
plot(test, color=#0ff)

Multi-line functions

//@version=1
study("My Script")
func mipmap(val:seq){
    var temp = val[1]
    if (temp == -10)
        temp = -20
    else
        temp = -10
    return temp
}
seq hiya = 0
hiya = mipmap(hiya)
plot(hiya, color=#ff0)

Function type declaration issues

💡

Note that if you're passing a series variable, you have to use :seq as shown in the following example

func MyFunc(mySeriesVar:seq, myVar) => mySeriesVar[1] * myVar

Operators

Operators

Alternative

Description

or

||

Or

and

&&

And

==

none

Equal to

!=

none

Not equal to

+ - * /

+= -= *= /=

Simple arithmetic operators

++ --

none

Increase / decrease value by one

% | ~ ^

none

Various other advanced operators (similar to JavaScript)

Available Data

Price

Returns candle values (timeseries), values are affected by heiken ashi when enabled

open, high, low, close

The following averages are also available:

ohlc4, hlc3, hl2

Basic Example

//@version=1
study("Price Candles", overlay=false)
plotcandle(open, high, low, close) // candle plots

Volume

Returns volume buy/sell values (timeseries)

vbuy, vsell

Basic Example

//@version=1
study("Volume", overlay=false)
var v = (vbuy + vsell)
histogram(v, color = close<open ? color.red : color.green)

Volume Delta Example

//@version=1
study("Volume Delta", overlay=false)
var vd = (vbuy - vsell)
histogram(vd, color = vd<0 ? color.red : color.green)

CVD (Cumulative Volume Delta) Example

//@version=1
study("CVD (Cumulative Volume Delta)")
seq vd = vbuy-vsell
var cvd = cum(vd)
plot(cvd, color=#00ff00)

Bids & Asks

Bid/Ask Sum

Returns a sum of bid/ask values

The range depends on the heatmap definition ( SD or HD heatmap )

  • SD heatmap max range is 220% of the closing price

  • HD heatmap max range is 120% of the closing price

//@version=1
study("[example] Bid/Ask Sum")
plot(bid_sum(),color=#AF0)
plot(ask_sum(),color=#F30)

Bid/Ask Sum Range (Percent)

Returns a sum of bid/ask sum of a specific range
( ⚠ This feature is experimental and slow )

  • range — Range in %, (e.g. bid_sum(120) 120% range of its current closing price)

//@version=1
study("[example] Bid/Ask Sum 15% Range")
plot(bid_sum(15),color=#AF0)
plot(ask_sum(15),color=#F30)

Bid/Ask Sum Absolute Range

Returns a sum of bid/ask sum of a specific price range

This feature is experimental, slightly faster than percent equivalent

  • price_min — Min value

  • price_max — Max value

//@version=1
study("[example] Bid/Ask Sum Absolute range (4000 from current price)")
plot(ask_sum(0,close+4000),color=#AF0)
plot(bid_sum(close-4000,0),color=#F30)

Bid/Ask Sum Example

//@version=1
study("Bid/Ask Range Sum Bands")

const divide = input("Divide by", 7)
plots[10] asks, bids

for (i=1;i<=10;i++) append(asks,ask_sum((i*i)/divide), darken(#FFAA00,i*10))
for (i=1;i<=10;i++) append(bids,-bid_sum((i*i)/divide), darken(#AAFFAA,i*10))

plot(asks)
plot(bids)

plot(ask_sum())
plot(-bid_sum())

plot(0, color=#333) // middle line

Bid/Ask Highest Size Price

Returns price where the bid/ask is at its highest size

//@version=1
study("[example] Bid/Ask Highest Size Price")
plot(ask_highest(),color=#F30)
plot(bid_highest(),color=#AF0)

Bid/Ask Spread Price

Returns price where cumulative bid/ask size starting from current price reaches the specified total threshold size

  • size — Total threshold size

//@version=1
study("[example] Bid/Ask Spread")
plot(ask_spread(100000),color=#F30)
plot(bid_spread(100000),color=#AF0)

Open Interest

Returns open interest candle values (timeseries)

🔥

Open Interest only available to subscribers.

Open Interest is also available as a built-in layer so you don't have to code one.

oi_open, oi_high, oi_low, oi_close

The following averages are also available:

oi_ohlc4, oi_hlc3, oi_hl2

Example:

//@version=1
study("Open Interest in LitScript", overlay=false)
plotcandle(oi_open, oi_high, oi_low, oi_close)

Liquidations

Returns ask or bid liquidations (timeseries)

🔥

Liquidations only available to subscribers.

liq_ask, liq_bid

Funding and Mark Price

Returns funding, funding_predicted or mark_price (timeseries)

🔥

Funding only available to subscribers.

funding, funding_predicted, mark_price

Array/Matrix Plots

Array/matrix plots are special kind of plots, helps avoid writing unnecessary bloat in your code.

In order to use them, you have to define an array, use append, then use plot to draw them.

🔧

Max array limit is 64 plots

Examples:

//@version=1
plots[2] array// size is a positive value, represents the amount of charts to create
append(array, open, #FF00FF) // fill the first chart's array data
append(array, close, #FF00FF) // fill the first chart's array data
plot(array) //plot the 
//@version=1
study("array overlaid example", overlay=true)
plots[32] levelsA // array allows us to generate 32 charts easily
plots[10] levelsB

// simple for loop
for (i=0;i<32;i++) {
  append(levelsA, sma(open,i*2)+i*20, lighten(#509,i*5))  // append is how we fill the data for arrays plots
}

for (i=0;i<100;i+=10) { // step by 10
  append(levelsB, sma(open,i*2)-i*20, darken(#B09,i*2))
}

plot(levelsA)
plot(levelsB)

Colors

Color Basics

Color definition

Colors can be defined using 3 character hexadecimal notation (e.g. #F0b), 6 characters (e.g. #FF00BB) or using builtin static color names (e.g. color.magenta)

Color Alpha

You can now also use alpha inside colors, using 4 character hexadecimal (e.g. #F0BA ) or 8 characters (e.g. #FF00BBAA ) where the last two letters represent the alpha value.

List of static colors

All built-in colors should start with color. e.g. color.blue

black, white, red, orange, lime, blue, yellow, cyan, magenta, silver, gray, maroon, olive, green, purple, teal, navy

Color blending

Color functions

brightness(color, amount) // adjusts color's brightness by a value ( 0-255 )
darken(color, amount) // alias to brightness(color, -amount)
lighten(color, amount) // alias to brightness(color, amount)
blend(colorA, colorB, amount) //  blends between two colors by amount ( 0.0-1.0 )

Example:

//@version=1
study("MyScript")
var mycolor = blend(#f00,#0f0,(open-open[1])/10)
plot(open, linewidth=10, color=mycolor)