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

# Market open interest

> Returns open interest for specified futures, options, and event-contract markets.<br/> Results are ordered by tuple `(market, time)`.<br/> With `type=event_contract`, markets are ordered by normalized exchange and raw symbol; `value_usd` is null. Granularity uses a rolling time filter: the first row in traversal order is emitted, then rows are suppressed until the next threshold. In END traversal, a row exactly at the threshold is emitted. Event-contract pagination preserves the rolling threshold across pages, so changing `page_size` does not change the selected observations.<br/> To fetch the next page of results use `next_page_url` JSON response field. Keep in mind that spot markets are not supported by this endpoint.<br/><br/> <b>Note:</b> The `value_usd` field in this endpoint was previously calculated using hardcoded logic that no longer reflects current contract specifications across all exchanges.<br/><br/> To address this, we have deprecated the `value_usd` field and introduced new, more accurate metrics available via the `/timeseries/market-metrics` endpoint.<br/><br/> These two metrics should be used as a replacement for the `value_usd` field going forward:<br/> - `open_interest_reported_future_usd` to represent the notional value of open interest in U.S. dollars for futures markets<br/> - `open_interest_reported_option_notional_usd` to represent the notional value of open interest in U.S. dollars for options markets<br/><br/> We also introduced `open_interest_reported_option_market_value_usd` to represent the market value of open interest in U.S. dollars for options markets.



## OpenAPI

````yaml /coinmetrics/openapi/coinmetrics.yaml get /timeseries/market-openinterest
openapi: 3.0.2
info:
  title: Coin Metrics API v4
  description: >-
    [Coin Metrics Homepage](https://coinmetrics.io/)<br/> [API Backward
    Compatibility
    Policy](https://docs.coinmetrics.io/access-our-data/api#backward-compatibility)<br/>
    [Python API
    Client](https://coinmetrics.github.io/api-client-python/site/index.html)<br/><br/>

    HTTP API root endpoint URL is `https://api.coinmetrics.io/v4`. Coin
    Metrics&apos; paid product.<br/> WebSocket API root endpoint is
    `wss://api.coinmetrics.io/v4`. Coin Metrics&apos; paid product.<br/><br/>
    The Community HTTP API root endpoint URL is
    `https://community-api.coinmetrics.io/v4`. API key is not required when
    accessing community endpoints. Available to the community under the
    [Creative Commons](https://creativecommons.org/licenses/by-nc/4.0/) license.

    # Authentication

    <!-- ReDoc-Inject: <security-definitions> -->

    # Response headers

    Note that Coin Metrics API responses have a `CF-RAY` HTTP header e.g.
    `88a6ec1d2f930774-IAD` which can be used for diagnostic purposes. When
    raising Support requests, please ensure to provide the value of this
    header. 
  termsOfService: https://coinmetrics.io/api/terms
  contact:
    name: Coin Metrics Support
    url: https://coinmetrics.io/support/
    email: support@coinmetrics.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 4.0.0
servers:
  - url: https://api.coinmetrics.io/v4
  - url: wss://api.coinmetrics.io/v4
  - url: https://community-api.coinmetrics.io/v4
security: []
tags:
  - name: Rate limits
    description: >-
      To ensure the quality of Coin Metrics services, API is subject to rate
      limiting.<br/> <table> <tr><th>Rate Limit Plan</th><th>REST API: Requests
      per Second (sliding window)</th><th>REST API: Download Speed</th><th>REST
      API: Max Parallel Requests</th><th>WebSocket API: Max Parallel
      Connections</th></tr> <tr><td>Community</td><td>10 requests per 6 seconds
      per IP address</td><td>Reduced speed</td><td>10</td><td>N/A</td></tr>
      <tr><td>Trial</td><td>10 requests per 6 seconds per API key</td><td>Max
      speed</td><td>10</td><td>200</td></tr> <tr><td>Default (PRO)</td><td>6000
      requests per 20 seconds per API key</td><td>Standard
      speed</td><td>10</td><td>200</td></tr> <tr><td>Download (PRO)</td><td>6000
      requests per 20 seconds per API key</td><td>Max
      speed</td><td>10</td><td>200</td></tr> </table> <br/> All PRO keys by
      default get the "default" rate limits. To download historical data at max
      speed, you need to switch to the "download" plan. <br/> <br/> The paid and
      community versions of the API have a limit of 10 parallel REST API
      requests. After this limit is reached, further parallel requests will be
      queued, so performance will be slower.<br/> <br/> If you reach the
      request-per-second limit, API starts to return `429 Too Many Requests`
      HTTP response status.<br/> API also provides `X-RateLimit-*` response
      headers formatted according to
      https://tools.ietf.org/html/draft-polli-ratelimit-headers-03.<br/>
      Additionally, the API provides the `X-RateLimit-Plan` header which
      indicates the current rate limiting plan. This header may have values:
      `default`, `trial`, `download`, or `community`.
    x-cm-gitbook:
      foldIntoInfo: true
  - name: Reference Data
    description: Metadata information of entities supported by Coin Metrics.
    x-cm-gitbook:
      tag: Meta Data
      icon: book
  - name: Catalog
    x-displayName: Catalog (deprecated)
    description: >-
      Catalog of available for your `api_key` data.<br/> Use the [Full
      catalog](#tag/Full-catalog) endpoints for the full list of supported by
      Coin Metrics data. <br/>DEPRECATED: See
      https://coinmetrics.io/important-changes-to-coin-metrics-api-catalog-endpoints/.
    x-cm-gitbook:
      remove: true
  - name: Catalog v2
    description: >-
      Catalog of available for your `api_key` data.<br/> Use the [Full catalog
      V2](#tag/Full-catalog-v2) endpoints for the full list of supported by Coin
      Metrics data.
    x-cm-gitbook:
      icon: list-check
  - name: Full catalog
    x-displayName: Full catalog (deprecated)
    description: >-
      The Full catalog returns the full range of data that is supported by Coin
      Metrics across all our products.<br/> If you are a client looking to
      understand the data that is available for your API key and data license,
      please use the [Catalog](#tag/Catalog) endpoint. <br/>DEPRECATED: See
      https://coinmetrics.io/important-changes-to-coin-metrics-api-catalog-endpoints/.
    x-cm-gitbook:
      remove: true
  - name: Full catalog v2
    description: >-
      The Full catalog returns the full range of data that is supported by Coin
      Metrics across all our products.<br/> If you are a client looking to
      understand the data that is available for your API key and data license,
      please use the [Catalog](#tag/Catalog-v2) endpoint.
    x-cm-gitbook:
      tag: Catalog v2
      icon: layer-group
  - name: Timeseries
    description: >-
      Endpoints for fetching metrics, market data, indexes and other time series
      data.
    x-cm-gitbook:
      icon: chart-line
      renameOperationsTo: Timeseries REST
  - name: Timeseries stream
    description: >-
      WebSocket endpoints for getting a real-time stream of metrics, market
      data, indexes and other time series data.
    x-cm-gitbook:
      tag: Timeseries
      icon: wifi
  - name: Taxonomy
    description: Taxonomy endpoints
    x-cm-gitbook:
      icon: sitemap
  - name: Taxonomy Metadata
    description: Taxonomy Metadata endpoints
    x-cm-gitbook:
      tag: Taxonomy
      icon: tags
  - name: Profile
    description: Profile endpoints
    x-cm-gitbook:
      tag: Meta Data
      icon: id-card
  - name: List of blockchain entities v2
    description: Endpoints for fetching lists of blockchain entities.
    x-cm-gitbook:
      tag: ATLAS
      icon: list
  - name: Full blockchain entities v2
    description: Endpoints for fetching full blockchain entities.
    x-cm-gitbook:
      tag: List of blockchain entities v2
      icon: database
  - name: Jobs
    description: Jobs API endpoints
    x-cm-gitbook:
      tag: ATLAS
      icon: briefcase
  - name: Blockchain Explorer Job
    description: Endpoints for creating async jobs for blockchain entities.
    x-cm-gitbook:
      tag: ATLAS
      icon: clock
  - name: Blockchain Explorer Job Results
    description: Schema definitions of results of Blockchain Explorer Job endpoints.
    x-cm-gitbook:
      foldInto: Blockchain Explorer Job
  - name: Chain Monitor tools
    description: Endpoints for working with chain monitor data.
    x-cm-gitbook:
      tag: ATLAS
      icon: wrench
  - name: Security Master
    description: Security Master endpoints
    x-cm-gitbook:
      tag: Meta Data
      icon: shield
  - name: Constituent Snapshots
    description: Endpoints for getting the snapshots of various constituents
    x-cm-gitbook:
      tag: Meta Data
      icon: camera
  - name: Constituent Timeframes
    description: Endpoints for getting the timeframes of various constituents
    x-cm-gitbook:
      tag: Meta Data
      icon: calendar
  - name: Blockchain Metadata
    description: Blockchain metadata endpoints
    x-cm-gitbook:
      tag: Meta Data
      icon: database
  - name: Meta Data
    x-cm-gitbook:
      icon: database
  - name: ATLAS
    x-cm-gitbook:
      icon: map
  - name: Timeseries REST
    x-cm-gitbook:
      tag: Timeseries
      icon: table
paths:
  /timeseries/market-openinterest:
    servers:
      - url: https://api.coinmetrics.io/v4
      - url: https://community-api.coinmetrics.io/v4
    get:
      tags:
        - Timeseries
      summary: Market open interest
      description: >-
        Returns open interest for specified futures, options, and event-contract
        markets.<br/> Results are ordered by tuple `(market, time)`.<br/> With
        `type=event_contract`, markets are ordered by normalized exchange and
        raw symbol; `value_usd` is null. Granularity uses a rolling time filter:
        the first row in traversal order is emitted, then rows are suppressed
        until the next threshold. In END traversal, a row exactly at the
        threshold is emitted. Event-contract pagination preserves the rolling
        threshold across pages, so changing `page_size` does not change the
        selected observations.<br/> To fetch the next page of results use
        `next_page_url` JSON response field. Keep in mind that spot markets are
        not supported by this endpoint.<br/><br/> <b>Note:</b> The `value_usd`
        field in this endpoint was previously calculated using hardcoded logic
        that no longer reflects current contract specifications across all
        exchanges.<br/><br/> To address this, we have deprecated the `value_usd`
        field and introduced new, more accurate metrics available via the
        `/timeseries/market-metrics` endpoint.<br/><br/> These two metrics
        should be used as a replacement for the `value_usd` field going
        forward:<br/> - `open_interest_reported_future_usd` to represent the
        notional value of open interest in U.S. dollars for futures markets<br/>
        - `open_interest_reported_option_notional_usd` to represent the notional
        value of open interest in U.S. dollars for options markets<br/><br/> We
        also introduced `open_interest_reported_option_market_value_usd` to
        represent the market value of open interest in U.S. dollars for options
        markets.
      operationId: getTimeseriesMarketOpenIntereset
      parameters:
        - $ref: '#/components/parameters/MarketId'
        - $ref: '#/components/parameters/TimeseriesMarketOpenInterestType'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/StartInclusive'
        - $ref: '#/components/parameters/EndInclusive'
        - $ref: '#/components/parameters/OpenInterestGranularity'
        - $ref: '#/components/parameters/Timezone'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PagingFrom'
        - $ref: '#/components/parameters/LimitPerMarket'
        - $ref: '#/components/parameters/Pretty'
        - $ref: '#/components/parameters/ResponseFormat'
        - $ref: '#/components/parameters/NextPageToken'
      responses:
        '200':
          $ref: '#/components/responses/MarketOpenInterest'
        '400':
          $ref: '#/components/responses/MarketNotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '414':
          $ref: '#/components/responses/UriTooLong'
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: Shell
          source: >
            curl --compressed
            "https://api.coinmetrics.io/v4/timeseries/market-openinterest?start_time=2020-08-05T23:00:00Z&end_time=2020-08-06T00:00:00Z&paging_from=start&markets=bitmex-XBTUSD-future&pretty=true&api_key=<your_key>"
        - lang: Python
          label: Python
          source: >
            import requests

            response =
            requests.get('https://api.coinmetrics.io/v4/timeseries/market-openinterest?start_time=2020-08-05T23:00:00Z&end_time=2020-08-06T00:00:00Z&paging_from=start&markets=bitmex-XBTUSD-future&pretty=true&api_key=<your_key>').json()

            print(response)
        - lang: Python
          label: Python Client
          source: >
            from coinmetrics.api_client import CoinMetricsClient

            client = CoinMetricsClient(<your_key>)


            response =
            client.get_market_openinterest(start_time="2020-08-05T23:00:00Z",
            end_time="2020-08-06T00:00:00Z", paging_from="start",
            markets="bitmex-XBTUSD-future").to_list()

            print(response)
components:
  parameters:
    MarketId:
      description: >-
        Comma separated list of markets or market patterns like `exchange-*` or
        `exchange-*-spot` or `*USDT-future`.<br/> Use a corresponding
        `/catalog-all-v2/market-{dataType}` endpoint for the full list of
        supported markets for a given data type.
      in: query
      name: markets
      required: true
      schema:
        type: array
        items:
          type: string
      explode: false
    TimeseriesMarketOpenInterestType:
      description: >-
        Selects prediction-market open interest. Without this parameter,
        prediction markets are excluded.
      in: query
      name: type
      schema:
        type: string
        enum:
          - event_contract
    StartTime:
      description: >-
        Start of the time interval.<br/> This field refers to the `time` field
        in the response.<br/> Multiple formats of ISO 8601 are supported:
        `2006-01-20T00:00:00Z`, `2006-01-20T00:00:00.000Z`,
        `2006-01-20T00:00:00.123456Z`, `2006-01-20T00:00:00.123456789Z`,
        `2006-01-20`, `20060120`.<br/> Inclusive by default.<br/> UTC timezone
        by default. `Z` suffix is optional and `timezone` parameter has a
        priority over it.<br/> If `start_time` is omitted, response will include
        time series from the **earliest** time available.
      in: query
      name: start_time
      schema:
        type: string
    EndTime:
      description: >-
        End of the time interval.<br/> This field refers to the `time` field in
        the response.<br/> Multiple formats of ISO 8601 are supported:
        `2006-01-20T00:00:00Z`, `2006-01-20T00:00:00.000Z`,
        `2006-01-20T00:00:00.123456Z`, `2006-01-20T00:00:00.123456789Z`,
        `2006-01-20`, `20060120`.<br/> Inclusive by default.<br/> UTC timezone
        by default. `Z` suffix is optional and `timezone` parameter has a
        priority over it.<br/> If `end_time` is omitted, response will include
        time series up to the **latest** time available.
      in: query
      name: end_time
      schema:
        type: string
    StartInclusive:
      description: Inclusive or exclusive corresponding `start_*` parameters.
      in: query
      name: start_inclusive
      schema:
        default: true
        type: boolean
    EndInclusive:
      description: Inclusive or exclusive corresponding `end_*` parameters.
      in: query
      name: end_inclusive
      schema:
        default: true
        type: boolean
    OpenInterestGranularity:
      description: >-
        Downsampling granularity of market open interest. Supported values are
        `raw`, `1m`, `1h`, and `1d`.
      in: query
      name: granularity
      schema:
        default: raw
        type: string
        enum:
          - raw
          - 1m
          - 1h
          - 1d
    Timezone:
      description: >-
        Timezone name for `start_time` and `end_time` timestamps.<br/> This
        parameter does not modify the output times, which are always `UTC`.<br/>
        Format is defined by [TZ
        database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
      in: query
      name: timezone
      schema:
        example: America/New_York
        default: UTC
        type: string
    PageSize:
      description: >-
        Number of items per single page of results.<br/> The value of this
        parameter is ignored if the endpoint supports the `format` parameter and
        its value is set to `json_stream`.
      in: query
      name: page_size
      schema:
        default: 100
        type: integer
        format: int32
        minimum: 1
        maximum: 10000
    PagingFrom:
      description: >-
        Where does the first page start, at the start of the interval or at the
        end.<br/> The value of this parameter is ignored if the endpoint
        supports the `format` parameter and its value is set to `json_stream`.
      in: query
      name: paging_from
      schema:
        default: end
        enum:
          - start
          - end
        type: string
        format: PagingFrom
    LimitPerMarket:
      description: >-
        How many entries per market result should contain. It is useful when
        multiple markets are requested.
      in: query
      name: limit_per_market
      schema:
        type: integer
        format: int32
    Pretty:
      description: Human-readable formatting of JSON responses.
      in: query
      name: pretty
      schema:
        type: boolean
        default: false
    ResponseFormat:
      description: >-
        Format of the response. Supported values are `json`, `json_stream`,
        `csv`.
      in: query
      name: format
      schema:
        enum:
          - json
          - json_stream
          - csv
        type: string
        default: json
    NextPageToken:
      description: >-
        Token for receiving the results from the next page of a query.<br/>
        Should not be used directly. To iterate through pages just use
        `next_page_url` response field.
      in: query
      name: next_page_token
      schema:
        type: string
  responses:
    MarketOpenInterest:
      description: Time series of market open interest.
      content:
        application/json:
          example:
            data:
              - market: binance-BTCUSDT-future
                time: '2020-08-05T23:04:50.421035000Z'
                contract_count: '35074.075'
                value_usd: '408810440.79225'
                database_time: '2020-08-05T23:04:50.606185000Z'
                exchange_time: '2020-08-05T23:03:59.417000000Z'
              - market: binance-BTCUSDT-future
                time: '2020-08-05T23:19:10.016074000Z'
                contract_count: '35061.142'
                value_usd: '409113039.09552'
                database_time: '2020-08-05T23:19:10.749665000Z'
                exchange_time: '2020-08-05T23:19:00.458000000Z'
          schema:
            $ref: '#/components/schemas/MarketOpenInterestResponse'
    MarketNotFound:
      content:
        application/json:
          example:
            error:
              type: bad_parameter
              message: >-
                Bad parameter 'markets'. Market 'sdvwbtc-as-asd-spot' is not
                supported.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Market not found.
    Unauthorized:
      description: Requested resource requires authorization.
      content:
        application/json:
          examples:
            unauthorized:
              summary: Unauthorized error response.
              value:
                error:
                  type: unauthorized
                  message: Requested resource requires authorization.
            wrong_credentials:
              summary: Wrong credentials error response.
              value:
                error:
                  type: wrong_credentials
                  message: Supplied credentials are not valid.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      content:
        application/json:
          example:
            error:
              type: forbidden
              message: >-
                Requested metric 'SplyBMXNtv' with frequency '1d' for asset
                'btc' is not available with supplied credentials.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Requested resource is not available with supplied credentials.
    UriTooLong:
      description: Provided URI is too long. It must not be greater than 10000 symbols.
  schemas:
    MarketOpenInterestResponse:
      properties:
        data:
          $ref: '#/components/schemas/MarketOpenInterestDataArray'
        next_page_token:
          $ref: '#/components/schemas/NextPageToken'
        next_page_url:
          $ref: '#/components/schemas/NextPageUrl'
      required:
        - data
      type: object
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
        - error
      type: object
    MarketOpenInterestDataArray:
      description: Time series of market open interest.
      items:
        $ref: '#/components/schemas/MarketOpenInterest'
      type: array
    NextPageToken:
      description: Token of the next page results for a given request.
      type: string
    NextPageUrl:
      description: URL of the next page results for a given request.
      type: string
    ErrorObject:
      properties:
        type:
          description: Error type string. Can be used for error identification.
          type: string
        message:
          description: >-
            Human-friendly error description. Can be amended without prior
            notification. Do not use for error identification in your code.
          type: string
      required:
        - type
        - description
      type: object
    MarketOpenInterest:
      description: Information about open interest.
      properties:
        market:
          $ref: '#/components/schemas/MarketId'
        time:
          $ref: '#/components/schemas/Time'
        contract_count:
          $ref: '#/components/schemas/ContractCount'
        value_usd:
          description: >-
            Deprecated. Contract value in USD. This field was previously
            calculated using hardcoded logic that no longer reflects current
            contract specifications across all exchanges. Please use the new
            metrics available via `/timeseries/market-metrics` endpoint:
            `open_interest_reported_future_usd` for futures markets and
            `open_interest_reported_option_notional_usd` for options markets.
            Event-contract open interest returns null.
          deprecated: true
          type: string
          format: decimal
          nullable: true
        database_time:
          $ref: '#/components/schemas/DatabaseTime'
        exchange_time:
          $ref: '#/components/schemas/OpenInterestExchangeTime'
      required:
        - market
        - time
        - contract_count
        - value_usd
        - database_time
      type: object
    MarketId:
      description: Unique name of the market.
      type: string
    Time:
      description: >-
        The time in ISO 8601 date-time format. Always with nanoseconds
        precision.
      type: string
      format: date-time
    ContractCount:
      description: Number of contracts. Returned as a decimal string.
      type: string
      format: decimal
    DatabaseTime:
      description: >-
        A time when we saved the data in the database. The time is in ISO 8601
        date-time format. Always with nanoseconds precision.
      type: string
      format: date-time
    OpenInterestExchangeTime:
      description: >-
        Time corresponding to the open interest data point. For open interest,
        this always equals `time`, since open interest is stored with a single
        timestamp rather than an independent exchange-reported time. Present for
        schema consistency with other market data types.
      type: string
      format: date-time
  securitySchemes:
    api_key:
      description: Coin Metrics API key can be specified as `?api_key=` query parameter.
      in: query
      name: api_key
      type: apiKey

````