---
title: cvd (CVD)
description: "cvd API reference: parameters, response fields and example requests."
---

# `cvd` — CVD

> Category: **Volume** · Composite

::: tip Reading the response
Use `POST /api/indicators?explain=true` to include interpretation notes at `indicators[responseKey].explain`. Read numeric results from `columns` and `data` in the same object.
:::

This is a volume indicator.

## Parameters

| Parameter | Type | Default |
|------|------|--------|
| `fractal_periods` | int | `2` |
| `cvd_period` | int | `21` |
| `ema_trend_period` | int | `50` |
| `max_pivot_bars` | int | `30` |

## Output columns

| Column |
|------|
| `bear_div` |
| `bear_div_strength` |
| `bull_div` |
| `bull_div_strength` |
| `cvd_delta` |
| `cvd_hist` |



## Histogram values and divergence ranges

`cvd_hist` is the per-candle histogram height: positive values indicate buying pressure and negative values selling pressure.
It is a rolling sum of OHLCV-estimated delta, not trade-level aggressive buy/sell flow.
Gold spot without actual trading volume does not support CVD.

Indicators, BYO compute and analyze responses include
`objects.divergences` to each CVD result. Each confirmed event contains:

| Field | Meaning |
| --- | --- |
| `id` | Stable parameter/direction/endpoint identity; namespace by venue, symbol, interval and indicator instance |
| `direction`, `kind` | `bullish` or `bearish`; currently `regular` divergence only |
| `start`, `end` | Each has `time_ms`, `price`, `cvd`: a price pivot and CVD on that same candle |
| `confirmation_bar_time_ms` | Open time of the confirmation candle, not the second pivot |
| `confirmed_at_ms` | Confirmation candle close computed from the interval; null if no interval was supplied |
| `status`, `label` | `confirmed`; bullish `+RD`, bearish `-RD` |
| `strength` | Consecutive-divergence level 1–3, not a probability or win rate |

All event times are **milliseconds**. A range connects two pivots; it is not a holding period or signal expiry.
The default pivot needs two bars on its right. Live APIs confirm only after the confirmation candle's
interval has elapsed, while the forming histogram bar can still change. Revised source data or different
warmup history can change results.

BYO compute assumes the caller supplies closed bars. Set top-level `last_bar_closed: false` when the last
bar is forming; earlier bars must be closed. Supply `interval` to obtain exact interval-based close times;
do not infer durations from gaps in the input.

Set `signals: true` and `include_forming: true` on calculation/chart requests to evaluate the final
OHLCV sample as complete. Pivot windows, trend filtering and strength rules are unchanged; missing right-hand
candles are never invented. In this mode `objects.schema_version=2` and the corresponding chart
`indicator_renderers` declaration also uses version 2. The same `divergences` collection
may contain `status=forming` objects with `confirmed_at_ms=null`; closed objects remain `confirmed`.
Feature IDs are unchanged: the word `confirmed` in an ID does not prove an actual close. A trial may
disappear on updates; identical parameters, direction and endpoints retain the object ID. Chart event markers,
CVD lines and endpoint markers carry `bar_status` (`forming` or `closed`). Omitting or disabling the
option preserves the original object schema and confirmation behavior.

Chart responses include both `indicator_objects` and standard `panels.items`: price lines on the main
panel, CVD lines on the subpanel, RD endpoint labels and arrows at confirmation bars (replaced by unified event markers with `signals: true`). Chart-item `time`
is in **seconds**. The renderer declaration uses `type=cvd-divergence`, `rendered_in_panels=true`:
items are already materialized, so clients must not render duplicate overlays.
Events are filtered by confirmation candle; original endpoints remain intact while drawing geometry
is clipped to the visible window. Multiple CVD instances are isolated by request ID/response key.

## Native features

Set top-level `signals: true` and read `indicators[responseKey].signals`. By default features are evaluated on closed bars: `true` is a positive result, `false` a valid negative result, and `null` unknown. These are not trade instructions.

This indicator supports `include_forming: true`: treat the current final OHLCV sample as complete under the same native rules, returning one set of values, features and objects. The signal table appends `bar_status`: `closed` for closed bars, `forming` for a trial with `confirmed_at_ms=null`. A trial may disappear on later updates or at close. For BYO, still set `last_bar_closed: false`. Close requirements below describe the default mode; trials only admit the final sample without shortening structural windows or model confirmation requirements. See [forming trials](/signals#forming).

History lengths are minimum evaluation requirements, not convergence guarantees. Comparisons use unrounded values and the exact boundaries below. Do not turn `null` into `false` on gaps, invalid dependencies or forming bars in the default mode.

| Feature column | Kind | Rule | Meaning | History / validity |
| --- | --- | --- | --- | --- |
| `cvd.bullish_divergence_confirmed` | `event` | A regular bullish divergence is confirmed on this bar; endpoints and strength are in objects.divergences. | Price and estimated OHLCV delta diverge between consecutive eligible pivots; not trade-level flow or a guaranteed reversal. | max(cvd_period, ema_trend_period, 2 * fractal_periods + 1) contiguous bars with some positive volume. |
| `cvd.bearish_divergence_confirmed` | `event` | A regular bearish divergence is confirmed on this bar; endpoints and strength are in objects.divergences. | Price and estimated OHLCV delta diverge between consecutive eligible pivots; not trade-level flow or a guaranteed reversal. | max(cvd_period, ema_trend_period, 2 * fractal_periods + 1) contiguous bars with some positive volume. |

### `cvd.bullish_divergence_confirmed`

- A lower price low with a higher cvd_hist low; both cvd_hist values < 0 and pivot closes < EMA(ema_trend_period).
- Both pivots must pass the EMA trend filter; their distance is strictly less than max_pivot_bars.
- A high pivot is strictly above neighboring highs; a low pivot is strictly below neighboring lows over fractal_periods bars on each side. Confirm on the rightmost bar's close, never backfill to the pivot.

### `cvd.bearish_divergence_confirmed`

- A higher price high with a lower cvd_hist high; both cvd_hist values > 0 and pivot closes > EMA(ema_trend_period).
- Both pivots must pass the EMA trend filter; their distance is strictly less than max_pivot_bars.
- A high pivot is strictly above neighboring highs; a low pivot is strictly below neighboring lows over fractal_periods bars on each side. Confirm on the rightmost bar's close, never backfill to the pivot.

See [feature requests](/compute#native-features) for the format and examples. `/api/chart` also accepts `signals: true`, marking confirmed events by default. With `include_forming`, trial events also produce markers tagged `bar_status=forming`; states are not drawn on every bar. See [feature charts](/compute#feature-chart).

## Example call

```bash
curl -X POST -H "Authorization: Bearer mq_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "binance",
    "market":   "perp",
    "symbol":   "BTCUSDT",
    "interval": "5m",
    "limit":    100,
    "signals":  true,
    "calc":     [{"name": "cvd", "params": {"fractal_periods": 2, "cvd_period": 21, "ema_trend_period": 50, "max_pivot_bars": 30}}]
  }' \
  https://api.mobiusquant.ai/api/indicators
```

## Full interpretation guide

Field meanings, interpretation rules and usage notes are
documented in Chinese at:

[cvd (中文详情)](https://docs.mobiusquant.ai/zh/indicators/cvd)

## Related indicators

[chaikin_oscillator](./chaikin_oscillator) · [cmf](./cmf) · [kvo](./kvo) · [obv](./obv) · [pvo](./pvo) · [vwap](./vwap)