# Synthetic price

## What is this endpoint for?

This endpoint calculates a synthetic price when there is no liquidity (historic trades) between two assets (fiat or digital). Let's say, for example, there was no liquidity between NEXO and GBP, but you need a price. To calculate this, the liquidity engine will use a series of intermediary assets where there is liquidity (lots of trading history) to calculate the price for NEXO > GBP.  \
\
To demonstrate how this calculation works, the engine might take the price for NEXO > BTC (where there is plenty of liquidity) and then the price of BTC > GBP (where there is also lots of liquidity) and combine the two to determine a robust synthetic price for NEXO > GBP. The engine will always use the path of highest liquidity, meaning several intermediary assets might be used. 

Read the full methodology [here](https://25446524.fs1.hubspotusercontent-eu1.net/hubfs/25446524/Factsheets/Kaiko%20Pricing%20Services%20Methodology.pdf). 

{% hint style="warning" %}
When using a synthetic price, in order to to meet IFRS-compliance standards, any fiat currency value should be requested in USD and converted using the [Oanda FX Rates add-on](/rest-api/analytics-solutions/kaiko-fair-market-value/established-assets/synthetic-price/convert-with-oanda-fx-rates.md). 
{% endhint %}

### HTTP Request

{% code overflow="wrap" %}

```http
https://<eu|us>.market-api.kaiko.io/v2/data/trades.v2/spot_exchange_rate/{base_asset}/{quote_asset}
```

{% endcode %}

### Path parameters

<table><thead><tr><th width="182">Parameter</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>base_asset</code></td><td>Yes</td><td>The desired base asset <code>code</code>.<br><br>See <a data-mention href="/pages/5iH1qlIc7aNEOOci4yMw">/pages/5iH1qlIc7aNEOOci4yMw</a></td></tr><tr><td><code>quote_asset</code></td><td>Yes</td><td>The desired quote asset <code>code</code>.<br><br>See <a data-mention href="/pages/5iH1qlIc7aNEOOci4yMw">/pages/5iH1qlIc7aNEOOci4yMw</a></td></tr></tbody></table>

### Query parameters

<table><thead><tr><th width="182">Parameter</th><th width="105">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>start_time</code></td><td>No</td><td>Start time in ISO 8601 (exclusive).<br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>end_time</code></td><td>No</td><td>Ending time in ISO 8601 (exclusive).<br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>interval</code></td><td>No</td><td>The interval parameter is suffixed with <code>s</code>, <code>m</code>, <code>h</code> or <code>d</code> to specify seconds, minutes, hours or days, respectively.<br><br>Any arbitrary value between one second and one day can be used, as long as it sums up to a maximum of 1 day. The suffixes are <code>s</code> (second), <code>m</code> (minute), <code>h</code> (hour) and <code>d</code> (day).<br><br> Default <code>1d</code>.</td></tr><tr><td><code>page_size</code></td><td>No</td><td><p>See <a data-mention href="/pages/mP3amLsYqKTsrRBoblxX">/pages/mP3amLsYqKTsrRBoblxX</a><br><br><strong>Page size limits differ by the <code>interval</code> selected:</strong></p><ul><li>Less than or equal to <code>1m</code><br> Default: <code>10</code>, Max: <code>100</code></li><li><code>1m</code> to <code>1h</code><br>Default: <code>4</code>, Max: <code>10</code></li><li>More than <code>1h</code><br>Default: <code>1</code>, Max: <code>4</code></li></ul><p><em>Automatically included in continuation tokens.</em></p></td></tr><tr><td><code>sort</code></td><td>No</td><td>Return the data in ascending (<code>asc</code>) or descending (<code>desc</code>) order. Default is <code>desc</code>.<br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>include_exchanges</code></td><td>No</td><td>List of exchanges' <code>code</code> to include in the calculation.<br><br><a data-mention href="/pages/QiW5iUvcyBF9RISFmZFV">/pages/QiW5iUvcyBF9RISFmZFV</a><br><br>Default is all exchanges.<br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>exclude_exchanges</code></td><td>No</td><td>List of exchanges' <code>code</code> to exclude in the calculation.<br><br><a data-mention href="/spaces/bvJkzmxJbcDMceEJsq2K/pages/vGAuhofqiYGAJCYlarFi">/spaces/bvJkzmxJbcDMceEJsq2K/pages/vGAuhofqiYGAJCYlarFi</a><br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>extrapolate_missing_values</code></td><td>No</td><td>When <code>true</code>, if there are any <code>null</code> (missing) prices for the calculation, they will be filled in using the last available price from the window requested. This is useful for assets that don't have a lot of trades or for data that is collected very frequently.<br><br>However, if the parameter is set to <code>true</code> and no prices were available in that window, a <code>null</code> value will still be returned.</td></tr><tr><td><code>sources</code></td><td>No</td><td>When <code>true,</code> the response includes the intermediary pair price details used to calculate the price.<br><br>Default: <code>false</code></td></tr></tbody></table>

### Fields

<table><thead><tr><th width="224">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>timestamp</code></td><td>Timestamp at which the interval begins.</td></tr><tr><td><code>price</code></td><td>Aggregated <a href="https://hal.science/hal-04017151v1/document">Robust Weighted Median</a> using liquidity path engine. <br><br><code>null</code> when no trades reported, except if <code>extrapolate_missing_values</code> is <code>true</code>.<br><br><em>Liquidity path is calculated every 4 hours seeking for the most liquid pairs to convert from base asset to quote asset.</em></td></tr><tr><td><code>extrapolate_missing_values</code></td><td><code>true</code> if the value has been extrapolated from the last computed value available, <code>false</code> if not.</td></tr></tbody></table>

### 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/trades.v2/spot_exchange_rate/dash/usd?interval=1m&extrapolate_missing_values=true&start_time=2023-05-03T00:01:00.000Z&end_time=2023-05-04T00:00:00.000Z'
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}

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

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
base_asset = "btc"
quote_asset = "usd"

# ---- Optional parameters ---- #
interval = "1h"
sort = "desc"
page_size = 4
start_time= "2023-01-01T00:00:00Z"
end_time= "2023-01-01T23:59:59Z"
include_exchanges = None
exclude_exchanges = None
extrapolate_missing_values = None
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, base_asset: str, quote_asset: str, start_time: str, end_time: str, interval: str, sort: str, page_size: int, include_exchanges: list = None, exclude_exchanges: list = None, extrapolate_missing_values: bool = None, sources: bool = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/trades.v2/spot_exchange_rate/{base_asset}/{quote_asset}'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size,
        "interval": interval,
        "include_exchanges": include_exchanges,
        "exclude_exchanges": exclude_exchanges,
        "extrapolate_missing_values": extrapolate_missing_values,
        "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, base_asset=base_asset, quote_asset=quote_asset, interval=interval, start_time=start_time, end_time=end_time, sort=sort, page_size=page_size, include_exchanges=include_exchanges, exclude_exchanges=exclude_exchanges, extrapolate_missing_values=extrapolate_missing_values, sources=sources)
print (df)
```

{% endtab %}
{% endtabs %}

### Response example

```json
{
  "query": {
    "start_time": "2023-05-03T00:01:00Z",
    "end_time": "2023-05-04T00:00:00Z",
    "page_size": 10,
    "base_asset": "dash",
    "quote_asset": "usd",
    "interval": "1m",
    "sort": "desc",
    "sources": false,
    "include_exchanges": [],
    "exclude_exchanges": [],
    "data_version": "v1",
    "commodity": "trades",
    "request_time": "2024-07-11T08:10:21.828Z",
    "instruments": [
      "bbsp:spot:btc-usdt",
      "bfnx:spot:btc-usdt",
      "bgon:spot:btc-usdt",
      "binc:spot:btc-usdt",
      "bnus:spot:btc-usdt",
      "bull:spot:btc-usdt",
      "cbse:spot:btc-usdt",
      "cnex:spot:btc-usdt",
      "gmni:spot:btc-usdt",
      "kcon:spot:btc-usdt",
      "krkn:spot:btc-usdt",
      "okex:spot:btc-usdt",
      "stmp:spot:btc-usdt",
      "bfnx:spot:dash-btc",
      "binc:spot:dash-btc",
      "cbse:spot:dash-btc",
      "cnex:spot:dash-btc",
      "yobt:spot:dash-btc",
      "bfnx:spot:usdt-usd",
      "bnus:spot:usdt-usd",
      "cbse:spot:usdt-usd",
      "gmni:spot:usdt-usd",
      "krkn:spot:usdt-usd",
      "stmp:spot:usdt-usd"
    ],
    "start_timestamp": 1683157800000,
    "end_timestamp": 1683158400000,
    "extrapolate_missing_values": true
  },
  "time": "2024-07-11T08:10:21.891Z",
  "timestamp": 1720685421891,
  "data": [
    {
      "timestamp": 1683158340000,
      "price": "49.263380298334226",
      "extrapolated": false
    },
    {
      "timestamp": 1683158280000,
      "price": "49.24160302106242",
      "extrapolated": false
    },
		/*...*/
	],
  "result": "success",
  "continuation_token": "AV2cWacBUPR8PvJTwoHZtPBUSEuqNYcv2iNgL96oZpT6MqqGc6ajQo7XM66wySCwViwNjs9C8Gu1xS2rRwGMrCT6rCRxFDCFnnKusyGFo34HkuY7Em7KqgpSzNADLhciV7w5UPeJrvm6cDgTnsaKVUgLMpj2ZioT",
  "next_url": "https://us.market-api.kaiko.io/v2/data/trades.v2/spot_exchange_rate/dash/usd?continuation_token=AV2cWacBUPR8PvJTwoHZtPBUSEuqNYcv2iNgL96oZpT6MqqGc6ajQo7XM66wySCwViwNjs9C8Gu1xS2rRwGMrCT6rCRxFDCFnnKusyGFo34HkuY7Em7KqgpSzNADLhciV7w5UPeJrvm6cDgTnsaKVUgLMpj2ZioT",
  "access": {
    "access_range": {
      "start_timestamp": 1262995200000,
      "end_timestamp": 2186006399000
    },
    "data_range": {
      "start_timestamp": null,
      "end_timestamp": null
    }
  }
}
```


---

# 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/analytics-solutions/kaiko-fair-market-value/established-assets/synthetic-price.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.