Volume delta (CVD) of a day

SPX options printed as calls minus those printed as puts, the terminal's CVD band, one row a minute: what printed in the minute and the running totals since 09:30 at its end. Three scopes: today's expiry (0DTE), the near expiries the book models (_next; all expiries is the two summed), and each weighted by the option's delta at the print (cvd_delta, delta-contracts). The volume book's own sign (a call printed is a call), never a guess at which side hit which. ES answers with SPX's: these are counts of SPX options, no basis moves them. Today's rows follow the session with a minute's lag.

GET/api/v1/cvd

Plan LIVEKey scope liveLimit 120 a minute per key; the last 90 days, older with DATASETVersion 1.0.0Since 2026-10-27

This endpoint serves

Plan: LIVE. LIVE: today's session every second, alerts, ASK, the levels API and the platform integrations, and 5 LAB credits a month. Every finished session is free in REPLAY. Pricing.

Parameters

Name	What it does	Default	Error
symrequiredquery · string	SPX or ES (MES answers as ES). Other symbols answer `spx_only`.		`missing_sym`, `spx_only`
dayquery · string	`YYYY-MM-DD`, within the last 90 days; older with the DATASET licence.	the running or most recent session	`bad_day`, `history_too_old`
errorsquery · 200	`200`: an error answers 200 with the same body and the real status in `X-FirmTape-Status`, for clients that cannot read a status.
keyquery · string	Legacy: the key in the address, for platforms that cannot send headers. Prefer the header.

Response

Columns and rows.

Field	Meaning	Unit
symstring	The symbol asked: SPX or ES.
daystring	The ET trading day.
index"SPX"	The options counted: SPX's, whatever was asked.
step"1m"	One row a minute.
unit"contracts"	`calls`, `puts`, `cvd` and their `_next` twins count contracts.
unit_delta"delta_contracts"	`cvd_delta` and `cvd_delta_next` count delta-contracts: each print's size times its delta, not times 100.
sourcerecording \| rebuilt	`recording`: the live engine's per-second counts; `rebuilt`: rebuilt from the raw tape after the day.
as_ofstring	The last second counted, ISO 8601 with the ET offset.
columnsarray	`t`, `calls`, `puts`, `cvd`, `calls_next`, `puts_next`, `cvd_next`, `cvd_delta`, `cvd_delta_next`.
rowsarray	One row a minute: its ET start (`HH:MM`), the contracts printed in it as calls and as puts (today's expiry), the running calls minus puts since 09:30 at its end, the same three for the near expiries, then the two running totals in delta-contracts. A series the day does not carry is null (days before 2026-10-08 carry no delta).

Errors

Status	Code	What to do
400	`missing_sym`, `bad_day`, `spx_only`	A parameter is wrong. Pass `sym`, one symbol or a comma list.
401	`no_key`, `bad_key`	No key, or an unknown or revoked one. Send `Authorization: Bearer <key>` with a key of the product's scope.
403	`live_required`, `history_too_old`	No LIVE plan, or a day older than 90 days without DATASET. Start or renew LIVE; `pricing` names the page.
404	`unknown_symbol`, `no_cvd`	No such symbol, or no volume delta for that day. Pick one from `GET /api/v1/symbols`.
429	`rate_limited`	Over a limit. Wait `Retry-After` seconds; poll with `If-None-Match`, a 304 is free.
503	`unavailable`	The volume archive did not answer. Retry shortly.

Every code: Errors.

Caching

Answers carry an ETag: send it back as If-None-Match and an unchanged reading answers 304 with no body, not counted against the limit.

Changes

2026-10-27 Added.

OpenAPI operation getCvd in /docs/developers/openapi.json.

Request

curlPythonNode

curl \
  -H "Authorization: Bearer $FIRMTAPE_LIVE_KEY" \
  "https://firmtape.com/api/v1/cvd?sym=SPX,ES"

import os, requests

H = {"Authorization": f"Bearer {os.environ['FIRMTAPE_LIVE_KEY']}"}
r = requests.get("https://firmtape.com/api/v1/cvd?sym=SPX,ES", headers=H)
print(r.status_code, r.text[:500])

const r = await fetch("https://firmtape.com/api/v1/cvd?sym=SPX,ES", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.FIRMTAPE_LIVE_KEY}` },
});
console.log(r.status, await r.text());

Response

200304400401403

{
  "sym": "SPX",
  "day": "2026-10-15",
  "index": "SPX",
  "step": "1m",
  "unit": "contracts",
  "unit_delta": "delta_contracts",
  "source": "recording",
  "as_of": "2026-10-15T15:59:59-04:00",
  "columns": [
    "t",
    "calls",
    "puts",
    "cvd",
    "calls_next",
    "puts_next",
    "cvd_next",
    "cvd_delta",
    "cvd_delta_next"
  ],
  "rows": [
    [
      "09:30",
      11642,
      13445,
      -1803,
      3024,
      7441,
      -4417,
      -873.22,
      -180.72
    ],
    [
      "09:31",
      9120,
      8810,
      -1493,
      2210,
      2540,
      -4747,
      -640.5,
      -201.1
    ]
  ]
}

(no body)

{
  "error": {
    "code": "missing_sym",
    "message": "No sym was given."
  }
}

{
  "error": {
    "code": "no_key",
    "message": "No key was sent (Orders: no key, or one that is unknown or revoked)."
  }
}

{
  "error": {
    "code": "live_required",
    "message": "The key is real; its account holds no active LIVE plan."
  }
}

Headers

ETag: "3f9a0c6e21d4b7a8e5f10c2d4b7a8e5f"
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117

Measurements of dealer positioning, never a forecast or a trade call. This page is built from FirmTape's public contract, the same files the OpenAPI document is built from; the tests hold them against the route code. Markdown: /docs/developers/live/cvd.md.