Quick Reference

Every v2 script starts with //@version=2. Top-level code runs once; onBar(index) runs per bar. index is distance from newest bar (0 = newest).

//@version=2
indicator("My Script", overlay?)
const len = input.int("Length", 20)
const candles = subscribe(data.OHLCV)
function onBar(index) { plot("SMA", ta.sma(candles.close(), len)) }

Top-level only: indicator(), subscribe(), subscription.calc(), input.*(), alert.define()

Limits

data.VOLUME follows the non-BOOK plan limit.

Context

Data Sources

subscribe(source)
subscribe(source, { exchange?: string, symbol?: string, timeframe?: number | string })

All accessors accept an optional offset, where 0 is current and 1 is previous.

BOOK at a Glance

• Snapshot metadata: book.unix(), book.binSize(), book.numLevels(), book.numBids(), book.numAsks()
• Top of book: book.bestBid(), book.bestAsk(), book.mid()
• Per-level reads: book.askPrice(level), book.bidPrice(level), book.askSize(level), book.bidSize(level)
• Native helpers: book.depth(...), book.imbalance(...), book.depthMany(...), book.imbalanceMany(...)
• book.data() and book.dataView() are removed for BOOK and now throw a migration error

book.depth(refPrice, outerPct, opts?, offset?) -> BookDepth | null
book.imbalance(refPrice, outerPct, opts?, offset?) -> BookImbalance | null
book.depthMany(refPrice, requests, offset?) -> Array<BookDepth | null>
book.imbalanceMany(refPrice, requests, offset?) -> Array<BookImbalance | null>

• refPrice: finite number greater than 0
• outerPct: finite percent distance from refPrice, >= 0
• opts: { innerPct?: number, mode?: "cumulative" | "differential", unit?: "quote" | "base", distanceDecay?: number }
• requests[i]: { outerPct: number, opts?: { innerPct?: number, mode?: "cumulative" | "differential", unit?: "quote" | "base", distanceDecay?: number } }

BookDepth = {
  unix, binSize, bidValue, askValue, bidQty, askQty, bidLevels, askLevels
}

BookImbalance = {
  unix, bid, ask, ratio
}

VOLUME at a Glance

• Snapshot metadata: volume.unix(), volume.binSize(), volume.numLevels()
• Per-level reads: volume.price(level), volume.buyVol(level), volume.sellVol(level)
• Structured snapshot access: volume.dataView() and volume.data()
• Native helpers: volume.summary(...), volume.range(...), volume.rangeMany(...), volume.poc(...), volume.valueArea(...), volume.rebucket(...)
• Native helpers can return null; guard before reading fields such as .price, .lowPrice, or .totals

volume.dataView(offset?) -> VolumeDataView
volume.data(offset?) -> VolumeDataView
volume.summary(offset?) -> VolumeSummary | null
volume.range(minPrice, maxPrice, offset?) -> VolumeRange | null
volume.rangeMany(requests, offset?) -> Array<VolumeRange | null>
volume.poc(offset?) -> VolumePoc | null
volume.poc(opts, offset?) -> VolumePoc | null
volume.valueArea() -> VolumeValueArea | null
volume.valueArea(percent, offset?) -> VolumeValueArea | null
volume.valueArea(opts, offset?) -> VolumeValueArea | null
volume.valueArea(percent, opts, offset?) -> VolumeValueArea | null
volume.rebucket(opts, offset?) -> VolumeBuckets | null

• dataView() / data() result: { unix, binSize, prices: Float64Array, buys: Float64Array, sells: Float64Array }
• rangeMany requests[i]: { minPrice: number, maxPrice: number }
• poc/valueArea opts: { minPrice?: number, maxPrice?: number, basis?: "total" | "buy" | "sell" | "deltaAbs" }
• valueArea percent: defaults to 70
• rebucket opts: exactly one of { bucketCount: number } or { levelsPerBucket: number }, with optional minPrice / maxPrice
• out-of-range dataView(offset?) returns NaN scalar fields with empty typed arrays

VolumeSummary = {
  unix, binSize, levels, minPrice, maxPrice, buy, sell, total, delta, ratio
}

VolumeRange = {
  unix, binSize, levels, fromPrice, toPrice, buy, sell, total, delta, ratio
}

VolumePoc = {
  unix, price, index, buy, sell, total, delta, ratio
}

VolumeValueArea = {
  unix, pocPrice, lowPrice, highPrice, levels, buy, sell, total, delta, ratio
}

VolumeBuckets = {
  unix, sourceBinSize, prices, buys, sells, totals, deltas
}

VD / CVD Buckets

data.VD and data.CVD support trade-size buckets via subscribe(source, { bucket: number }).

const vd = subscribe(data.VD, { bucket: 10 })
const cvd = subscribe(data.CVD, { bucket: 3 })

Extra accessors on bucketed subscriptions:

vd.bucket() -> number
vd.bucketInfo() -> { id: number, label: string, minValue: number, maxValue: number }

Both support aggregated exchanges: subscribe(data.VD, { exchange: agg("bybitf", "binancef"), bucket: 3 }).

See Data Sources for full signatures, argument types, result shapes, and working examples.

HTF offsets use that subscription's clock, not the chart clock.

Higher Timeframes & calc

const htf = subscribe(data.OHLCV, { timeframe: "1h" })
const htfEma = htf.calc(src => ta.ema(src.close(), 20))  // top-level only
function onBar(index) { plot("EMA", htfEma()) }

calc runs on the subscription's clock. Callbacks may return a number or a flat object snapshot. No plotting, entities, logging, inputs, or subscribe allowed inside calc callbacks.

Inputs

All input functions accept shared options: key?: string, description?: string, sameLine?: bool, required?: bool, onlyIf?: condition.

Conditional visibility — use in onlyIf option:

Plotting

All plot functions accept forceOverlay?: bool to render on the price chart regardless of indicator overlay setting.

Skipping a plot call on a bar = na. Declare all labels during history warmup. bg/fill are effect-style — no na gap when skipped.

Entities

All require //@version=2 and a unique key string per type per bar. All return a handle with .set(opts?), .clone(newKey), .delete(). All accept forceOverlay?: bool.

Key identity is (type, key, bar unix). Recreate or upsert keyed entities inside onBar on every bar where they should exist, and use the handle returned for that bar. If you keep a handle variable, overwrite it with the latest constructor result before calling .set().

Stale-handle behavior:

• After .delete(), the handle becomes invalid and later .set() / .clone() / .delete() calls throw invalid entity handle.
• If the underlying entity was removed later, .set() / .clone() can throw entity does not exist.

entity.delete(handle) -> bool — global delete helper.

Technical Analysis — ta.*

Moving Averages

Oscillators

Volume-Based

Volatility

Aggregation

Change Detection

Crossovers

Math — math.*

Rounding

Aggregation & Clamping

Basic & Logarithms

math.abs(v) math.floor(v) math.ceil(v) math.trunc(v) math.pow(base,exp) math.sqrt(v) math.exp(v) math.sign(v) math.log10(v) math.log2(v) math.logN(v,base)

Utilities

Strings — str.*

Colors — color.*

Constants: up down red green blue yellow teal magenta white orange black pink purple brown gray transparent cyan indigo silver emerald amber lightskyblue maroon navy olive

Gradient aliases: color.mode.clamp color.mode.wrap color.mode.mirror color.space.rgb color.space.hsl color.easing.linear color.easing.smoothstep color.easing.smootherstep

Examples: Colors & Gradients

Colors accept hex strings (#RRGGBB / #RRGGBBAA) or ABGR numbers. Functions return hex strings.

color.up / color.down are based on your terminals theme up and down colors.

Timeframes — timeframe.*

Timeframe strings: 10s, 30m, 4h, 1D, 2W, 3M, 1Y.

Globals

Alerts

const crossUp = alert.define("ema.cross.up", {
  title: "EMA Cross Up",
  fields: [
    { key: "price", type: "number" },
    { key: "fast", type: "number" },
    { key: "slow", type: "number" }
  ]
})

crossUp.trigger({ price: close, fast, slow })

See Alerts for trigger mode behavior and payload validation.

Drawing Constants