firmtape-com Levels API

openapi: 3.2.0
info:
  title: FirmTape public Levels API
  version: 1.0.0
  description: 'Every public FirmTape operation: the levels API (LIVE), the Orders and POSITIONS APIs (ORDERS), the LAB API, the archive JSON (REPLAY), the dataset files and the Geo API. Measurements of dealer positioning and public records, never trading signals. Docs: https://firmtape.com/docs/developers'
servers:
- url: https://firmtape.com
tags:
- name: Levels
paths:
  /api/v1/levels:
    get:
      x-plan: live
      x-key: live
      x-limit: 120 a minute per key; a 304 is free
      operationId: getLevels
      x-slug: levels
      summary: Get levels
      description: '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`. Each symbol also carries the day''s levels of interest under `levels_of_interest`: the strikes ranked C1.. and P1.. that the terminal''s chart draws, and its session levels under `session_levels`: the prior day, the prior week, the month so far and the opening range.'
      x-features:
      - levels-api
      - walls-and-levels
      - futures-views
      - integrations
      x-since: '2026-09-30'
      x-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-10-27'
        - Each answer carries the day's levels of interest, `levels_of_interest`, and its session levels, `session_levels`.
      parameters:
      - name: sym
        in: query
        required: true
        description: '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.'
        schema:
          type: string
        x-error: missing_sym, too_many_symbols
      - name: include
        in: query
        required: false
        description: '`gamma` adds each symbol''s gamma by strike: one request per chart.'
        schema:
          type: string
          enum:
          - gamma
      - name: book
        in: query
        required: false
        description: 'With `include=gamma`: which book''s strikes.'
        schema:
          type: string
          enum:
          - vol
          - oi
          default: vol
        x-error: bad_book
      - name: contract
        in: query
        required: false
        description: 'Futures: a dated contract in the two weeks before a roll, e.g. `ESH27`. The levels move by that contract''s own basis.'
        schema:
          type: string
        x-default: the front quarterly
        x-error: contract_not_live
      - name: errors
        in: query
        required: false
        description: '`200`: an error answers 200 with the same body and the real status in `X-FirmTape-Status`, for clients that cannot read a status.'
        schema:
          type: string
          enum:
          - '200'
      - name: key
        in: query
        required: false
        description: 'Legacy: the key in the address, for platforms that cannot send headers. Prefer the header.'
        schema:
          type: string
      responses:
        '200':
          description: One entry per symbol asked, in order. A symbol that fails carries its own `error`; the rest still answer.
          headers:
            X-RateLimit-Limit: '120'
            X-RateLimit-Remaining: '117'
          content:
            application/json:
              schema:
                type: object
                required:
                - book
                - next_update_s
                - levels
                properties:
                  book:
                    type: string
                    description: Always `volume`.
                    const: volume
                  next_update_s:
                    type: integer
                    description: The smallest `next_update_s` of the symbols.
                    x-unit: seconds
                  levels:
                    type: array
                    items:
                      $ref: '#/components/schemas/LiveLevel'
                    description: The readings.
      tags:
      - Levels
components:
  schemas:
    LiveLevel:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true