> For the complete documentation index, see [llms.txt](https://docs.kaiko.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kaiko.com/rest-api/reference-data/derivatives-contract-details.md).

# Derivatives contract details

{% hint style="info" %}

### This data is included in the following Kaiko packages:

* **Reference Data** \[Advanced Tier]
  {% endhint %}

### What is this endpoint for? <a href="#what-is-this-endpoint-for" id="what-is-this-endpoint-for"></a>

## What is this endpoint for?

This endpoint provides details of the contracts, including base asset, quote asset, contract size, contract size unit, listing\_timestamp, expiry, strike price, and underlying index.

### Endpoint

```url
https://<eu|us>.market-api.kaiko.io/v2/data/derivatives.v2/reference
```

### Path Parameters

| Parameter | Required? | Example                       |
| --------- | --------- | ----------------------------- |
| `region`  | Yes       | Choose between `eu` and `us`. |

### Query Parameters

<table><thead><tr><th width="163">Parameter</th><th width="98">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td><code>exchange</code></td><td>Yes</td><td>Should be one of the exchanges currently supported</td><td><code>okex</code></td></tr><tr><td><code>instrument_class</code></td><td>Yes</td><td><code>future</code>, <code>perpetual-future</code>, or <code>option</code></td><td><code>future</code></td></tr><tr><td><code>instrument</code></td><td>No</td><td>Instrument <code>code</code>.<br><br>See </td><td><code>ethusd220624</code>, <code>btc*220624</code>, <code>*usdt</code>, <code>btc*may22*</code></td></tr><tr><td><code>base_assets</code></td><td>No</td><td>For finding the instruments with the certain base asset</td><td><code>btc</code>, <code>eth</code></td></tr><tr><td><code>quote_assets</code></td><td>No</td><td>For finding the instruments with the certain quote asset</td><td><code>usd</code>, <code>usdt</code></td></tr><tr><td><code>option_type</code></td><td>No</td><td><code>option</code> only. For finding either only the call options or put options</td><td><code>C</code>, <code>P</code></td></tr><tr><td><code>min_strike</code></td><td>No</td><td><code>option</code> only. Used to retrieve options whose strike price is above this minimum value (exclusive/inclusive)</td><td><code>10000</code></td></tr><tr><td><code>max_strike</code></td><td>No</td><td><code>option</code> only. Used to retrieve options whose strike price is below this maximum value (exclusive/inclusive)</td><td><code>90000</code></td></tr><tr><td><code>start_time</code><br><br><strong>Deribit exchange only</strong></td><td>No</td><td><code>future</code> &#x26; <code>option</code> only. Used to retrieve futures and options that expire after this date and time (inclusive)</td><td><code>2022-06-23T00:01:00.000Z</code></td></tr><tr><td><code>end_time</code><br><br><strong>Deribit exchange only</strong></td><td>No</td><td><code>future</code> &#x26; <code>option</code> only. Used to retrieve futures and options that are listed before this date and time (exclusive)</td><td><code>2022-06-25T23:59:00.000Z</code></td></tr><tr><td><code>page_size</code></td><td>No</td><td>Number of snapshots to return data for. (default: 1000, min: 1, max: 1000).<br><br>See </td><td><code>500</code></td></tr></tbody></table>

### Fields: Perpetual-Future

| Field                    | Description                                                                        | Example                   |
| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------- |
| `exchange`               | The exchange where the specified instrument is being traded                        | `binc`                    |
| `instrument_class`       | Shows whether the specified instrument is `future`, `perpetual-future` or `option` | `perpetual-future`        |
| `instrument`             | The specified instrument                                                           | `btc-usdc`                |
| `base`                   | The base asset of the instrument                                                   | `btc`                     |
| `quote`                  | The unit in which the instrument is quoted                                         | `usdc`                    |
| `contract_size`          | Size of the contract                                                               | `1`                       |
| `contract_size_unit`     | Unit in which contract is denominated                                              | `btc`                     |
| `listing_timestamp`      | Date listed by exchange                                                            | `2024-01-03 12:30:00 UTC` |
| `funding_rate_frequency` | Interval at which the funding rate is paid                                         | `8h`                      |

### Fields: Future

| Field                | Description                                                                        | Example                   |
| -------------------- | ---------------------------------------------------------------------------------- | ------------------------- |
| `exchange`           | The exchange where the specified instrument is being traded                        | `okex`                    |
| `instrument_class`   | Shows whether the specified instrument is `future`, `perpetual-future` or `option` | `future`                  |
| `instrument`         | The specified instrument                                                           | `btcusdt250117`           |
| `base`               | The base asset of the instrument                                                   | `btc`                     |
| `quote`              | The unit in which the instrument is quoted                                         | `usdt`                    |
| `contract_size`      | Size of the contract                                                               | `0.01`                    |
| `contract_size_unit` | Unit in which contract is denominated                                              | `btc`                     |
| `listing_timestamp`  | The timestamp when a certain option instrument is listed on the exchange           | `2025-01-03 08:10:00 UTC` |
| `expiry`             | Expiration date of the contract                                                    | `2025-01-17 08:00:00 UTC` |

### Fields: Option

| Field                | Description                                                                        | Example                   |
| -------------------- | ---------------------------------------------------------------------------------- | ------------------------- |
| `exchange`           | The exchange where the specified instrument is being traded                        | `drbt`                    |
| `instrument_class`   | Shows whether the specified instrument is `future`, `perpetual-future` or `option` | `option`                  |
| `instrument`         | The specified instrument                                                           | `btc10dec21100000c`       |
| `base`               | The base asset of the instrument                                                   | `btc`                     |
| `quote`              | The unit in which the instrument is quoted                                         | `usd`                     |
| `contract_size`      | Size of the contract                                                               | `1`                       |
| `contract_size_unit` | Unit in which contract is denominated                                              | `btc`                     |
| `listing_timestamp`  | The timestamp when a certain option instrument is listed on the exchange           | `2021-11-18 08:16:00 UTC` |
| `expiry`             | Expiration date of the contract                                                    | `2021-12-10 08:00:00 UTC` |
| `strike_price`       | The strike price of the contract in USD.                                           | `30000`                   |
| `underlying_index`   | Name of the underlying asset                                                       | `BTC-10DEC21`             |

### Request examples

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

````url
curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/derivatives.v2/reference?exchange=drbt&instrument_class=option&base_assets=btc&page_size=50'```python
````

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

```python
##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
exchange = "okex"
instrument_class = "future"

# ---- Optional parameters ---- #
instrument = None
base_assets = None
quote_assets = "btc"
option_type = None
min_strike = None
max_strike = None
start_time = None
end_time = None
page_size = 500

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, exchange: str, instrument_class: str, instrument: str, base_assets: str, quote_assets: str, option_type: str, min_strike: int, max_strike: int, start_time: str, end_time: str, page_size: int):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/derivatives.v2/reference'
    params = {
        "exchange": exchange,
        "instrument_class": instrument_class,
        "instrument": instrument,
        "base_assets": base_assets,
        "quote_assets": quote_assets,
        "option_type": option_type,
        "min_strike": min_strike,
        "max_strike": max_strike,
        "start_time": start_time,
        "end_time": end_time,
        "page_size": page_size
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, exchange=exchange, instrument_class=instrument_class, instrument=instrument, base_assets=base_assets, quote_assets=quote_assets, option_type=option_type, min_strike=min_strike, max_strike=max_strike, start_time=start_time, end_time=end_time, page_size=page_size)
print (df)
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response example

```json
{
    "query": {
        "exchange": "drbt",
        "instrument_class": "option",
        "base_assets": [
            "btc"
        ],
        "page_size": "50",
        "data_version": "v2",
        "commodity": "derivatives",
        "request_time": "2022-11-30T15:26:49.66Z"
    },
    "time": "2022-11-30T15:26:55.623Z",
    "timestamp": 1669822015623,
    "data": [
        {
            "exchange": "drbt",
            "instrument_class": "option",
            "instrument": "btc10apr204750c",
            "base": "btc",
            "quote": "usd",
            "contract_size": "1",
            "contract_size_unit": "btc",
            "listing_timestamp": "2020-03-28 03:21:00 UTC",
            "expiry": "2020-04-10 08:00:00 UTC",
            "strike_price": "4750",
            "underlying_index": "SYN.BTC-10APR20"
        },
        /*---*/
    ],
    "result": "success",
    "continuation_token": "VHoT1C16LjCmtrfParGdwd4mVJnV1Qaqx5AMgXWsYawuiw68Qfymdf215NBcg9LzPJNxA9cZsBjB5S8JBHd8Giw2qoFDFvJ1tP3M5",
    "next_url": "https://us.market-api.kaiko.io/v2/data/derivatives.v2/reference?continuation_token=VHoT1C16LjCmtrfParGdwd4mVJnV1Qaqx5AMgXWsYawuiw68Qfymdf215NBcg9LzPJNxA9cZsBjB5S8JBHd8Giw2qoFDFvJ1tP3M5",
    "access": {
        "access_range": {
            "start_timestamp": 1646006400000,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}
```

Searching for contracts (Deribit exchange only). You can get a list of all the futures or options that can be traded between two specific times by using the `start_time` and `end_time` settings. For instance, if you're interested in all the futures or options that can be traded between October 1, 2022, and October 2, 2022, you would set start\_time as `2022-10-01T00:00:00.000Z` and end\_time as `2022-10-03T00:00:00.000Z`. If you want to find futures or options that were traded at a specific time, simply use the same time for both `start_time` and `end_time`. If you only provide one of the `start_time` or `end_time`, the other one will be automatically determined as shown in the table below.

| start\_time (ISO 8601) | end\_time (ISO 8601) | Description                                                                               |
| ---------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
| Given                  | Given                | `start_time (ISO 8601)` and `end_time (ISO 8601)` are the specified datetime respectively |
| Given                  | Not given            | `end_time (ISO 8601)` = `start_time (ISO 8601)` + 1 day                                   |
| Not given              | Given                | `start_time (ISO 8601)` = `end_time (ISO 8601)` - 1 day                                   |
| Not given              | Not given            | all the instruments will be shown regardless of dates                                     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kaiko.com/rest-api/reference-data/derivatives-contract-details.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.