# Expected shortfall calculation

## What is this endpoint for?

This endpoint helps you calculate the expected shortfall (ES) and stressed ES. It is computed by a proprietary and thoroughly backtested methodology that accounts for the idiosyncrasies of crypto market structure. By convention, it's a forecasting ES, i.e.,the prediction of the potential loss for the next day. We introduced a mixture parameter that can provide either the ES, the stressed ES or a combination of the two (see the `stress_parameter` below).

### Endpoint

{% code overflow="wrap" %}

```http
https://us.market-api.kaiko.io/v2/data/analytics.v2/expected_shortfall
```

{% endcode %}

### Parameters

<table><thead><tr><th>Parameter</th><th width="106.87890625">Required</th><th width="353.21484375">Description</th></tr></thead><tbody><tr><td><code>bases</code></td><td>Yes</td><td><p>List of portfolio base components. <br><br>See <a data-mention href="../../data-feeds/reference-data/basic-tier/asset-codes">asset-codes</a></p><p></p><p>Total must match <code>quantities</code> below.<br><br>The order of <code>bases</code> and their respective <code>quantities</code> must match in the request. </p></td></tr><tr><td><code>quote</code></td><td>Yes</td><td>The fiat currency.<br><br><a data-mention href="../../data-feeds/reference-data/basic-tier/asset-codes">asset-codes</a></td></tr><tr><td><code>quantities</code></td><td>Yes</td><td>Quantities list of base asset in the portfolio.<br><br>Must match the number of <code>bases</code>.<br><br>The order of <code>quantities</code> and their respective <code>bases</code> must match in the request. </td></tr><tr><td><code>risk_level</code></td><td>Yes</td><td><p>The risk level for the expected shortfall. <br><br>Min: <code>0.90</code> (included) </p><p><br>Max: <code>1</code> (excluded)</p></td></tr><tr><td><code>start_time</code></td><td>Yes</td><td>First fixing of the calculation in ISO 8601 (inclusive).</td></tr><tr><td><code>end_time</code></td><td>Yes</td><td>Last fixing of the calculation in ISO 8601 (inclusive).</td></tr><tr><td><code>stress_parameter</code></td><td>No</td><td><p>Float between <code>0</code> and <code>1</code> that controls the blend between ES and Stressed ES.</p><p><br>It is <code>0</code> for ES and <code>1</code> for stressed ES.</p><p><br>It equals <code>0</code> by default.</p></td></tr><tr><td><code>reporting_currency</code></td><td>No</td><td><p>This allows you to express the final risk metrics in a specific fiat currency.</p><p><br>By default, expressed in USD.</p></td></tr><tr><td><code>sources</code></td><td>No</td><td><code>boolean</code>. If true, returns all pair prices which were used to compute the expected shortfall. <br><br>Default: <code>false</code></td></tr></tbody></table>

### Fields

| Parameter            | Description                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `es_time`            | The time at which the ES is computed.                                                                           |
| `expected_shortfall` | Composed of two fields: value and `risk_level` (the expected shortfall estimator at the specified `risk_level`) |
| `pair`               | The constituent pair. (showing only when `sources` is set to be true)                                           |
| `ref_price`          | The reference price per asset. (showing only when `sources` is set to be true)                                  |
| `date`               | The date of the reference price. (showing only when `sources` is set to be true)                                |

### 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/analytics.v2/expected_shortfall?bases=eth,btc,ltc&quantities=3,2,5&quote=usd&risk_level=0.95&start_time=2025-12-01T00:00:00.000Z&end_time=2025-12-05T00:00:00.000Z&stress_parameter=0.5&reporting_currency=eur'
```

{% 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 ---- #
bases = "btc,eth"
quote = "usd"
quantities = "1,10"
risk_level = "0.95"
start_time = "2021-12-01T00:00:00.000Z"
end_time = "2022-01-31T00:00:00.000Z"

# ---- Optional parameters ---- #
sources = None

# ---- 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, bases: str, quote: str, quantities: str, risk_level: str, start_time: str, end_time: str, sources: bool = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/analytics.v2/expected_shortfall'
    params = {
        "bases": bases,
        "quote": quote,
        "quantities": quantities,
        "risk_level": risk_level,
        "start_time": start_time,
        "end_time": end_time,
        "sources": sources
    }

    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, bases=bases, quote=quote, quantities=quantities, risk_level=risk_level, start_time=start_time, end_time=end_time, sources=sources)
print (df)
```

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

### Response example

{% code overflow="wrap" %}

```json
{
    "query": {
        "bases": "eth,btc,ltc",
        "quote": "usd",
        "quantities": [
            3,
            2,
            5
        ],
        "exchanges": "",
        "risk_level": 0.95,
        "sources": false,
        "data_version": "v2",
        "commodity": "analytics",
        "request_time": "2026-04-01T14:29:00.536Z",
        "reporting_currency": "eur"
    },
    "time": "2026-04-01T14:29:00.825Z",
    "timestamp": 1775053740825,
    "data": [
        {
            "es_time": 1764547200000,
            "expected_shortfall": {
                "value": 13337.396618466695,
                "risk_level": 0.95
            }
        },
        {
            "es_time": 1764633600000,
            "expected_shortfall": {
                "value": 13193.145029429792,
                "risk_level": 0.95
            }
        },
        {
            "es_time": 1764720000000,
            "expected_shortfall": {
                "value": 13476.064947481469,
                "risk_level": 0.95
            }
        },
        {
            "es_time": 1764806400000,
            "expected_shortfall": {
                "value": 13587.247396977718,
                "risk_level": 0.95
            }
        },
        {
            "es_time": 1764892800000,
            "expected_shortfall": {
                "value": 13553.701550483325,
                "risk_level": 0.95
            }
        }
    ],
    "access": {
        "access_range": {
            "start_timestamp": 1763683200,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}
```

{% endcode %}