# Best bids and asks (top of book)

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

Top-of-Book is also known as best bids and asks. It offers the best bid and best asks on an order book, provided in real-time.

## 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/market_update_v1
```

{% endtab %}
{% endtabs %}

## Request parameters

<table><thead><tr><th width="246">Parameter</th><th width="387">Description</th><th>Examples</th></tr></thead><tbody><tr><td><code>instrumentCriteria</code></td><td><p>A <strong>nested object</strong> to configure following properties for your stream: </p><ul><li><code>exchange</code> (String) - The code(s) for the exchange(s)</li><li><code>instrument_class</code> (String) - The class(es) of the instrument(s) .</li><li><code>code (String) -</code> The Kaiko code for the instrument.</li></ul><p>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>. </p></td><td><p><code>cbse</code></p><p></p><p><code>spot</code></p><p></p><p><code>algo-btc</code><br><br></p></td></tr></tbody></table>

{% hint style="info" %}
**Configuring a wildcard**

A wildcard allows you to request all information we have on a specific instrument, class, or exchange in the same stream.\
\
Use a `*` in place of the relevant `exchange`, `instrument`, or `class` parameter. <br>

For example, the configuration below would deliver trades for BTC/USD across all exchanges where it’s supported:

`exchange: *`\
`class: spot`\
`instrument: btc-usd`
{% endhint %}

## Response fields

<table><thead><tr><th width="223">Field</th><th width="537">Description</th></tr></thead><tbody><tr><td><code>amount</code></td><td><ul><li>When <code>BEST-BID</code>: The quantity of the base asset that the buyer is willing to purchase</li><li>When <code>BEST-ASK</code>: The quantity of the base asset the seller has available for sale</li></ul></td></tr><tr><td><code>class</code></td><td>Instrument class, empty when not mapped.</td></tr><tr><td><code>code</code></td><td>Instrument code, empty when not mapped.</td></tr><tr><td><code>exchange</code></td><td>Instrument exchange code.</td></tr><tr><td><code>sequenceId</code></td><td>Sequence ID for event. Sortable in lexicographic order.</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: algo-btc</p><ul><li>base asset = algo</li><li>quote asset = btc<br><br><code>price</code>: <code>1.96e-06</code></li></ul><p>For each unit of Algo, the buyer is willing to pay <code>1.96e-06</code> BTC, equal to 0.00000196 when converted to a decimal number<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: algo-btc</p><ul><li>base asset = algo</li><li>quote asset = btc<br><br><code>price</code>: <code>1.97e-06</code></li></ul><p>For each unit of Algo, the buyer is willing to accept <code>1.97e-06</code> BTC, equal to 0.00000197 when converted to a decimal number</p></td></tr><tr><td><code>tsExchange</code></td><td><p>The timestamp provided by the exchange for the data. Where exchanges do not provide this data, we fill this with <code>tsCollection</code>. <br><br>This applies to the following exchanges: <br></p><ul><li>Bitfinex (<code>bfnx</code>) perpetual-future &#x26; spot</li><li>Binance US (<code>bnus</code>) spot</li><li>Bitvavo (<code>bvav</code>) spot</li></ul></td></tr><tr><td><code>tsCollection</code></td><td>The timestamp for when Kaiko received the data from the exchange.</td></tr><tr><td><code>tsEvent</code></td><td>The timestamp the data became available in the Kaiko system.</td></tr><tr><td><code>updateType</code></td><td><code>BEST_BID</code> - The current best bid<br><code>BEST_ASK</code> - The current best ask</td></tr><tr><td><code>additionalProperties</code></td><td>N/A. Always <code>null</code></td></tr><tr><td><code>id</code></td><td>N/A. Always <code>null</code></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/market_update_request_top_of_book.py>" visible="false" %}
{% endtab %}

{% tab title="Python (Replay)" %}
**This example demonstrates how to request historical data using replay. The maximum amount of data you can request for one replay cannot exceed a total of 24 hours in `hours`, `seconds`, and `minutes`.** \
\
**Replay data is available on a 72-hour rolling basis and should only be used to retrieve missed data. If full history is required, please use Rest API or CSV deployment methods.**

{% @github-files/github-code-block url="<https://github.com/kaikodata/kaiko-sdk-examples/blob/master/python/code-example/market_update_request_replay_top_of_book.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/market_update_v1" -H "accept: application/json" -H "X-Api-Key: $KAIKO_API_KEY" -H "Content-Type: application/json" -d "{ \"instrumentCriteria\": {  \"exchange\": \"cbse\",  \"instrumentClass\": \"spot",  \"code\": \"btx-usd\" }, \"commodities\": [\"SMUC_TOP_OF_BOOK\"]}"
```

{% 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
{
  "commodity": "SMUC_TOP_OF_BOOK",
  "amount": 6.835e-05,
  "class": "spot",
  "code": "btc-usd",
  "exchange": "cbse",
  "sequenceId": "cqr9icumv1b0afe4cg50",
  "price": 60763.73,
  "tsExchange": {
    "value": "2024-08-09T22:33:23.902971Z"
  },
  "tsCollection": {
    "value": "2024-08-09T22:33:23.916224545Z"
  },
  "tsEvent": "2024-08-09T22:33:23.978211823Z",
  "updateType": "BEST_BID",
  "id": "",
  "additionalProperties": {}
}

```


---

# 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/data-feeds/level-1-and-level-2-data/level-1-tick-level/best-bids-and-asks-top-of-book.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.