ChartnautDocs

Overview

This section is the code reference for indicator, definition and study scripts: every declaration, hook and ctx call, with examples you can paste into a builder's Code tab.

You do not need code to use Chartnaut. The Agent and each builder's agent write these scripts for you. Open these pages to write a script yourself, to read what an agent wrote, or to fix a lint error, a budget warning or a definition that emits nothing.

Map of this section

Section

Use it for

Getting started

Which script type to write, how a script is laid out, a first script of each type

Accuracy and guarantees

What the engine promises about bars, warmup, seams and anchors, and the limits and errors you can hit

Shared runtime

What every script shares: bar data, ctx.accum, inputs, dependencies, drawing, layers, timeframe handles, sessions, budgets, lint codes. Start here for APIs

Indicator API

Overlay or pane, series types, panes and scales, onBar, layers

Indicator examples

Ten library indicators, from Volume to VWAP

Definition API

events.declare, ctx.emit and labels, multi-file packages

Definition examples

Bull bar, EMA cross, session opening-range break

Study API

onEvent and onFinish, ctx.collect and ctx.publish, results, Forward Insights

Study examples

Event count, forward return, stop or target first hit

Agents

What the Agent and each builder's agent write, and the checks they run

Troubleshooting

FAQ, and pages that go from a symptom to its fix

What definitions, studies and indicators are for is covered in the guides: How research works and How indicators work. This section covers how to write them.

Write scripts from a terminal or a coding agent

The same scripts run outside the app. The Chartnaut CLI and the Chartnaut API take the code, run it on Chartnaut's servers on the instrument, timeframe and range you ask for, and return what the script produced: an indicator's series, a definition's events or a study's results. You never receive raw candles. Both need Starter or above.

chartnaut new definition or-break
chartnaut validate definitions/or-break
chartnaut run definitions/or-break --on EURUSD --tf 5m --last 30d
chartnaut push definitions/or-break -m "first version"

chartnaut run on a folder runs your local files and saves nothing. chartnaut push saves a new version, the same one you see in the app's builder, and chartnaut pull brings down a script you saved in the app. Saving and versions

Claude Code and Codex work well here. chartnaut init writes a guide the agent reads, and chartnaut docs <topic> prints any page in this section in the terminal. Working with Claude Code and Codex

How to read the API

  1. Learn the shared pieces in Shared runtime: drawing, indicators.declare, inputs, timeframe handles.

  2. Open the Indicator, Definition or Study section only for what that type adds: series outputs, events, or collect and publish.

  3. To put a study's numbers on Charts, see Show studies on charts.

The pipeline

  1. Indicator draws values on the chart, bar by bar (onBar, ctx.plot).

  2. Definition marks a setup every time it happened in history (events.declare, ctx.emit with a required label).

  3. Study measures what followed those events (onEvent, ctx.publish).

  4. Forward Insight shows a study's answer on Charts when the setup forms again. You create one with Attach to chart on a finished study run.

Definition events painted on a chart preview
A definition's events marked on the builder's chart preview.

Common questions

Do I have to write code?

No. Start with Test your first trading idea or Build your own indicator, which use the Agent.

Which script type should I write?

See Choose your DSL.

Where are ctx.plot, ctx.range, ctx.hline and ctx.mark documented?

In Drawing on the chart.

I want lines and histograms on the chart.

Read Series types, then Build a custom indicator.

I want to mark a setup in history.

Read Emit and labels, then Build a definition.

I want to measure what happens after a setup.

Read the Study API, then Build and run a study.

I want study numbers on my live chart.

See Show studies on charts and Forward Insights.

My script is slow or fails with a budget warning.

See Budgets and limits.

How do the agents write this code?

See the Agents overview.

NextOverview