Developers menu

Get levels

The volume book's flip, call wall, put wall and net gamma for up to 20 symbols in one call, with the open-interest book alongside under oi.

GET/api/v1/levels

Plan LIVEKey scope liveLimit 120 a minute per key; a 304 is freeVersion 1.0.0Since 2026-09-30

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	Comma list, up to 20: `SPX,ES,NQ,QQQ`. MES, MNQ and M2K answer as ES, NQ and RTY; a dated contract (`ESH27`) names that contract.		`missing_sym`, `too_many_symbols`
includequery · gamma	`gamma` adds each symbol's gamma by strike: one request per chart.
bookquery · vol \| oi	With `include=gamma`: which book's strikes.	vol	`bad_book`
contractquery · string	Futures: a dated contract in the two weeks before a roll, e.g. `ESH27`. The levels move by that contract's own basis.	the front quarterly	`contract_not_live`
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

One entry per symbol asked, in order. A symbol that fails carries its own error; the rest still answer.

Field	Meaning	Unit
book"volume"	Always `volume`.
next_update_sinteger	The smallest `next_update_s` of the symbols.	seconds
levelsarray	The readings.
levels[].symstring	The symbol answered: SPX, ES, NQ, RTY or a ticker. A micro (MES, MNQ, M2K) answers as its future.
levels[].requestedstring	Present when the symbol asked differs from `sym` (`MES` answered as `ES`).
levels[].namestring	The symbol's name.
levels[].classstring	`index`, `future`, `etf` or `stock`.
levels[].contractstring	Futures: the contract the levels are moved to, e.g. `ESZ26`.
levels[].sessionopen \| closed \| stale	`open` while the book is current, `closed` outside market hours, `stale` when market hours are on but the book has not moved for a while.
levels[].daystring	The ET trading day of the reading, `YYYY-MM-DD`.
levels[].book"volume"	Always `volume`: every level is the volume book, the one the terminal draws.
levels[].pricenumber \| null	The price at the reading.	index points
levels[].price_as_ofstring	When that price was taken, ISO 8601 in New York time.
levels[].flipnumber \| null	Zero-gamma flip of the volume book. On a finished day, read at the levels minute (`levels_at`).	index points
levels[].call_wallnumber \| null	Call wall: the strike with the largest call gamma. On a finished day, read at the levels minute.	index points
levels[].put_wallnumber \| null	Put wall: the strike with the largest put gamma. On a finished day, read at the levels minute.	index points
levels[].net_gammaobject	Net dealer gamma of the book: its value, its sign and its unit, named on every answer.
levels[].net_gamma.valuenumber \| null	Net dealer gamma, in `unit`.
levels[].net_gamma.signpositive \| negative \| null	The sign of `value`.
levels[].net_gamma.unitusd_m_per_point \| usd_per_1pct	`usd_m_per_point` (millions of USD per index point: SPX, ES) or `usd_per_1pct` (USD per 1% move: tickers, NQ, RTY).
levels[].at_flipboolean	SPX and ES: the price is within 5 points of the flip, where the side is not a reliable reading.
levels[].dealer_gammalong \| short \| null	SPX and ES: the side of net gamma; null at the flip.
levels[].gamma_pctlnumber \| null	SPX and ES: the volume book's gamma at spot against the same minute of the last 20 sessions, a decile from -11 to +11. A measurement, with no measured forward edge.
levels[].as_ofstring	When the book was built, ISO 8601 in New York time.
levels[].as_of_unixinteger	The same instant, Unix seconds.
levels[].age_sinteger	Seconds since the book was built.	seconds
levels[].cadenceobject	How often the book and the price are rebuilt.
levels[].cadence.bookstring	`1s` (SPX, ES) or `5m` (tickers, NQ, RTY).
levels[].cadence.pricestring	`1s`.
levels[].gradestring \| null	Tickers, NQ, RTY: the chain's trust grade (A best). Null for SPX and ES.
levels[].flip_statusstring \| null	Tickers: whether the flip was found inside the strike grid.
levels[].oiobject \| null	The open-interest book's levels, the same fields; null when the symbol has none.
levels[].oi.flipnumber \| null	Zero-gamma flip of the open-interest book.	index points
levels[].oi.call_wallnumber \| null	Call wall of the open-interest book.	index points
levels[].oi.put_wallnumber \| null	Put wall of the open-interest book.	index points
levels[].oi.net_gammaobject	Net dealer gamma of the book: its value, its sign and its unit, named on every answer.
levels[].oi.flip_statusstring \| null	Tickers: whether the flip was found inside the strike grid (`ok`) or not.
levels[].basisobject	ES, NQ, RTY: the day's basis that moved the index levels.
levels[].basis.valuenumber \| null	Future minus index.	index points
levels[].basis.indexstring	The index the book is measured on: SPX, NDX or RUT.
levels[].basis.passesinteger	Basis passes measured so far today.
levels[].basis.rulestring	How the basis is made: the running median of the day's passes, rounded to the future's tick.
levels[].sourcestring	Futures: which index book and which basis.
levels[].levels_at15:45 \| 12:45	A finished day only: the levels minute (ET) `flip`, `call_wall` and `put_wall` were read at. Absent while the session runs.
levels[].last_secondobject	A finished day only: the replaced fields as the session's last second had them.
levels[].last_second.flipnumber \| null	Flip at the last second.	index points
levels[].last_second.call_wallnumber \| null	Call wall at the last second.	index points
levels[].last_second.put_wallnumber \| null	Put wall at the last second.	index points
levels[].last_second.at_flipboolean	At the flip, at the last second.
levels[].last_second.dealer_gammalong \| short \| null	The side, at the last second.
levels[].next_update_sinteger	When a new reading is worth asking for: 3 for SPX and ES, up to 300 for a five-minute book, 60 when the session is not open.	seconds
levels[].gammaobject	With `include=gamma`: the symbol's gamma by strike (the fields of `GET /api/v1/gamma`), or an `error`.
levels[].errorobject	This symbol failed; the others in the call still answer.
levels[].error.codestring	`unknown_symbol`, `no_data`, `no_basis` or `contract_not_live`.
levels[].error.messagestring	What happened, in words.
levels[].error.livearray	With `contract_not_live`: the contracts measured that day.

Errors

Status	Code	What to do
400	`missing_sym`, `too_many_symbols`, `bad_book`	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`	The account holds no LIVE plan. Start or renew LIVE; `pricing` names the page.
429	`rate_limited`, `too_many_places`	Over the minute's limit, or the key is in use from a fourth address this hour. Wait `Retry-After` seconds; poll with `If-None-Match`, a 304 is free.

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-11 A finished day answers with its closing levels, read at 15:45 ET; levels_at and last_second added.
2026-10-11 RTY and M2K.
2026-09-30 Added.

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

Request

curlPythonNode

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

import os, requests

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

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

Response

200304400401403

{
  "book": "volume",
  "next_update_s": 3,
  "levels": [
    {
      "sym": "ES",
      "name": "E-mini S&P 500",
      "class": "future",
      "contract": "ESZ26",
      "session": "open",
      "day": "2026-09-30",
      "book": "volume",
      "price": 6771.5,
      "price_as_of": "2026-09-30T10:15:03-04:00",
      "flip": 6752.25,
      "call_wall": 6800,
      "put_wall": 6700,
      "net_gamma": {
        "value": -812.4,
        "sign": "negative",
        "unit": "usd_m_per_point"
      },
      "at_flip": false,
      "dealer_gamma": "short",
      "gamma_pctl": -4,
      "as_of": "2026-09-30T10:15:03-04:00",
      "as_of_unix": 1790777703,
      "age_s": 1,
      "cadence": {
        "book": "1s",
        "price": "1s"
      },
      "grade": null,
      "oi": {
        "flip": 6731.4,
        "call_wall": 6825,
        "put_wall": 6700,
        "net_gamma": {
          "value": 1234.5,
          "sign": "positive",
          "unit": "usd_m_per_point"
        }
      },
      "basis": {
        "value": 59.5,
        "index": "SPX",
        "passes": 4,
        "rule": "running median of the day's basis passes up to that time, rounded to 0.25"
      },
      "source": "SPX volume book moved by the ES basis",
      "next_update_s": 3
    }
  ]
}

(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/levels.md.