# Derivatives contract details

## 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 <a data-mention href="/pages/8ywkQXfxfv1FjtyspEaU">/pages/8ywkQXfxfv1FjtyspEaU</a></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 <a data-mention href="/pages/mP3amLsYqKTsrRBoblxX">/pages/mP3amLsYqKTsrRBoblxX</a></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 wether 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 wether 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 wether 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.

<table><thead><tr><th width="236">start_time (ISO 8601)</th><th width="243">end_time (ISO 8601)</th><th>Description</th></tr></thead><tbody><tr><td>Given</td><td>Given</td><td><code>start_time (ISO 8601)</code> and <code>end_time (ISO 8601)</code> are the specified datetime respectively</td></tr><tr><td>Given</td><td>Not given</td><td><code>end_time (ISO 8601)</code> = <code>start_time (ISO 8601)</code> + 1 day</td></tr><tr><td>Not given</td><td>Given</td><td><code>start_time (ISO 8601)</code> = <code>end_time (ISO 8601)</code> - 1 day</td></tr><tr><td>Not given</td><td>Not given</td><td>all the instruments will be shown regardless of dates</td></tr></tbody></table>


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.