# Kaiko Best Execution

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

Get a market-representative execution benchmark that’s ideal for reporting and demonstrating execution efficiency to clients.\
\
The exchanges used in this calculation are vetted, meaning only those that are part of the [Kaiko Exchange Ranking](https://www.kaiko.com/products/rates-and-indices/exchange-ranking) are included. The best bids are aggregated over 10-second intervals and delivered every second. This means you receive the best bids and asks from the previous 10 seconds, updated every second.&#x20;

Read the full methodology [here](https://25446524.fs1.hubspotusercontent-eu1.net/hubfs/25446524/Factsheets%20and%20Methodologies/Best%20Execution%20Pricing%20Methodology.pdf).&#x20;

{% hint style="info" %}
Note that Kaiko Exchange Ranking is updated every quarter, so the exchanges used in the calculation may change.
{% endhint %}

## Endpoints

{% tabs %}
{% tab title="gRPC" %}

```url
gateway-v0-grpc.kaiko.ovh
```

{% endtab %}

{% tab title="http" %}

```url
gateway-v0-http.kaiko.ovh
```

{% endtab %}

{% tab title="API (testing)" %}

```url
https://gateway-v0-http.kaiko.ovh/api/stream/aggregated_quote_v2
```

{% endtab %}
{% endtabs %}

## Request parameters

<table><thead><tr><th width="184">Parameter</th><th width="387">Description</th><th>Examples</th><th data-type="checkbox">Mandatory?</th></tr></thead><tbody><tr><td><code>instrument_class</code></td><td>The class of the instrument(s) .<br><br>Explore instruments, codes and exchanges in the <a href="https://instruments.kaiko.com/#/instruments">Instrument Explorer</a> or <a data-mention href="/spaces/ltAbhvgBfrAWlpUnC7ys/pages/ypeWZ4XSK6XHt2hrySeK">/spaces/ltAbhvgBfrAWlpUnC7ys/pages/ypeWZ4XSK6XHt2hrySeK</a>. </td><td><code>spot</code></td><td>true</td></tr><tr><td><code>code</code></td><td>The Kaiko code for the instrument(s).<br><br>The class of the instrument(s) .<br><br>Explore instruments, codes and exchanges in the <a href="https://instruments.kaiko.com/#/instruments">Instrument Explorer</a> or <a data-mention href="/spaces/ltAbhvgBfrAWlpUnC7ys/pages/ypeWZ4XSK6XHt2hrySeK">/spaces/ltAbhvgBfrAWlpUnC7ys/pages/ypeWZ4XSK6XHt2hrySeK</a>. </td><td><code>btc-usd</code><br></td><td>true</td></tr><tr><td><code>includeUnvettedPrice</code></td><td>This parameter is set to <code>false</code> by default and not included in the code example. <br><br>Setting this field to <code>true</code> includes best bids and asks from exchanges that are not included in the Kaiko Exchange Ranking. <br><br>This parameter is helpful when an instrument you need is not covered by any exchange on the Kaiko Exchange ranking. It also serves as a backup for instruments covered by only one exchange, ensuring you still receive a price in case that exchange drops off the ranking when it's updated.<br><br>If you set this parameter <code>true</code>, the calculation will include all exchanges covered by Kaiko and this price will appear in a separate <code>unvetted</code> section of the response. </td><td><code>"includeUnvettedPrice": true</code></td><td>false</td></tr></tbody></table>

{% hint style="info" %}
**Configuring multiple instruments**

To configure multiple instruments in the same stream, provide the `code` as a comma separated list `eg btc-usd,eth-usd.`
{% endhint %}

## Response fields

<table><thead><tr><th width="223">Field</th><th width="537">Description</th></tr></thead><tbody><tr><td><code>aggregate</code></td><td>The time period over which the best bid or ask was calculated. This is always <code>10s</code>. </td></tr><tr><td><code>instrumentClass</code></td><td>The class of the instrument.</td></tr><tr><td><code>code</code></td><td>The instrument code.</td></tr><tr><td><code>eventType</code></td><td><code>BEST_BID</code> - The best bid from the period<br><code>BEST_ASK</code> - The best ask from the period</td></tr><tr><td><code>tsEvent</code></td><td>The timestamp the data became available in the Kaiko system.</td></tr><tr><td><code>price</code></td><td><p><strong>When <code>BEST-BID</code></strong>: The price per unit of the base that the buyer is willing to pay in the quote asset, represented as a scientific notation</p><p><br>Example: btc-usd</p><ul><li>base asset = btc</li><li>quote asset = usd<br><br><code>price</code>: <code>60555.00271626198</code></li></ul><p>For each unit of <code>btc</code>, the buyer is willing to pay <code>60555.00271626198</code> USD.<br></p><p><strong>When <code>BEST-ASK</code></strong>: The price per unit of the base that the seller is willing to accept in the quote asset, represented as a scientific notation</p><p><br>Example: btc-usd</p><ul><li>base asset = btc</li><li>quote asset = usd<br><br><code>price</code>: <code>60556.00224312413</code></li></ul><p>For each unit of <code>btc</code>, the buyer is willing to accept 60556.00224312413 USD.</p></td></tr><tr><td><code>volume</code></td><td><ul><li><strong>When <code>BEST-BID</code>:</strong> The quantity of the base asset that the buyer is willing to purchase</li><li><strong>When <code>BEST-ASK</code>:</strong> The quantity of the base asset the seller has available for sale</li></ul></td></tr></tbody></table>

## Request examples

{% tabs %}
{% tab title="Python" %}
{% @github-files/github-code-block url="<https://github.com/kaikodata/kaiko-sdk-examples/blob/master/python/code-example/aggregated_quote_request.py>" visible="false" %}
{% endtab %}

{% tab title="cURL" %}
**cURL requests are intended for testing purposes only.**

{% code overflow="wrap" %}

```url
curl -X POST "https://gateway-v0-http.kaiko.ovh/api/stream/aggregated_quote_v2" -H "accept: application/json" -H "X-Api-Key: $KAIKO_API_KEY" -H "Content-Type: application/json" -d "{\"instrumentClass\":\"spot\", \"code\": \"btc-usd\"}"
```

{% endcode %}
{% endtab %}

{% tab title="Other examples" %}
For more advanced users, you can access our full SDK [here](https://github.com/kaikodata/kaiko-sdk-examples/tree/master), where you'll find more coding languages, examples and guidance.
{% endtab %}
{% endtabs %}

## Response Example

```json
 "aggregate": "10s",
  "instrumentClass": "spot",
  "code": "btc-usd",
  "eventType": "BEST_ASK",
  "tsEvent": "2024-08-09T23:15:18.087882038Z",
  "vetted": {
    "price": "60556.00224312413",
    "volume": "0.2699806"
```


---

# 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/stream/analytics-solutions/kaiko-best-execution.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.