cryptodataapi-com Volatility Regime API

openapi: 3.2.0
info:
  title: Crypto Data Volatility Regime API
  description: 'Real-time crypto market intelligence API. Built for AI agents: gasless USDC payments via x402 protocol, one-call onboarding, and 180+ endpoints for prices, derivatives, funding, and sentiment.'
  version: '2026-10-28'
servers:
- url: https://cryptodataapi.com
tags:
- name: Volatility Regime
  description: Per-asset realized-vol regime classifier, market-wide stress score, and per-symbol detail.
paths:
  /api/v1/volatility/regime:
    get:
      tags:
      - Volatility Regime
      summary: Get Volatility Regime
      description: 'Per-asset realized-volatility regime across the SIGNUM_RGG universe.


        Each asset is classified into one of ``vol_shock``, ``expanding``,

        ``compressed``, ``mean_reverting``, or ``normal`` from realized vol (close-to-

        close, Parkinson, Garman-Klass) on daily klines. Each entry carries 7d/30d

        vol, the 90d vol percentile, term structure (7d/30d), and a vol-target

        position-size multiplier (``target_vol / current_vol``, capped).


        **Backfillable** — replayable from daily klines (unlike the intraday-only

        liquidity regime). The ``vol.rv_1h`` field is live-only and lands null on

        historically backfilled days.


        **``vol_target_multiplier`` is ABSOLUTE**: ``60 / rv_gk_30`` (close-to-close

        fallback) clamped to ``[0.25, 3.0]`` — not a percentile of the coin''s own

        history. A coin with 30d vol >= 240% pins at 0.25 for as long as that holds

        (``vol.multiplier_at_floor``, ``vol.multiplier_floor_days``). For a

        **shock gate use ``vol.rv_z_7 >= 2``** (7d vol two sigmas above its own

        trailing 90d) or ``vol_pctile_7``; ``vol_shock`` itself is relative (7d GK

        at/above the 90th percentile of the coin''s own 90d).


        A coin needs ``MIN_BARS`` = 40 daily bars to be classified. Rows whose

        candle fetch failed this cycle are carried over from the previous build

        (``stale_cycles`` > 0, max 8 cycles) rather than vanishing.


        Example screens: `?regime=compressed&sort=days_compressed` (longest dry

        tinder), `?regime=vol_shock` (acute spikes), `?sort=vol_target_multiplier&

        order=desc` (assets a vol-targeter would size up).


        **Tiers:** Free is scoped to BTC only; Pro / Pro Plus return the full universe.'
      operationId: get_volatility_regime_api_v1_volatility_regime_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: source
        in: query
        required: false
        schema:
          title: Source
          enum:
          - binance_spot
          - hyperliquid_perp
          - null
          type:
          - string
          - 'null'
      - name: regime
        in: query
        required: false
        schema:
          description: Filter by volatility regime
          title: Regime
          enum:
          - vol_shock
          - expanding
          - compressed
          - mean_reverting
          - normal
          - null
          type:
          - string
          - 'null'
        description: Filter by volatility regime
      - name: sort
        in: query
        required: false
        schema:
          enum:
          - symbol
          - rv_gk_30
          - rv_gk_7
          - vol_pctile_30
          - term_structure_ratio
          - vol_target_multiplier
          - days_compressed
          type: string
          default: vol_pctile_30
          title: Sort
      - name: order
        in: query
        required: false
        schema:
          enum:
          - asc
          - desc
          type: string
          default: desc
          title: Order
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 250
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolatilityRegimeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/volatility/regime/score:
    get:
      tags:
      - Volatility Regime
      summary: Get Volatility Regime Score
      description: 'Market-wide volatility-stress composite (0-100) + sentiment + regime mix.


        Higher score = more market-wide volatility stress (size down). Sentiment

        bands: stressed (≥70), elevated (55-69), normal (45-54), calm (30-44),

        dormant (<30) — where ``dormant`` is the dangerously-quiet, compressed-vol

        state. Trimmed companion to ``/volatility/regime`` — no per-coin list.

        Its daily history is ``composite_score`` on ``/volatility/index/history``.'
      operationId: get_volatility_regime_score_api_v1_volatility_regime_score_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolatilityRegimeScoreResponse'
      security:
      - APIKeyHeader: []
  /api/v1/volatility/index:
    get:
      tags:
      - Volatility Regime
      summary: Get Volatility Index
      description: 'Crypto Volatility Index (CVI) — market-wide realized vol + BTC/ETH implied.


        The headline ``cvi_realized_30`` is the **volume-weighted 30d annualized

        realized vol (%)** across the universe (each coin weighted by its mean daily

        notional). ``composite_score`` is the 0-100 vol-stress breadth gauge.

        ``majors`` carries BTC & ETH realized vs Deribit implied vol (DVOL) and the

        **variance risk premium** (``vrp`` = implied − realized).


        **Tiers:** the market-wide CVI headline is available on every plan; the

        ``majors`` block is BTC-only on Free and adds ETH on Pro / Pro Plus.'
      operationId: get_volatility_index_api_v1_volatility_index_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolatilityIndexResponse'
      security:
      - APIKeyHeader: []
  /api/v1/volatility/implied:
    get:
      tags:
      - Volatility Regime
      summary: Get Implied Vol
      description: 'BTC/ETH implied vol (Deribit DVOL) + variance risk premium.


        Current DVOL, 24h change, realized comparison and VRP: **BTC-only on Free**,

        BTC + ETH on Pro / Pro Plus. The full DVOL history series + the ATM implied-vol

        term structure are **Pro Plus** only (``detail: true``).'
      operationId: get_implied_vol_api_v1_volatility_implied_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImpliedVolResponse'
      security:
      - APIKeyHeader: []
  /api/v1/volatility/index/history:
    get:
      tags:
      - Volatility Regime
      summary: Get Volatility Index History
      description: 'Daily CVI + vol-stress history, up to a year (**Pro Plus**).


        One point per UTC day in ``[today - days, today]``. From 2026-08-24 values

        come from each day''s live archived snapshot. Earlier days are reconstructed

        from daily klines with the live formula and carry ``backfilled: true`` — CVI

        was only archived from 2026-07-23, and until 2026-08-24 the live universe

        still counted delisted exchange pairs with frozen prices, which roughly

        doubled the published index. Reconstructed days use today''s coin universe.

        Today appears once the 20:00 UTC snapshot is built. ``composite_score`` is

        the number ``/volatility/regime/score`` serves live, captured once a day.'
      operationId: get_volatility_index_history_api_v1_volatility_index_history_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 90
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolatilityIndexHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/volatility/regime/{symbol}:
    get:
      tags:
      - Volatility Regime
      summary: Get Volatility Regime Symbol
      description: 'Per-asset Volatility regime detail with 60d daily history.


        Coin scope follows the plan: **Free = BTC only**, Pro / Pro Plus = any coin.

        The 60d ``history`` series is **Pro Plus** only (empty on Free / Pro).


        Hyperliquid thousand-unit tickers (``kBONK``, ``kPEPE``, ``kSHIB``) are

        accepted as aliases of the plain symbol.'
      operationId: get_volatility_regime_symbol_api_v1_volatility_regime__symbol__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: symbol
        in: path
        required: true
        schema:
          type: string
          title: Symbol
        example: BTC
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolatilityRegimeDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/volatility/regime/refresh:
    post:
      tags:
      - Volatility Regime
      summary: Refresh Volatility Regime
      description: Force recompute the Volatility regime cache (Pro+).
      operationId: refresh_volatility_regime_api_v1_volatility_regime_refresh_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolatilityRegimeRefreshResponse'
      security:
      - APIKeyHeader: []
components:
  schemas:
    VolatilityRegimeResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/VolatilityRegimeItem'
          type: array
          title: Items
        count:
          type: integer
          title: Count
        universe_size:
          type: integer
          title: Universe Size
        timestamp:
          type: string
          title: Timestamp
      type: object
      required:
      - items
      - count
      - universe_size
      - timestamp
      title: VolatilityRegimeResponse
    ImpliedVolEntry:
      properties:
        symbol:
          type: string
          title: Symbol
        dvol:
          title: Dvol
          type:
          - number
          - 'null'
        dvol_change_24h:
          title: Dvol Change 24H
          type:
          - number
          - 'null'
        realized_30:
          title: Realized 30
          type:
          - number
          - 'null'
        vrp:
          title: Vrp
          type:
          - number
          - 'null'
        history:
          items:
            $ref: '#/components/schemas/DvolHistoryPoint'
          type: array
          title: History
          default: []
        term_structure:
          items:
            $ref: '#/components/schemas/TermStructurePoint'
          type: array
          title: Term Structure
          default: []
      type: object
      required:
      - symbol
      title: ImpliedVolEntry
    VolatilityRegimeRefreshResponse:
      properties:
        refreshed:
          type: boolean
          title: Refreshed
        count:
          type: integer
          title: Count
        timestamp:
          type: string
          title: Timestamp
      type: object
      required:
      - refreshed
      - count
      - timestamp
      title: VolatilityRegimeRefreshResponse
    ImpliedVolResponse:
      properties:
        as_of:
          type: string
          title: As Of
        detail:
          type: boolean
          title: Detail
          description: True when history + term_structure are populated (Pro+)
          default: false
        items:
          items:
            $ref: '#/components/schemas/ImpliedVolEntry'
          type: array
          title: Items
          default: []
      type: object
      required:
      - as_of
      title: ImpliedVolResponse
      description: 'BTC/ETH implied vol (Deribit DVOL) + variance risk premium. Current DVOL +

        VRP open to any key; full DVOL history + ATM term structure gated to Pro+.'
    TermStructurePoint:
      properties:
        expiry:
          type: string
          title: Expiry
        expiry_days:
          type: integer
          title: Expiry Days
        atm_iv:
          type: number
          title: Atm Iv
      type: object
      required:
      - expiry
      - expiry_days
      - atm_iv
      title: TermStructurePoint
    MajorVolEntry:
      properties:
        symbol:
          type: string
          title: Symbol
        realized_30:
          title: Realized 30
          description: 30d annualized realized vol (%)
          type:
          - number
          - 'null'
        implied_dvol:
          title: Implied Dvol
          description: Deribit DVOL — 30d implied vol (%)
          type:
          - number
          - 'null'
        vrp:
          title: Vrp
          description: Variance risk premium = implied − realized (vol points)
          type:
          - number
          - 'null'
        implied_change_24h:
          title: Implied Change 24H
          type:
          - number
          - 'null'
      type: object
      required:
      - symbol
      title: MajorVolEntry
      description: Per-major realized-vs-implied comparison (options-liquid coins only).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VolatilityIndexResponse:
      properties:
        as_of:
          type: string
          title: As Of
        cvi_realized_30:
          title: Cvi Realized 30
          description: 'Headline CVI: volume-weighted 30d realized vol (%)'
          type:
          - number
          - 'null'
        cvi_realized_7:
          title: Cvi Realized 7
          type:
          - number
          - 'null'
        composite_score:
          type: number
          title: Composite Score
          description: 0-100 vol-stress breadth gauge (higher = more stress)
          default: 50.0
        sentiment:
          type: string
          title: Sentiment
          default: normal
        gross_exposure_multiplier:
          type: number
          title: Gross Exposure Multiplier
          default: 1.0
        median_vol_pctile_30:
          title: Median Vol Pctile 30
          type:
          - number
          - 'null'
        universe_size:
          type: integer
          title: Universe Size
          default: 0
        regime_mix:
          additionalProperties: true
          type: object
          title: Regime Mix
          description: Regime pct shares across the universe
        majors:
          items:
            $ref: '#/components/schemas/MajorVolEntry'
          type: array
          title: Majors
          default: []
      type: object
      required:
      - as_of
      title: VolatilityIndexResponse
      description: 'The Crypto Volatility Index headline: market-wide realized CVI + regime

        breadth + BTC/ETH realized-vs-implied. Open to any valid key.'
    VolatilityIndexHistoryResponse:
      properties:
        points:
          items:
            $ref: '#/components/schemas/VolatilityIndexHistoryPoint'
          type: array
          title: Points
          default: []
        count:
          type: integer
          title: Count
          default: 0
      type: object
      title: VolatilityIndexHistoryResponse
      description: Daily CVI + vol-stress history, up to 365 days (Pro+).
    VolMetricsModel:
      properties:
        rv_cc_7:
          title: Rv Cc 7
          type:
          - number
          - 'null'
        rv_cc_30:
          title: Rv Cc 30
          type:
          - number
          - 'null'
        rv_parkinson_30:
          title: Rv Parkinson 30
          type:
          - number
          - 'null'
        rv_gk_7:
          title: Rv Gk 7
          type:
          - number
          - 'null'
        rv_gk_30:
          title: Rv Gk 30
          type:
          - number
          - 'null'
        rv_1h:
          title: Rv 1H
          type:
          - number
          - 'null'
        vol_pctile_30:
          title: Vol Pctile 30
          type:
          - number
          - 'null'
        vol_pctile_7:
          title: Vol Pctile 7
          type:
          - number
          - 'null'
        rv_z_30:
          title: Rv Z 30
          type:
          - number
          - 'null'
        rv_z_7:
          title: Rv Z 7
          type:
          - number
          - 'null'
        term_structure_ratio:
          title: Term Structure Ratio
          type:
          - number
          - 'null'
        vol_target_multiplier:
          title: Vol Target Multiplier
          type:
          - number
          - 'null'
        days_compressed:
          type: integer
          title: Days Compressed
          default: 0
        days_shock:
          type: integer
          title: Days Shock
          default: 0
        days_in_regime:
          type: integer
          title: Days In Regime
          default: 0
        prev_regime:
          title: Prev Regime
          type:
          - string
          - 'null'
          enum:
          - vol_shock
          - expanding
          - compressed
          - mean_reverting
          - normal
          - null
        regime_changed:
          type: boolean
          title: Regime Changed
          default: false
        notional_30:
          title: Notional 30
          type:
          - number
          - 'null'
        multiplier_at_floor:
          type: boolean
          title: Multiplier At Floor
          description: True when vol_target_multiplier is pinned at its 0.25 floor (30d realized vol >= 240%). The multiplier is absolute (60 / rv), not a percentile.
          default: false
        multiplier_floor_days:
          type: integer
          title: Multiplier Floor Days
          description: Consecutive latest daily bars the multiplier has sat at the floor (0 when not at the floor)
          default: 0
      type: object
      title: VolMetricsModel
    VolatilityRegimeDetailResponse:
      properties:
        symbol:
          type: string
          title: Symbol
        source:
          type: string
          enum:
          - binance_spot
          - hyperliquid_perp
          title: Source
        price:
          type: number
          title: Price
        regime:
          type: string
          enum:
          - vol_shock
          - expanding
          - compressed
          - mean_reverting
          - normal
          title: Regime
        is_stable:
          type: boolean
          title: Is Stable
          default: false
        vol:
          $ref: '#/components/schemas/VolMetricsModel'
        stale_cycles:
          type: integer
          title: Stale Cycles
          description: Consecutive 30-min rebuild cycles this row was carried over from the previous build because its candle fetch failed (0 = computed this cycle)
          default: 0
        history:
          items:
            $ref: '#/components/schemas/VolatilityHistoryEntry'
          type: array
          title: History
          default: []
        timestamp:
          type: string
          title: Timestamp
      type: object
      required:
      - symbol
      - source
      - price
      - regime
      - vol
      - timestamp
      title: VolatilityRegimeDetailResponse
    DvolHistoryPoint:
      properties:
        date:
          type: string
          title: Date
        dvol:
          type: number
          title: Dvol
      type: object
      required:
      - date
      - dvol
      title: DvolHistoryPoint
    VolatilityRegimeItem:
      properties:
        symbol:
          type: string
          title: Symbol
        source:
          type: string
          enum:
          - binance_spot
          - hyperliquid_perp
          title: Source
        price:
          type: number
          title: Price
        regime:
          type: string
          enum:
          - vol_shock
          - expanding
          - compressed
          - mean_reverting
          - normal
          title: Regime
        is_stable:
          type: boolean
          title: Is Stable
          default: false
        vol:
          $ref: '#/components/schemas/VolMetricsModel'
        stale_cycles:
          type: integer
          title: Stale Cycles
          description: Consecutive 30-min rebuild cycles this row was carried over from the previous build because its candle fetch failed (0 = computed this cycle)
          default: 0
      type: object
      required:
      - symbol
      - source
      - price
      - regime
      - vol
      title: VolatilityRegimeItem
    VolatilityHistoryEntry:
      properties:
        date:
          type: string
          title: Date
        close:
          type: number
          title: Close
        rv_cc_30:
          title: Rv Cc 30
          type:
          - number
          - 'null'
        rv_gk_30:
          title: Rv Gk 30
          type:
          - number
          - 'null'
      type: object
      required:
      - date
      - close
      title: VolatilityHistoryEntry
    VolatilityIndexHistoryPoint:
      properties:
        date:
          type: string
          title: Date
        cvi_realized_30:
          title: Cvi Realized 30
          type:
          - number
          - 'null'
        cvi_realized_7:
          title: Cvi Realized 7
          type:
          - number
          - 'null'
        composite_score:
          title: Composite Score
          type:
          - number
          - 'null'
        sentiment:
          title: Sentiment
          type:
          - string
          - 'null'
        backfilled:
          type: boolean
          title: Backfilled
          description: True when any value was reconstructed from daily klines rather than taken from a verified live capture — every point before 2026-08-24.
          default: false
      type: object
      required:
      - date
      title: VolatilityIndexHistoryPoint
    VolatilityRegimeScoreResponse:
      properties:
        as_of:
          type: string
          title: As Of
        composite_score:
          type: number
          title: Composite Score
        sentiment:
          type: string
          title: Sentiment
        target_vol:
          type: number
          title: Target Vol
          default: 60.0
        gross_exposure_multiplier:
          type: number
          title: Gross Exposure Multiplier
          default: 1.0
        median_vol_pctile_30:
          title: Median Vol Pctile 30
          type:
          - number
          - 'null'
        aggregate:
          additionalProperties: true
          type: object
          title: Aggregate
          description: Regime counts + pct shares across the tracked universe
      type: object
      required:
      - as_of
      - composite_score
      - sentiment
      title: VolatilityRegimeScoreResponse
      description: Trimmed composite-only companion to /volatility/regime.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key