> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gammaflip.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Levels time series

> The `TOTAL` levels over a time window, oldest first: one row per capture (`15m`),
per UTC hour (`1h`) or per session (`close`). `start` is inclusive, `end` exclusive.
A response has at most 5,000 rows plus an opaque `meta.next_cursor`. Counts as 1 request.
See https://docs.gammaflip.io/history for session dates, the close definition and
point-in-time semantics.




## OpenAPI

````yaml /openapi.yaml get /history/levels/{exchange}/{coin}
openapi: 3.1.0
info:
  title: GammaFlip GEX API
  version: 1.0.0
  description: >
    Programmatic access to Gamma Exposure (GEX) data for crypto options

    (Bybit, Deribit, OKX, Derive) and US options (the `tradfi` exchange).


    API access is a plan entitlement (`api_access`). The trial includes it

    (50 requests/day); other plans with API access get 500 requests/day.

    Only `/gex/...`, `/levels/...` and the `/history/...` query endpoints count

    against the quota; `/exchanges`, `/coins`, `/expirations/...`, `/me` and

    `/history/coverage` are free. History file downloads use a separate daily

    bucket of file credits (trial 20, other plans 200). A `429` carries no

    `Retry-After` header: use `X-RateLimit-Reset`, `X-History-Files-Reset` or
    `/me`.


    All GEX values are USD per 1% move of the underlying. Field definitions:

    https://docs.gammaflip.io/data-dictionary
  contact:
    name: GammaFlip Support
    email: admin@gammaflip.io
    url: https://gammaflip.io
servers:
  - url: https://api.gammaflip.io/api/v1
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /history/levels/{exchange}/{coin}:
    get:
      tags:
        - History
      summary: Levels time series
      description: >
        The `TOTAL` levels over a time window, oldest first: one row per capture
        (`15m`),

        per UTC hour (`1h`) or per session (`close`). `start` is inclusive,
        `end` exclusive.

        A response has at most 5,000 rows plus an opaque `meta.next_cursor`.
        Counts as 1 request.

        See https://docs.gammaflip.io/history for session dates, the close
        definition and

        point-in-time semantics.
      operationId: getHistoryLevels
      parameters:
        - $ref: '#/components/parameters/HistoryExchange'
        - $ref: '#/components/parameters/Coin'
        - name: start
          in: query
          required: false
          description: >-
            ISO date or datetime (UTC), inclusive. Default `end` minus 30 days.
            Years 2020 to 2100.
          schema:
            type: string
            example: '2026-09-01'
        - name: end
          in: query
          required: false
          description: >-
            ISO date or datetime (UTC), exclusive. Default now, floored to the
            15-minute capture grid.
          schema:
            type: string
            example: '2026-10-01'
        - name: granularity
          in: query
          required: false
          description: >
            `15m` (every capture, window up to 31 days), `1h` (last capture of
            each UTC hour,

            up to 180 days) or `close` (last capture of each session,
            unlimited).
          schema:
            type: string
            enum:
              - 15m
              - 1h
              - close
            default: close
        - name: cursor
          in: query
          required: false
          description: >-
            The `meta.next_cursor` of the previous page. Repeat the other
            parameters.
          schema:
            type: string
      responses:
        '200':
          description: Levels rows
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HistoryLevelsRow'
                  meta:
                    $ref: '#/components/schemas/HistoryMeta'
        '400':
          $ref: '#/components/responses/HistoryNotAvailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    HistoryExchange:
      name: exchange
      in: path
      required: true
      description: >
        `bybit`, `deribit`, `okx`, `derive`, `combined` or `tradfi`. `all` and
        `combined`

        with a TradFi ticker resolve to `tradfi`. Venue subsets such as
        `deribit+derive`

        have no history: `400 history_not_available`.
      schema:
        type: string
        examples:
          - deribit
          - combined
          - tradfi
    Coin:
      name: coin
      in: path
      required: true
      description: >-
        Symbol (case-insensitive), for example `BTC` or `QQQ`. Use `/coins` for
        the list.
      schema:
        type: string
        example: BTC
  schemas:
    HistoryLevelsRow:
      type: object
      description: >
        One stored `TOTAL` snapshot. `type` is `close` only for the last capture
        of a

        completed session. `oi_date` is the session whose open interest the row
        used.

        The levels fields follow the `Levels` schema (`max_pain` is `null` for
        `TOTAL`, so always `null` in the levels series;

        a single-expiration snapshot may set it).
      allOf:
        - type: object
          properties:
            schema_version:
              type: integer
              example: 1
            timestamp_utc:
              type: string
              format: date-time
              example: '2026-10-05T20:15:00Z'
            session_date:
              type: string
              format: date
              description: UTC date (crypto) or New York trading date (TradFi).
              example: '2026-10-05'
            type:
              type: string
              enum:
                - intraday
                - close
            exchange:
              type: string
              example: tradfi
            symbol:
              type: string
              example: QQQ
            oi_date:
              type:
                - string
                - 'null'
              format: date
              description: Session whose open interest was used.
              example: '2026-10-02'
        - $ref: '#/components/schemas/Levels'
    HistoryMeta:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        exchange:
          type: string
          description: As requested (lowercased).
          example: tradfi
        coin:
          type: string
          example: QQQ
        symbol:
          type: string
          example: QQQ
        exchange_resolved:
          type: string
          example: tradfi
        market:
          type: string
          enum:
            - crypto
            - tradfi
        units:
          type: string
          example: USD per 1% move of the underlying
        docs_url:
          type: string
          example: https://docs.gammaflip.io/data-dictionary
        granularity:
          type: string
          enum:
            - 15m
            - 1h
            - close
          description: '`/history/levels` only.'
        start:
          type: string
          format: date-time
          description: '`/history/levels` only: the window start as applied.'
        end:
          type: string
          format: date-time
          description: '`/history/levels` only: the window end (exclusive) as applied.'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            `/history/levels` only: pass as `cursor` for the next page; `null`
            on the last page.
        session_date:
          type: string
          format: date
          description: '`/history/timestamps` only.'
        snapshot_at:
          type: string
          format: date-time
          description: '`/history/snapshot` only: the capture returned.'
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    Levels:
      type: object
      description: >
        The levels of one GEX snapshot. GEX values are USD per 1% move of the

        underlying; `call_gex` and `put_gex` are non-negative, `net_gex =
        call_gex - put_gex`.

        Missing values are `null`. See the data dictionary.
      properties:
        spot:
          type:
            - number
            - 'null'
          description: Underlying price at capture.
        flip:
          type:
            - number
            - 'null'
          description: >-
            Primary gamma-flip price (`flip_points[0]`), the net-gamma sign
            change nearest to spot.
        flip_count:
          type: integer
          description: Number of zero crossings in the profile.
        regime:
          type:
            - string
            - 'null'
          enum:
            - positive
            - negative
            - null
          description: '`positive` if `spot >= flip`.'
        net_gex:
          type:
            - number
            - 'null'
          description: Sum of call_gex minus sum of put_gex.
        abs_gex:
          type:
            - number
            - 'null'
          description: Sum of call_gex plus sum of put_gex.
        call_gex:
          type:
            - number
            - 'null'
        put_gex:
          type:
            - number
            - 'null'
        call_oi_total:
          type:
            - number
            - 'null'
          description: Sum of call open interest in contracts.
        put_oi_total:
          type:
            - number
            - 'null'
          description: Sum of put open interest in contracts.
        p1_strike:
          type:
            - number
            - 'null'
          description: Strike with the largest positive net GEX.
        p1_gex:
          type:
            - number
            - 'null'
        p2_strike:
          type:
            - number
            - 'null'
        p2_gex:
          type:
            - number
            - 'null'
        n1_strike:
          type:
            - number
            - 'null'
          description: Strike with the most negative net GEX.
        n1_gex:
          type:
            - number
            - 'null'
        n2_strike:
          type:
            - number
            - 'null'
        n2_gex:
          type:
            - number
            - 'null'
        a1_strike:
          type:
            - number
            - 'null'
          description: Strike with the largest absolute GEX (call + put).
        a1_gex:
          type:
            - number
            - 'null'
        a2_strike:
          type:
            - number
            - 'null'
        a2_gex:
          type:
            - number
            - 'null'
        s_price:
          type:
            - number
            - 'null'
          description: Max-stability level, the peak of the net-gamma profile (a price).
        s_gex:
          type:
            - number
            - 'null'
        v_price:
          type:
            - number
            - 'null'
          description: Max-volatility level, the trough of the net-gamma profile (a price).
        v_gex:
          type:
            - number
            - 'null'
        max_pain:
          type:
            - number
            - 'null'
          description: Per-expiration max-pain strike; `null` for TOTAL.
        atm_iv:
          type:
            - number
            - 'null'
          description: ATM implied volatility as a decimal (0.18 = 18%).
    RateLimit:
      type: object
      properties:
        limit:
          type: integer
          example: 500
        remaining:
          type: integer
          example: 487
        reset:
          type: string
          format: date-time
          example: '2026-04-15T00:00:00+00:00'
    Error:
      type: object
      description: >
        Standard error body. `error` is a stable slug safe to branch on;
        `message` is human-readable prose that may change and must not be
        parsed. Errors are never wrapped in the data/meta envelope used by
        successful responses. Some errors add hint fields.
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - unauthorized
            - subscription_required
            - market_not_in_plan
            - rate_limit_exceeded
            - invalid_exchange
            - invalid_pair
            - invalid_expiration
            - invalid_param
            - no_data
            - unsupported_coin
            - market_unavailable
            - history_not_available
            - range_too_large
            - no_snapshot
            - no_file
            - files_unavailable
            - history_files_limit_exceeded
            - method_not_allowed
          example: invalid_exchange
        message:
          type: string
          example: Exchange 'kraken' is not available.
        current_tier:
          type: string
          description: With `subscription_required` and `market_not_in_plan`.
          example: trial
        valid_exchanges:
          type: array
          items:
            type: string
          description: With `invalid_exchange`, `invalid_pair` and `history_not_available`.
          example:
            - deribit
            - bybit
            - okx
            - derive
            - combined
        nearest_expirations:
          type: array
          items:
            type: string
          description: >-
            With `invalid_expiration`; up to five ISO dates closest to the
            request (the earliest five if the value is not a date).
          example:
            - '2026-10-17'
            - '2026-10-19'
        valid_values:
          type: array
          items:
            type: string
          description: >-
            With `invalid_param` for `view`, `granularity`, `file` and
            `compare`.
          example:
            - full
            - levels
        max_value:
          type: number
          description: With `invalid_param` for `range_pct`.
          example: 50
        max_window_days:
          type: integer
          description: With `range_too_large`.
          example: 31
        nearest_timestamps:
          type: array
          items:
            type: string
            format: date-time
          description: With `no_snapshot`; up to three capture times closest to `at`.
          example:
            - '2026-10-05T20:15:00Z'
            - '2026-10-05T13:45:00Z'
        market:
          type: string
          description: With `market_not_in_plan`; the market the requested coin belongs to.
          enum:
            - crypto
            - tradfi
          example: tradfi
        markets_in_plan:
          type: array
          items:
            type: string
          description: With `market_not_in_plan`.
        supported_crypto:
          type: array
          items:
            type: string
          description: >-
            With `unsupported_coin`; crypto coins listed by at least one
            exchange.
          example:
            - BTC
            - ETH
            - HYPE
            - SOL
            - XRP
        supported_tradfi:
          type: array
          items:
            type: string
          description: With `unsupported_coin`; US tickers we track.
          example:
            - QQQ
            - SPX
            - SPY
        rate_limit:
          allOf:
            - $ref: '#/components/schemas/RateLimit'
          description: >-
            With `rate_limit_exceeded` and `history_files_limit_exceeded`;
            mirrors the X-RateLimit-* headers.
  responses:
    HistoryNotAvailable:
      description: >
        `invalid_exchange`, `invalid_pair`, `invalid_param`,
        `history_not_available`

        (venue subset; with `valid_exchanges`) or `range_too_large` (with
        `max_window_days`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: >
        Missing or invalid credential, or a credential that does not resolve to
        a user. Both return `unauthorized`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >
        `subscription_required` (the plan has no API access) or
        `market_not_in_plan`

        (the plan does not include the coin's market).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: |
        Daily rate limit exceeded. No `Retry-After` header is sent: use
        `X-RateLimit-Reset` or `GET /me`.
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
            example: 0
        X-RateLimit-Reset:
          schema:
            type: string
            format: date-time
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key prefixed with `gex_sk_`. Create one in your
        [account dashboard](https://gammaflip.io/account).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.