GammaFlip.io History API

openapi: 3.2.0
info:
  title: GammaFlip GEX History API
  version: 1.0.0
  description: 'Programmatic access to Gamma Exposure (GEX) data for crypto options

    (Bybit, Deribit, OKX, Derive, Binance) 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: []
tags:
- name: History
paths:
  /history/levels/{exchange}/{coin}:
    get:
      operationId: getHistoryLevels
      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.'
      tags:
      - History
      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'
  /history/timestamps/{exchange}/{coin}:
    get:
      operationId: getHistoryTimestamps
      summary: Capture timestamps of a session date
      description: 'The capture times (ISO 8601 UTC) of one session date, oldest first. The session date

        is the UTC date for crypto and the New York trading date for TradFi. Counts as 1 request.'
      tags:
      - History
      parameters:
      - $ref: '#/components/parameters/HistoryExchange'
      - $ref: '#/components/parameters/Coin'
      - name: date
        in: query
        required: true
        description: Session date, `YYYY-MM-DD`.
        schema:
          type: string
          format: date
          example: '2026-10-05'
      responses:
        '200':
          description: Capture timestamps
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      type: string
                      format: date-time
                  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'
  /history/snapshot/{exchange}/{coin}:
    get:
      operationId: getHistorySnapshot
      summary: Per-strike snapshot at a past moment
      description: 'The stored snapshot nearest to `at` (within 15 minutes): snapshot-level fields and

        the strikes within +/- 25% of spot. When nothing is that close the answer is

        `404 no_snapshot` with `nearest_timestamps` from the `TOTAL` captures. Counts as 1 request.'
      tags:
      - History
      parameters:
      - $ref: '#/components/parameters/HistoryExchange'
      - $ref: '#/components/parameters/Coin'
      - name: at
        in: query
        required: true
        description: ISO datetime (UTC).
        schema:
          type: string
          example: '2026-10-05T19:50:00Z'
      - name: expiration
        in: query
        required: false
        description: '`TOTAL` (default) or an ISO expiration date `YYYY-MM-DD`.'
        schema:
          type: string
          default: TOTAL
          example: TOTAL
      responses:
        '200':
          description: Snapshot
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/HistorySnapshot'
                  meta:
                    $ref: '#/components/schemas/HistoryMeta'
        '400':
          $ref: '#/components/responses/HistoryNotAvailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No capture within 15 minutes of `at` (`no_snapshot`, with `nearest_timestamps`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
  /history/coverage:
    get:
      operationId: getHistoryCoverage
      summary: What history exists
      description: 'Per exchange and symbol: first and last capture, number of sessions and the date range

        of the daily files. **Free**: not counted against the quota. Cached for up to an hour.'
      tags:
      - History
      responses:
        '200':
          description: Coverage
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HistoryCoverageRow'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /history/files/{exchange}/{coin}:
    get:
      operationId: listHistoryFiles
      summary: List daily history files
      description: 'The manifest of daily CSV.gz files, newest first, at most 400 rows. Counts as 1 request.

        Download a file with `/history/files/{exchange}/{coin}/{date}/{file}`.'
      tags:
      - History
      parameters:
      - $ref: '#/components/parameters/HistoryExchange'
      - $ref: '#/components/parameters/Coin'
      - name: start
        in: query
        required: false
        description: First session date, `YYYY-MM-DD`, inclusive.
        schema:
          type: string
          format: date
      - name: end
        in: query
        required: false
        description: Last session date, `YYYY-MM-DD`, exclusive.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: File manifest
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/HistoryFileEntry'
                  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'
  /history/files/{exchange}/{coin}/{date}/{file}:
    get:
      operationId: downloadHistoryFile
      summary: Download a daily history file
      description: 'Answers `302` with a presigned link, valid for up to 15 minutes, to a gzip-compressed

        CSV (`application/gzip`, downloaded as `_.csv.gz`). Costs one **file credit**

        from the separate `history_files` daily bucket, not a request. A 400, 404 or 503 costs

        nothing. Follow the redirect without your `X-API-Key` header. Column layouts:

        https://docs.gammaflip.io/data-dictionary#daily-history-files'
      tags:
      - History
      parameters:
      - $ref: '#/components/parameters/HistoryExchange'
      - $ref: '#/components/parameters/Coin'
      - name: date
        in: path
        required: true
        description: Session date, `YYYY-MM-DD`.
        schema:
          type: string
          format: date
          example: '2026-10-05'
      - name: file
        in: path
        required: true
        schema:
          type: string
          enum:
          - levels
          - strikes_total
          - strikes_by_expiry
      responses:
        '302':
          description: Redirect to the presigned file link.
          headers:
            Location:
              description: Presigned link, valid for up to 15 minutes.
              schema:
                type: string
                format: uri
            X-History-Files-Limit:
              description: Daily file credits; `0` means unlimited. Omitted if the quota service is unavailable.
              schema:
                type: integer
            X-History-Files-Remaining:
              description: Credits left; `0` together with a `0` limit means unlimited. Omitted if the quota service is unavailable.
              schema:
                type: integer
            X-History-Files-Reset:
              schema:
                type: string
                format: date-time
        '400':
          $ref: '#/components/responses/HistoryNotAvailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No such file (`no_file`). Costs no credit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Daily file credits used up (`history_files_limit_exceeded`). No `Retry-After`

            header: use `X-History-Files-Reset` or `GET /me`.

            '
          headers:
            X-History-Files-Limit:
              description: Daily file credits (`0` means unlimited, which never yields a 429).
              schema:
                type: integer
            X-History-Files-Remaining:
              schema:
                type: integer
                example: 0
            X-History-Files-Reset:
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: File storage temporarily unavailable (`files_unavailable`). Costs no credit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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'
    HistoryStrike:
      type: object
      properties:
        strike:
          type: number
          example: 760
        call_gex:
          type:
          - number
          - 'null'
          description: Non-negative.
        put_gex:
          type:
          - number
          - 'null'
          description: Non-negative.
        net_gex:
          type:
          - number
          - 'null'
          description: '`call_gex - put_gex`.'
        call_oi:
          type:
          - number
          - 'null'
          description: Open interest in contracts.
        put_oi:
          type:
          - number
          - 'null'
    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%).
    HistoryCoverageRow:
      type: object
      properties:
        exchange:
          type: string
          example: tradfi
        symbol:
          type: string
          example: QQQ
        first_ts:
          type: string
          format: date-time
          example: '2026-05-04T13:30:00Z'
        last_ts:
          type: string
          format: date-time
          example: '2026-10-06T09:45:00Z'
        sessions:
          type: integer
          example: 109
        files_first_date:
          type:
          - string
          - 'null'
          format: date
          example: '2026-05-04'
        files_last_date:
          type:
          - string
          - 'null'
          format: date
          example: '2026-10-05'
    HistorySnapshot:
      description: 'A stored snapshot: the snapshot-level fields (as `HistoryLevelsRow`, plus

        `expiration` and `dte`) and the strikes within +/- 25% of spot.

        '
      allOf:
      - $ref: '#/components/schemas/HistoryLevelsRow'
      - type: object
        properties:
          expiration:
            type: string
            description: '`TOTAL` or an ISO date.'
            example: TOTAL
          dte:
            type:
            - number
            - 'null'
            description: Calendar days to expiration; `null` for `TOTAL`.
          strikes:
            type: array
            items:
              $ref: '#/components/schemas/HistoryStrike'
    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'
    HistoryFileEntry:
      type: object
      properties:
        session_date:
          type: string
          format: date
          example: '2026-10-05'
        file:
          type: string
          enum:
          - levels
          - strikes_total
          - strikes_by_expiry
        rows:
          type: integer
          example: 2700
        bytes:
          type: integer
          description: Size of the gzip file.
          example: 148112
        sha256:
          type: string
          description: SHA-256 of the gzip file.
        schema_version:
          type: integer
          example: 1
    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
          - binance
          - 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'
    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'
    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'
    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'
  parameters:
    HistoryExchange:
      name: exchange
      in: path
      required: true
      description: '`bybit`, `deribit`, `okx`, `derive`, `binance`, `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
  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).

        '