Contract Prices

/timeseries/market-contract-prices

Definition

Market contract prices are prices relevant to derivatives contract. It consists of the mark price, index price, and estimated settlement price.

The estimated settlement price is an estimate of the settlement price if the contract were to be settled

Details

Exchanges report the following contract prices:

• Mark price: The mark price is used by an exchange to calculate a trader's unrealized profit and losses and to trigger liquidations for risk management purposes. Each exchange applies a unique methodology for calculating the mark price, which typically is a function of the index price, funding rate, and the best bid and best ask with some smoothing applied over a time interval to address market manipulation or volatility. This prevents unnecessary liquidations during volatile market environments. Exchanges typically do not use the last traded price for risk management purposes because it is susceptible to market manipulation.

• Index price: The price of the derivative contract's underlying index. Each exchange applies a unique methodology for calculating the index price, which typically involves weighting the prices from spot markets from multiple different exchanges.

• Estimated settlement price: An estimate of the settlement price if the contract were to be immediately settleed. Each exchange applies a unique methodology for calculating the final settlement price, which typically involves an average of the index price over some interval. The estimated settlement price applies this methodology continuously in real-time. The estimated settlement price can be helpful in hedging or calculating estimated profit and loss prior to contract expiration.

API Endpoints

Market contract prices can be accessed using the timeseries/market-contract-prices endpoint.

Market contract prices

get

https://api.coinmetrics.io/v4wss://api.coinmetrics.io/v4https://community-api.coinmetrics.io/v4

/timeseries/market-contract-prices

Returns contract prices for specified markets. This includes index price and mark price that are used by the exchange for settlement and risk management purposes. Results are ordered by tuple (market, time). To fetch the next page of results use next_page_url JSON response field.

Authorizations

api_key

api_keystringRequired

Coin Metrics API key can be specified as ?api_key= query parameter.

Query parameters

marketsstring[]Required

Comma separated list of markets or market patterns like exchange-* or exchange-*-spot or *USDT-future. Use the /catalog-all/markets endpoint for the full list of supported markets.

start_timestringOptional

Start of the time interval. This field refers to the time field in the response. 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. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If start_time is omitted, response will include time series from the earliest time available.

end_timestringOptional

End of the time interval. This field refers to the time field in the response. 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. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If end_time is omitted, response will include time series up to the latest time available.

start_inclusivebooleanOptional

Inclusive or exclusive corresponding start_* parameters.

Default: true

end_inclusivebooleanOptional

Inclusive or exclusive corresponding end_* parameters.

Default: true

granularitystring · enumOptional

Downsampling granularity of market contract prices. Supported values are raw, 1m, 1h, and 1d.

Default: rawPossible values:

timezonestringOptional

Timezone name for start_time and end_time timestamps. This parameter does not modify the output times, which are always UTC. Format is defined by TZ database.

Default: UTCExample: America/New_York

page_sizeinteger · int32 · min: 1 · max: 10000Optional

Number of items per single page of results. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: 100

paging_fromstring · enumOptional

Where does the first page start, at the start of the interval or at the end. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: endPossible values:

limit_per_marketinteger · int32Optional

How many entries per market result should contain. It is useful when multiple markets are requested.

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

formatstring · enumOptional

Format of the response.

Default: jsonPossible values:

next_page_tokenstringOptional

Token for receiving the results from the next page of a query. Should not be used directly. To iterate through pages just use next_page_url response field.

Responses

200

Time series of market contract prices.

application/json

400

Market not found.

application/json

401

Requested resource requires authorization.

application/json

403

Requested resource is not available with supplied credentials.

application/json

414

Provided URI is too long. It must not be greater than 10000 symbols.

get

/timeseries/market-contract-prices

HTTPcURLJavaScriptPython

GET /v4/timeseries/market-contract-prices?markets=text HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

{
  "data": [
    {
      "market": "deribit-ETH-25MAR22-1200-P-option",
      "time": "2021-09-01T13:24:00.000000000Z",
      "mark_price": "0.02126",
      "index_price": "3529.34",
      "database_time": "2021-09-01T13:24:41.266168000Z",
      "exchange_time": "2021-09-01T13:24:00.000000000Z"
    }
  ],
  "next_page_token": "0.MjAyMC0wNi0wOFQyMDo0NTowMFo",
  "next_page_url": "https://api.coinmetrics.io/v4/timeseries/market-contract-prices?markets=deribit-ETH-10SEP21-3200-P-option&api_key=<your_key>&pretty=true&page_size=2&next_page_token=0.MjAyMC0wNi0wOFQyMDo0NTowMFo"
}

Shell

curl --compressed "https://api.coinmetrics.io/v4/timeseries/market-contract-prices?markets=deribit-ETH-25MAR22-1200-P-option&limit_per_market=1&api_key=<your_key>"

Python

Python Client

Example

A sample of contract price data from our /timeseries/market-contract-prices API endpoint is shown below for the deribit-ETH-25MAR22-1200-P-option market.

{
  "data" : [ {
    "market" : "deribit-BTC-11NOV22-20000-C-option",
    "time" : "2022-10-20T08:03:00.000000000Z",
    "database_time" : "2022-10-20T08:03:52.831102000Z",
    "mark_price" : "0.0791",
    "index_price" : "19153.67",
    "settlement_price_estimated" : "19153.67",
    "exchange_time" : "2022-10-20T08:03:51.768000000Z"
  }, {
    "market" : "deribit-BTC-11NOV22-20000-C-option",
    "time" : "2022-10-20T08:04:00.000000000Z",
    "database_time" : "2022-10-20T08:04:15.834472000Z",
    "mark_price" : "0.0791",
    "index_price" : "19154.68",
    "settlement_price_estimated" : "19154.68",
    "exchange_time" : "2022-10-20T08:04:14.938000000Z"
  } ]
}

• market: The id of the market. Market ids use the following naming convention for options markets: exchangeName-optionsSymbol-option

• time: The time at which Coin Metrics queried the contract price from an exchange in ISO 8601 date-time format. Always with nanoseconds precision.

• mark_price: The instrument market price, which represents the contract's fair market value and is used to calculate a trader's unrealized profit and losses and to trigger liquidations for risk management purposes.

• index_price: The price of the underlying benchmark index.

• settlement_price_estimated: Represents what the underlying index settlement price would be if the contract immediately expired.

• database_time: The timestamp when the data was saved in the database in ISO 8601 date-time format with nanoseconds precision. Always with nanoseconds precision.

• exchange_time: The timestamp reported by the exchange. Can be null if the exchange does not report a timestamp.

Release History

• CM MDF v2.5 on November 22, 2021: We expanded our options coverage to include several new data types, including market contract prices, from Deribit and added several new API endpoints to serve this data.

• CM MDF v2.7 on October 24, 2022: Began collecting and serving the settlement price and estimated settlement price for option markets. The settlement price is served in our /catalog/markets endpoint and is available shortly after an option market expires. And the estimated settlement price is updated once a minute and served in our /timeseries/market-contract-prices endpoint.