General FAQ

Getting Started

What is kScript?

kScript is a TypeScript-based domain-specific language designed for financial data analysis and visualization. It allows you to write scripts for technical analysis, trading indicators, and market data processing with a syntax similar to Pine Script but powered by modern web technologies.

Do I need to know TypeScript to use kScript?

No, you don't need to know TypeScript. kScript has its own simplified syntax. However, familiarity with programming concepts will help you write more complex scripts.

Data Sources and Context

What are `currentSymbol` and `currentExchange`?

These are built-in context variables that automatically contain the current trading pair and exchange being analyzed:

Why do I get NaN when accessing historical data in early bars?

kScript executes per-bar, meaning on each bar, only data up to that point is available. When you access historical data like data[5], the first 4 bars will return NaN because there aren't 5 bars of history yet:

Solution: Always check for NaN or ensure enough historical data exists before using it in calculations. You can use the barIndex to make sure you're not accessing data too early.

Can I analyze multiple symbols in one script?

Yes, but you need to explicitly specify each symbol:

Can I write a script without source data?

No, you cannot run a script without source data. kScript is designed for time-series analysis and requires data to create the timeline for bar-by-bar execution. Even if you declare sources but they return empty data, the script won't run because there are no bars to process.

No, you cannot call source functions inside control structures. Source subscriptions must be declared at the root level of your script in timeseries declarations.

Why: Sources need to be fetched and prepared before the script can execute. The runtime extracts source calls during the initialization phase, before the bar-by-bar loop begins. Dynamic source subscription during control flow would require async operations that aren't supported.

How do I access orderbook heatmap raw data?

Orderbook data is accessed through specialized built-in functions that operate on orderbook timeseries sources. The data structure is [timestamp, price1, amount1, price2, amount2, ...] where positive amounts are bids and negative amounts are asks.

Available functions:

sumBids(source, depthPct=10) - Sum of all bid amounts within depth percentage
sumAsks(source, depthPct=10) - Sum of all ask amounts within depth percentage
maxBidAmount(source, depthPct=10) - Maximum bid amount within depth
maxAskAmount(source, depthPct=10) - Maximum ask amount within depth
minBidAmount(source, depthPct=10) - Minimum bid amount within depth
minAskAmount(source, depthPct=10) - Minimum ask amount within depth

How does kScript handle data gaps and interpolation?

kScript fills data gaps with NaN values. The system creates a continuous timestamp array based on the interval, and when fetched data doesn't match the timeline length, gaps are pre-filled with NaN.

Important: For line plots, kScript will interpolate to connect points across gaps. For other use cases, if you need interpolation (forward fill, linear interpolation, etc.), you must implement it manually using custom logic.

Technical Indicators

Why am I getting NaN values in my calculations?

NaN (Not a Number) usually occurs when:

There's insufficient historical data for the calculation
You're dividing by zero
The data source has gaps

Solution: Check for NaN values:

Plotting and Visualization

How do I plot multiple indicators on the same chart?

Can I plot conditional signals?

Yes, use ternary operators or conditional values:

How do I change plot colors dynamically?

Use the colorIndex parameter:

Can I call plot functions inside conditionals (if-else) or loops?

Conditionals (if-else): Yes - You can call plot functions inside if-else statements. The plot will execute conditionally based on the condition at each bar.

Loops: Not allowed - Plotting inside loops would create multiple plot outputs per bar, which is not the intended behavior and may cause unexpected results.

What's the difference between `plotLine()` and `plot(plotType="line")`?

There is NO functional difference. plot() with plotType="line" is simply an alias that internally calls plotLine(). The plot() function is a generic interface that can create different plot types by changing the plotType parameter.

Available plot types via plot():

plotType="line" or "spline" → calls plotLine()
plotType="bar" → calls plotBar()
plotType="candle" → calls plotCandle()
plotType="point" → calls plotShape()

How does the positioning system work for shape and text plots?

Shape and text plots use a coordinate-based positioning system with price (y-axis) and time (x-axis):

X-axis (Time): Automatically set to the current bar timestamp. For plotRange(), you can specify custom timestamps for time1 and time2.
Y-axis (Price): Explicitly provided as the price or value parameter.
Text alignment: xAlign and yAlign parameters affect rendering relative to the anchor point.

Common Issues and Troubleshooting

My script isn't displaying anything. What's wrong?

Check:

You have a proper define() statement
You're plotting something with plotLine(), plotBar(), etc.
Your data source is valid. Empty data sources can lead to empty charts.
Check the Problem pop up for error messages

I'm getting "Undefined identifier" errors

Make sure:

Variables are declared before use
Variable names are spelled correctly
You're using proper scope (variables declared in functions are local)

How do I debug my kScript code?

Use print() and printTimeSeries() statements to output values:

Why is my indicator not updating in real-time?

Ensure you're:

Using timeseries data correctly
Not using static calculations where dynamic ones are needed
Plotting the results properly

Can I use `null` instead of `na` to indicate empty data?

No, using null will cause plot values to become 0 because the runtime's Number(null) returns 0, not NaN. This means your "empty" data points will plot as zero values instead of gaps.

Solution: Use NaN to represent missing data. The runtime properly handles NaN as missing data, and plot functions will show gaps where NaN values occur.

Language Features and Syntax

Does kScript support switch statements?

No, kScript v2 does NOT support switch statements. Only if-else conditionals and loops (for, while) are supported control structures.

Workaround: Use nested if-else chains to achieve similar functionality.

Are objects and arrays supported in kScript?

Arrays: Partial support - Arrays are supported with type restrictions. Arrays must contain elements of the same type (homogeneous arrays).

Supported array types:

number[] - Array of numbers
string[] - Array of strings
any[] - Generic arrays (for mixed timeseries/number)

Objects: Very limited - Objects are treated as type any. Main use cases are input() constraints like {min: 0, max: 100} and accessing timeseries fields via member access like ohlcv.close. You cannot create custom objects with arbitrary properties.

Can a script get signals from another script or indicator?

No, kScript v2 does NOT currently support cross-script communication. Each script runs in isolation and cannot access data or signals from other scripts. Each script has its own runtime context, data manager, variable environment, and series storage.

Note: Cross-script communication will be added as a feature soon.

Workaround: Use shared data sources. Both scripts can subscribe to the same source data and process it independently. Alternatively, combine the logic of multiple indicators into a single script.

Can I use timeseries in custom functions and control structures?

Yes and No, with important constraints:

Custom Functions:

Timeseries CAN be passed as parameters to custom functions
Inside functions, timeseries are automatically indexed at the current bar to get numeric values. However, the behavior will not be intended, as the timeseries will be treated as a single value. For example, OHLCV timeseries data will be treated as a singular open data value.

Control Structures:

Timeseries cannot be declared inside control structures (if/for/while)

Use static for constants
Avoid redundant calculations
Use built-in functions instead of custom implementations
Limit historical data lookback when possible

Common Error Messages

What does "source must be a timeseries" mean?

You're passing a regular variable to a function that expects timeseries data:

💡

Still Have Questions?

Can't find what you're looking for? We're here to help!

Join the discussion in #kscript-floor or check out the kScript Reference for more details.