# 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="../basic-tier/exchange-trading-pair-codes-instruments">exchange-trading-pair-codes-instruments</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="../../../general/getting-started/pagination">pagination</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>