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

# Realised volatility

> Annualised realised volatility of the underlying index over a rolling lookback. `lookback_days=30` is 30-day realised vol, directly comparable with 1m implied vol. Values are decimal.

**History window.** How far back you can read depends on your billing plan: 1 month on monthly billing, 1 year on quarterly, 3 years on annual. A `start` earlier than your window (or no `start` at all) is moved forward to the window start, and the `Sandmark-Data-Window-Start` response header says where it began. An `end` before the window start returns `403`.

> [!TIP]
>
> Pair `lookback_days=30` with `tenor_label=1m` implied vol to compare like with like. See
> [Implied vs realised](https://docs.sandmark.com/guides/iv-vs-rv.md).


## OpenAPI

````yaml GET /v1/timeseries/rv
openapi: 3.0.3
info:
  title: Sandmark Volatility API
  version: 1.0.0
  description: >-
    Continuous implied and realised volatility for crypto options, with the
    reference data to query it.
  contact:
    name: Sandmark
    url: https://sandmark.com
servers:
  - url: https://api.sandmark.com/volatility
    description: Production
security:
  - apiKey: []
tags:
  - name: Reference
    description: Assets, frequencies and expiries.
  - name: Timeseries
    description: Continuous IV and RV series.
paths:
  /v1/timeseries/rv:
    get:
      tags:
        - Timeseries
      summary: Realised volatility
      description: >-
        Annualised realised volatility of the underlying index over a rolling
        lookback. `lookback_days=30` is 30-day realised vol, directly comparable
        with 1m implied vol. Values are decimal.


        **History window.** How far back you can read depends on your billing
        plan: 1 month on monthly billing, 1 year on quarterly, 3 years on
        annual. A `start` earlier than your window (or no `start` at all) is
        moved forward to the window start, and the `Sandmark-Data-Window-Start`
        response header says where it began. An `end` before the window start
        returns `403`.
      operationId: getRealizedVolTimeseries
      parameters:
        - name: asset
          in: query
          required: true
          schema:
            type: string
            enum:
              - DER.BTC_USD
              - DER.ETH_USD
              - DER.BTC_USDC
              - DER.ETH_USDC
              - DER.SOL_USDC
              - DER.XRP_USDC
              - DER.AVAX_USDC
              - DER.TRX_USDC
              - DER.HYPE_USDC
              - OKX.BTC_USD
              - OKX.ETH_USD
              - BIN.BTC_USDT
              - BIN.ETH_USDT
              - BYB.BTC_USDT
              - BYB.ETH_USDT
          description: >-
            Underlying identifier, `VENUE.BASE_QUOTE`. `DER` is Deribit; `OKX`,
            `BIN` (Binance) and `BYB` (Bybit) are the other venues.
            `DER.BTC_USD` and `DER.ETH_USD` are the inverse contracts and carry
            the deepest history; the `_USDC` underlyings are linear.
          example: DER.BTC_USD
        - name: frequency
          in: query
          required: true
          schema:
            type: string
            enum:
              - 1h
          description: >-
            Sampling frequency of the stored series. `GET /v1/frequencies` lists
            the available values.
          example: 1h
        - name: lookback_days
          in: query
          required: true
          schema:
            type: integer
            enum:
              - 1
              - 7
              - 14
              - 30
              - 60
              - 90
              - 180
              - 270
              - 365
          description: Estimator window in days.
          example: 30
        - name: start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Inclusive lower bound, ISO 8601 UTC (for example
            `2026-11-01T00:00:00Z`). Defaults to the start of your history
            window.
          example: '2026-10-20T00:00:00Z'
        - name: end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Inclusive upper bound, ISO 8601 UTC. Defaults to the latest stored
            observation.
          example: '2026-11-01T00:00:00Z'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 500
          description: >-
            Maximum rows to return. Rows are ordered **newest first**, so
            `limit` keeps the most recent observations inside `start`..`end`.
            Page backwards by moving `end`.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RvSeriesResponse'
              example:
                series: rv
                row_count: 2
                data:
                  - UNDERLYING_ID: DER.BTC_USD
                    DATETIME: '2026-11-06T22:00:00Z'
                    LOOKBACK_LABEL: 1m
                    LOOKBACK_DAYS: 30
                    RV: 0.3519
                    FREQUENCY: 1h
                    METHOD: rv_30d_lookback
                    METRIC_FAMILY: continuous_rv
                    LOAD_TS: '2026-11-06T22:27:44'
                  - UNDERLYING_ID: DER.BTC_USD
                    DATETIME: '2026-11-06T21:00:00Z'
                    LOOKBACK_LABEL: 1m
                    LOOKBACK_DAYS: 30
                    RV: 0.352
                    FREQUENCY: 1h
                    METHOD: rv_30d_lookback
                    METRIC_FAMILY: continuous_rv
                    LOAD_TS: '2026-11-06T21:27:45'
          headers:
            Sandmark-Data-Window-Start:
              description: >-
                Earliest timestamp your plan can read, ISO 8601 UTC. Use it to
                tell a clamped `start` from a real gap in the data.
              schema:
                type: string
                format: date-time
        '400':
          description: '`start` or `end` is not a valid ISO 8601 timestamp.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 400
                message: >-
                  start must be an ISO 8601 timestamp such as
                  2026-11-01T00:00:00Z; got 'yesterday'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 401
                message: >-
                  Access denied due to missing subscription key. Make sure to
                  include subscription key when making requests to an API.
        '403':
          description: '`end` falls before the start of your data window.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 403
                message: >-
                  end is before your data window, which starts at
                  2026-10-07T23:00:00Z
        '422':
          description: A parameter failed validation. `detail` names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '429':
          description: >-
            Rate limit exceeded. Retry after the number of seconds in
            `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 429
                message: Rate limit is exceeded. Try again in 12 seconds.
components:
  schemas:
    RvSeriesResponse:
      type: object
      required:
        - series
        - row_count
        - data
      properties:
        series:
          type: string
          enum:
            - rv
        row_count:
          type: integer
          description: Number of rows in `data`.
        data:
          type: array
          items:
            $ref: '#/components/schemas/RvRow'
          description: Newest first.
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          example: 403
        message:
          type: string
      required:
        - statusCode
        - message
    ValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  type: string
              msg:
                type: string
              type:
                type: string
    RvRow:
      type: object
      properties:
        UNDERLYING_ID:
          type: string
          example: DER.BTC_USD
        DATETIME:
          type: string
          format: date-time
          description: Bar close, UTC.
        LOOKBACK_DAYS:
          type: number
          description: Estimator window in days.
        LOOKBACK_LABEL:
          type: string
          example: 1m
        RV:
          type: number
          description: Annualised realised volatility, **decimal**.
        FREQUENCY:
          type: string
          example: 1h
        METHOD:
          type: string
          example: rv_30d_lookback
        METRIC_FAMILY:
          type: string
          example: continuous_rv
        LOAD_TS:
          type: string
          description: When the row was written, UTC.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Sandmark API key.

````

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