WHALE ENGINE
Documentation

Volume Weighted Average Price (vwap)

Volume Weighted Average Price (VWAP) calculates the average of its source from an anchor while weighting each candle by volume. Candles with more volume therefore have more influence on the series. The result remains in the same unit as the source and represents the volume-weighted mean of the entire accumulated period.

The calculation is cumulative rather than rolling: it includes every candle from the latest anchor until the next reset. Without anchor, a new period starts on the first loaded candle and then at the beginning of each UTC day. When anchor is set, the custom anchor replaces the daily schedule and each trigger starts a new period. The source’s position above or below VWAP expresses its distance from the volume-weighted mean since the anchor.

Block declaration

A strategy can contain multiple [[vwap]] blocks. Each block produces one numeric series identified by its id field.

When a parameter contains several values, Whale-E materializes one variant for every combination. For a VWAP block, the variant count is the product of its symbols, timeframes, sources, and anchors. An omitted parameter counts as one inherited or default value.

Volume is always read implicitly from the candles for the block’s symbol and timeframe. The block does not accept a volume parameter.

Examples

Minimal setup

This block uses the default hlc3 source and daily anchor.

[[vwap]]
id = "daily_vwap"

Custom source

This block weights the closing price by volume instead of using hlc3.

[[vwap]]
id     = "close_vwap"
source = "close"

Custom anchor

The [[custom_series]] block below produces a series that is true when the close is above the open. Every true value resets anchored_vwap. This example demonstrates the anchor syntax; in an actual strategy, the series can represent whichever reset event fits the scenario being tested.

[[custom_series]]
id      = "reset_signal"
formula = "close > open"

[[vwap]]
id     = "anchored_vwap"
source = "close"
anchor = "reset_signal"

Multiple custom anchors

This block creates two anchored_vwap variants. The first uses reset_up, while the second uses reset_down. In each variant, the anchored_vwap.anchor string variable identifies the selected anchor.

[[custom_series]]
id      = "reset_up"
formula = "close > open"

[[custom_series]]
id      = "reset_down"
formula = "close < open"

[[vwap]]
id     = "anchored_vwap"
source = "close"
anchor = ["reset_up", "reset_down"]

Filter relative to VWAP

This condition lets the strategy continue when the close is above the daily VWAP.

[[vwap]]
id = "daily_vwap"

[[condition]]
id            = "above_vwap"
condition     = "close > daily_vwap"
next_block_id = "..."

Dedicated symbol and timeframe

This block calculates a daily-anchored VWAP on hourly candles for BINANCE:ETHUSDT. The daily reset still follows UTC days on the selected timeframe. See Exchanges, Symbols and Timeframes for alignment rules with the primary symbol and timeframe.

[[vwap]]
id        = "eth_vwap"
symbol    = "BINANCE:ETHUSDT"
timeframe = "60"

Parameters

ParameterDescription
id
 String
 Required		Unique name identifying the VWAP series produced by the block.
source
 String
 or Array
 Optional		Numeric series weighted by volume.
Each value can be a standard source (open, close, high, low, hl2, hlc3, ohlc4, hlcc4, volume) or the id of another indicator.
When an array is provided, the block creates one variant for each source.
Default: "hlc3".
anchor
 String
 or Array
 Optional		Identifier of a numeric series that triggers a VWAP reset. Zero and NaN are false; any other value is true. The candle that triggers the anchor is the first candle in the new calculation.
When an array is provided, the block creates one variant for each anchor. These variants combine with those created by source, symbol, and timeframe.
If anchor is omitted or the array is empty, the block uses a daily UTC anchor.
symbol
 String
 or Array
 Optional		Market symbol or symbols that provide the implicit volume and any standard sources used by the block.
If symbol is omitted, the block inherits the primary symbol defined in [backtest].
For symbol formats, arrays, and alignment rules, see Exchanges, Symbols and Timeframes.
timeframe
 String
 or Array
 Optional		Timeframe on which VWAP, its source, its volume, and its anchor are aligned.
If timeframe is omitted, the calculation uses the grid’s primary timeframe defined in [backtest].
For accepted formats and timeframe alignment rules, see Exchanges, Symbols and Timeframes.

Available variables

The VWAP block exposes its numeric series together with metadata for its inputs, symbol, and timeframe.

Assume the block is configured as:

[[vwap]]
id     = "anchored_vwap"
source = "close"
anchor = "reset_signal"

Then:

VariableDescription
anchored_vwap or anchored_vwap[0]
Decimal		Current VWAP value.
anchored_vwap[n]
Decimal		VWAP value from n candles ago.
anchored_vwap.source
String		Name of the series weighted by volume.
anchored_vwap.volume_source
String		Name of the implicit volume series used in the calculation.
anchored_vwap.anchor
String		Name of the anchor series selected by the active variant. This variable is available only when at least one custom anchor is set.
anchored_vwap.symbol
String		Market symbol used by the VWAP series.
anchored_vwap.timeframe
String		Timeframe used by the VWAP series.

Notes

  • VWAP is calculated as sum(source × volume) / sum(volume). The candle that triggers an anchor is included in the new cumulative period.
  • With a custom anchor, the series remains NaN until the first trigger. If the source or volume becomes NaN after the calculation starts, the cumulative state remains NaN until the next anchor.
  • The implicit daily anchor cannot be included in an array of custom anchors. Separate [[vwap]] blocks are required to expose both anchor types in the same strategy.
  • Numeric variables support arithmetic, comparisons, and logical operators.
  • Text variables are strings intended for equality and inequality checks.
Prev
Variance