NAV Navbar
curl python

Introduction

Kaiko provides live and historical institutional quality market data for digital assets. Our service retrieves and validates millions of trades, derivative data and order books each day from the world's leading cryptocurrency exchanges to deliver robust and reliable market data to financial institutions globally. To learn more the product suites of Kaiko, please visit Kaiko's Data Dictionary. It shows schemas, methodologies, data samples, and additional information about all product suites that we provide and the delivery channels they are accessible through.

This is the documentation for the v2 of our REST API and CSV files.

Kaiko currently provides two HTTP APIs:

In addition, Kaiko also offers a Stream product for real-time, low latency data:

Change Log

2023-05-31

2023-05-17

Mapping update: Changes implemented for the following Instruments

2023-05-03

2023-04-24

2023-04-11

Mapping update: Changes implemented for the following Instruments

2023-04-06

Mapping update: Changes implemented for the following Instruments

2023-04-05

2023-04-04

2023-03-30

2023-03-29

Mapping update: Changes implemented for the following Assets

2023-03-27

Mapping update: Changes implemented for the following Assets

2023-03-23

Mapping update: Changes implemented for the following Assets

2023-02-21

Mapping update: Changes implemented for the following Assets

2023-02-06

2023-02-02

2023-01-26

2023-01-16

2023-01-12

2022-06-03

Mapping update: Changes implemented for the following Assets

2022-05-18

Mapping Update: FTXUSD deprecation

2022-04-29

2022-02-17

Mapping update

2022-02-15

Mapping update

2022-01-06

Mapping update

2021-12-28

Mapping update

2021-12-24

2021-12-20

2021-12-10

Mapping update

2021-12-08

Mapping update

API Input

When interacting with Kaiko HTTP APIs, you are expected to pass two information in a header:

curl --compressed -H 'Accept: application/json' 'https://<api_hostname>/<endpoint>'

Timestamp Input

All time parameters are in UTC and returned in the following ISO 8601 datetime format:

YYYY-MM-DDThh:mm:ss.sssZ

For example:

2017-12-17T13:35:24.351Z

The "T" separates the date from the time. The trailing "Z" indicates UTC time.

Exchange Code

We strive to use only one exchange code to cover all the instrument classes such as spot, futures and etc., but due to the legacy issues, we might use different exchange codes for one exchange. The following exchanges are the exchanges having more than one exchange codes for covering different instrument classes.

Exchange Exchange code Instrument Classes
Binance binc spot, future, perpetual future
Binance bopt option
Bybit bbit future, perpetual future, option
Bybit bbsp spot
Huobi huob spot
Huobi hbdm future, perpetual future, option
Kraken krkn spot
Kraken crfl future, perpetual future

Instrument Code

To access any detailed data such as trade, order book and etc, we need to provide an instrument code as an input for the REST API. Instruments follow a different naming conventions based on their instrument classes.

Spot

Spot names are normalized to have the same name format (base_asset-quote_asset) across exchanges. For instance, to access the data of Binance's spot btc/usdt, btc-usdt is the right instrument code.

Future

The instrument code for futures are not normalized. In other words, one should use the instrument names given by exchanges to download data of futures from Kaiko REST API endpoints. (e.g. Bitmex future: xbtu21, Binance future: btcusd220930)

Perpetual-future

Instruments of perpetual futures are normalized to have the same name format (base_asset-quote_asset) across exchanges. In other words, Deribit option: btc7oct2231000p)

Option

The instrument code for options are not normalized. In other words, one should use the instrument names given by exchanges to download data of options from Kaiko REST API endpoints. (e.g. Deribit option: btc7oct2231000p)

API Output

"taker_side_sell" Explained

You can find this field in the Trade API endpoint

For Centralized Exchange(CEX) taker_side_sell takes the value of true when a taker's sell order fills a maker's buy order and false when a taker's buy order fills a maker's sell order.

For Decentralized Exchanges (DEX) using Automatic Market Maker (AMM) protocols, the liquidity pool contract is considered the maker. The entity executing a transaction against the liquidity pool is the taker.

If an exchange does not appear below, it can be assumed that all data we provide is normalized correctly. For exchanges where we were unable to confirm as reporting data from either a taker or a maker's perspective, we have included the notation mapping from the exchange's trade direction field to our taker_side_sell field. This is necessary so that researchers who want to further study trade direction can make their own conclusions. For exchanges that classify trade direction differently or exclude the field entirely, we also include the notation mapping and a short explanation for how their variable differs.

Finally, we have made a couple of errors in classifying exchanges as "maker" or "taker", typically early on in the process of developing taker_side_sell. Rather than switch our trade reporting after years of data collection, we have simply marked exchanges where the inverse of the notation stated should be applied. For these exchanges, researchers should be aware that when taker_side_sell: false, the inverse should be assumed.

To read an in-depth explanation of this variable, read our post here.

Unconfirmed, Misclassified or Absent Trade Direction Field

Exchange Exchange Notation Kaiko taker_side_sell: true equivalent to: Comment
BTCBox "type": "buy" or "sell" inverse notation: "type": "sell" Inverse, but confirmed perspective from exchange.
Liquid (Quoine) taker_side: "buy" or "sell" inverse notation: taker_side: "buy" Inverse, but confirmed perspective from exchange.
Bithumb "type": "bid" or "ask" inverse notation: "type": "bid" Inverse, but confirmed perspective from exchange.
Coinone "is_ask": "0"(if seller is taker)/"1"(if seller is maker) inverse notation: "is_ask": "1" Inverse, confirmed from exchange but slightly different notation format
Bitstamp type: 0 (buy) or 1 (sell) type: 1 Unconfirmed perspective from exchange
Bit-Z "s": "buy" or "sell" "s": "sell" Unconfirmed perspective from exchange
EXX type": "buy" or "sell" type: "sell" Unconfirmed perspective from exchange
CEX.io2 type: "buy" or "sell" type: "sell" Unconfirmed perspective from exchange
Yobit "type": "bid" or "ask" "type": "bid" Unconfirmed perspective from exchange
itBit None Always returns true No buy/sell field
Korbit None Always returns null No buy/sell field
Coinflex None Always returns null No buy/sell field

Market Open and Close

Digital asset exchanges operate approximately 24x7x365. For daily aggregated data, the opening price is calculated as the first trade at or after 00:00:00 UTC. The closing price is calculated as the last trade prior to 00:00:00 UTC.

Timestamp Output

All timestamps are returned as millisecond Unix timestamps (the number of milliseconds elapsed since 1970-01-01 00:00:00.000 UTC). For metadata fields, times are also returned in millisecond-resolution ISO 8601 datetime strings in the same format as input for convenience.

Reference Data API

General

The base URL for the Reference Data Endpoints is: https://reference-data-api.kaiko.io/. Authentication is not required.

Assets

Request Example

curl --compressed -H 'Accept: application/json' 'https://reference-data-api.kaiko.io/v1/assets'

Response Example

{
  "result": "success",
  "data": [
    {
      "code": "btc",
      "name": "Bitcoin",
      "asset_class": "cryptocurrency",
      "asset_classes": [
        "cryptocurrency"
      ]
    },
    {
      "code": "bch",
      "name": "Bitcoin Cash",
      "asset_class": "cryptocurrency",
      "asset_classes": [
        "cryptocurrency"
      ]
    },
    {
      "code": "jpy",
      "name": "Japanese Yen",
      "asset_class": "fiat",
      "asset_classes": [
        "fiat"
      ]
    },
    /* ... */
  ]
}

This endpoint retrieves a list of supported assets.

HTTP request

GET https://reference-data-api.kaiko.io/v1/assets

Parameters

No parameters supported.

Fields

Field Description
asset_class The asset's primary asset class
asset_classes The asset's secondary asset classes
code Kaiko identifier for the asset.
name The asset name

Exchanges

Request Example

curl --compressed -H 'Accept: application/json' 'https://reference-data-api.kaiko.io/v1/exchanges'

Response Example


{
  "result": "success",
  "data": [
    {
      "code": "bfly",
      "name": "bitFlyer",
      "kaiko_legacy_slug": "bl"
    },
    {
      "code": "bfnx",
      "name": "Bitfinex",
      "kaiko_legacy_slug": "bf"
    }
    /* ... */
  ]
}

This endpoint retrieves a list of supported exchanges.

HTTP request

GET https://reference-data-api.kaiko.io/v1/exchanges

Parameters

No parameters supported.

Fields

Field Description
code Kaiko identifier for the exchange.
kaiko_legacy_slug Identifier used in delivery of aggregated data.
name The exchange name.

Instruments

Request Example

curl --compressed -H 'Accept: application/json' 'https://reference-data-api.kaiko.io/v1/instruments'

Response Example

{
  "result": "success",
  "data": [
    {
      "kaiko_legacy_exchange_slug": "bf",
      "trade_start_time": "2017-08-09T23:36:33.0000000Z",
      "trade_end_time": null,
      "code": "xmr-btc",
      "exchange_code": "bfnx",
      "exchange_pair_code": "XMRBTC",
      "base_asset": "xmr",
      "quote_asset": "btc",
      "kaiko_legacy_symbol": "xmrbtc",
      "class": "spot",
      "trade_start_timestamp": 1502321793000,
      "trade_end_timestamp": null,
      "trade_count": 2439870,
      "trade_compressed_size": 35037071
    },
    {
      "kaiko_legacy_exchange_slug": "kk",
      "trade_start_time": "2017-08-08T20:10:04.0000000Z",
      "trade_end_time": null,
      "code": "gno-eth",
      "exchange_code": "krkn",
      "exchange_pair_code": "GNOETH",
      "base_asset": "gno",
      "quote_asset": "eth",
      "kaiko_legacy_symbol": "gnoeth",
      "class": "spot",
      "trade_start_timestamp": 1502223004345,
      "trade_end_timestamp": null,
      "trade_count": 380822,
      "trade_compressed_size": 21119034
    },
    /* ... */
  ]
}

This endpoint retrieves a list of supported instruments. There are three possible cases regarding the trading period:

HTTP request

GET https://reference-data-api.kaiko.io/v1/instruments

Parameters

Parameter Required Description
exchange_code No Exchange code. See Exchanges Reference Data Endpoint.
base_asset No The desired base asset code. See Instruments Reference Data Endpoint.
quote_asset No The desired quote asset code. See Instruments Reference Data Endpoint.
code No Kaiko identifier for the instrument. Always base_asset-quote_asset for spot instruments.
kaiko_legacy_symbol No Kaiko legacy instrument symbol.
class No spot, future, perpetual-future,...
base_asset_class No Base asset class. See Instruments Reference Data Endpoint.
quote_asset_class No Quote asset class. See Instruments Reference Data Endpoint.
trade_start_timestamp No Starting time in ISO 8601 (inclusive).
trade_end_timestamp No Ending time in ISO 8601 (inclusive). Can also use "ongoing" to get ongoing instruments.
trade_count_min No Minimum number of trades.
trade_count_max No Maximum number of trades.
with_list_pools No true or false. For pairs traded on DEXs, provides the list of underlying pools to each instrument.
continuation_token No See Pagination.
page_size No Maximum number of records to return in one response
orderBy No Order results by a specifit field. See below for all possible values.
order No Return the data in ascending (1) or descending (-1) order

Possible values for orderBy: exchange_code, class, kaiko_legacy_symbol, trade_start_timestamp, trade_end_timestamp, trade_count, base_asset, quote_asset, code, trade_count_min, trade_count_max

All parameters, except for trade_count_min/max, trade_start/end_timestamp can be repeated in the URL to filter on all those value For example to get instruments for coinbase & deribit : /instruments?exchange_code=cbse&exchange_code=drbt

Fields

Field Description
base_asset1 Base asset.
class spot, future, perpetual-future,...
code2 Kaiko identifier for the instrument. Always base_asset-quote_asset for spot instruments.
exchange_code Exchange code.
exchange_pair_code2 Identifier for the instrument used by the exchange.
kaiko_legacy_exchange_slug Exchange kaiko_legacy_slug.
kaiko_legacy_symbol Identifier used in past deliveries of historical market data and Data Feed.
quote_asset1 Quote asset.
trade_start_time Time of first available trade in Kaiko's data set.
trade_start_timestamp Timestamp of first available trade in Kaiko's data set.
trade_end_time Time of last available trade in Kaiko's data set. null if instrument is still active
trade_end_timestamp Timestamp of last available trade in Kaiko's data set. null if instrument is still active
trade_count Total number of trades available through Kaiko Market Data API and Data Feed. For active pairs, this is an approximation.
trade_compressed_size Approximate size in bytes of all available trades in Kaiko Data Feed.
list_pools The list of the underlying pools to each instrument. (Only when arg with_list_pools=true is provided).

*1: Some exchanges may refer to base and quote currencies differently. Kaiko denotes prices in units of quote and volume in units of base, as reported by exchanges. * *2: Some exchanges reverse the ordering of base/quote in their codes. *

Pools

Request Example

curl --compressed -H 'Accept: application/json' 'https://reference-data-api.kaiko.io/v1/pools'

Response Example

{
  "result":"success",
  "data":[
    {"address":"0x52ea46506b9cc5ef470c5bf89f17dc28bb35d85c",
      "name":"usdt",
      "protocol":"curv",
      "type":"base pool",
      "fee":"0.0004",
      "tokens":[
        {"address":"0x5d3a536e4d6dbd6114cc1ead35777bab948e3643","symbol":"cDAI","decimals":"8"},
        {"address":"0x39aa39c021dfbae8fac545936693ac917d5e7563","symbol":"cUSDC","decimals":"8"},
        {"address":"0xdac17f958d2ee523a2206206994597c13d831ec7","symbol":"USDT","decimals":"6"}
      ],
      "underlyingTokens":[
        {"address":"0x6b175474e89094c44da98b954eedeac495271d0f","symbol":"DAI","decimals":"18"},
        {"address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","symbol":"USDC","decimals":"6"},
        {"address":"0xdac17f958d2ee523a2206206994597c13d831ec7","symbol":"USDT","decimals":"6"}
      ]
    },
    /* ... */
  ]
}

This endpoint retrieves a list of supported pools. The caracteristics of each pool differs depending on the protocol.

HTTP request

GET https://reference-data-api.kaiko.io/v1/pools

Parameters

Parameter Required Description
address No The pool's contract address.
protocol No The pool's protocol.
type No The pool's type. ex: Curve meta pool, Curve base pool, etc.
fee No The trading fees on this pool.
tokens No Filter on one or several tokens in the pool.
underlying_tokens No Filter on one or several tokens in the pool. Specific to Curve.

Fields

Field Description
address The pool's contract address.
name The pool's name as it is specified on-chain.
protocol The pool's protocol. ex:usp2,usp3, curv, blcr
type The pool's type. ex: Curve meta pool, Curve base pool, etc.
fee The trading fees on this pool.
tokens The pool's tokens.
underlyingTokens The underlying tokens in the pool. Specific to Curve.
tickSpacing The pool's tick spacing. Specific to Uniswap v3.
weights The weights of the different tokens in the pool. Specific to Balancer.

Market Data API

General

Base endpoints

The base URL for the Market Data Endpoints is regionalized. We are currently offering endpoints in the US and in Europe:

Usage

Authentication

Request Syntax

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://<api_hostname>/<endpoint>'

Each API lives under its own hostname. Clients must include an API key in the header of every request they make. The format is as follows:

X-Api-Key: <client-api-key>

Data versioning

Kaiko takes transparency and accountability very seriously. Therefore, our provided datasets are versioned. Dataset versioning is orthogonal to API versioning. Any potential breaking changes in results (e.g. semantical changes or corrections of historically incorrect data) will result in a new dataset version - no corrections or adjustments will be done in the dark. Addition of new data will not result in a new dataset version. Data is versioned on a per-base-data level.

The versioning is selected by selecting a base data set and a version. All current Market Data API endpoints take the commodity and data_version parameters.

By setting this to latest, you will get the most recent version. The returned version is always included in the query field and can be referred to if you would ever need to compare results, should we ever need to adjust historical data. Paginating over a request with version set to latest will preserve the current version across subsequent pagination requests.

We recommend using the most current version explicitly in production integrations as the latest label might move at any time to a breaking change. For the trades and order_book_snapshots commodities the latest version is currently v1

Response Example

{
  "timestamp": 1540474596175,
  "trade_id": "68024786",
  "price": "6559.84000000",
  "amount": "0.00646600",
  "taker_side_sell": true
}

Envelope

Response Example

{
  "result": "success",
  "time": "2018-06-14T17:19:40.303Z",
  "timestamp": 1528996780303,
  "query": { /* ... */ },
  "data": [ /* ... */ ],
  "access": {
    "access_range": {
      "start_timestamp": 1546300800000,
      "end_timestamp": 1577836800000
    },
    "data_range": {
      "start_timestamp": 1356998400000,
      "end_timestamp": 1577836800000
    }
  }
}

All API responses are in JSON format. A result field, with a value of success or error is returned with each request. In the event of an error, a message field will provide an error message.

An access object is also echoed back. It contains two ranges of timestamps:

Key Data type Description
access {} Time ranges of accesses.
data [] | {} Response result data.
message string Error message, if query was not successful.
query {} All handled query parameters echoed back.
result string success if query successful, error otherwise.
time string The current time at our endpoint.
timestamp long The current time at our endpoint.

Pagination

Pagination Example

{
  "result": "success",
  "time": "2018-06-14T17:19:40.303Z",
  "timestamp": 1528996780303,
  "query": {...},
  "data": [...],
  "continuation_token": "ab25lIG1vcmUgYmVlciBpcyBvbmUgbW9yZSBiZWVyIHRvbyBtYW55",
  "next_url": "https://<eu|us>.market-api.kaiko.io/v2/data/trades.v1/exchanges/bfnx/spot/btc-usd/trades?continuation_token=ab25lIG1vcmUgYmVlciBpcyBvbmUgbW9yZSBiZWVyIHRvbyBtYW55",
  "access": {...}
}

For queries that result in a larger dataset than can be returned in a single response, a continuation_token field is included. Calling the same endpoint again with the continuation_token query parameter added will return the next result page. For convenience, a next_url field is also included, containing a URL that can be called directly to get the next page. Paginated endpoints also takes a page_size parameter that specifies the maximum number of items that should be included in each response. Only the first call should include page_size, all subsequent calls should only use continuation_token. Paginating over a request with version set to latest will preserve the current version across subsequent pagination requests.

Parameters

Parameter Required Description
continuation_token No
page_size No Maximum number of records to return in one response

Errors

All API responses are in JSON format. A result field, with a value of success or error is returned with each request. In the event of an error, a message field will provide an error message.

HTTP error codes

The Kaiko platform API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized -- You are not authenticated properly. See Authentication.
403 Forbidden -- You don't have access to the requested resource.
404 Not Found
405 Method Not Allowed
406 Not Acceptable
429 Too Many Requests
500 Internal Server Error -- We had a problem with our service. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance.

Trade data

Real-time & Historical Trade Data

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/exchanges/bfnx/spot/btc-usd/trades'

Response Example

{
    "query": {
        "page_size": 100,
        "exchange": "bfnx",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "sort": "desc",
        "data_version": "v1",
        "commodity": "trades",
        "request_time": "2020-11-12T16:33:20.575Z"
    },
    "time": "2020-11-12T16:33:20.869Z",
    "timestamp": 1605198800869,
    "data": [
        {
            "timestamp": 1605198775855,
            "trade_id": "522419198",
            "price": "16026",
            "amount": "0.025",
            "taker_side_sell": true
        },
        {
            "timestamp": 1605198775031,
            "trade_id": "522419197",
            "price": "16026",
            "amount": "0.01",
            "taker_side_sell": true
        },
  /* ... */
  ],
  "result": "success",
  "continuation_token": "rbd28vrmb1cwaxfykuJBKAABhNi1Bfv1EY55P3QPSnYnm8VuX1LqLhA2d3yVfYgMKtfBYxJg7sHrkTfkQGysW23Lm9Lp9rsVpVk2Esmgz9VQZvNE4xWN8hh3LgLrCa7ty4B3YGCwtH",
  "next_url": "https://us.market-api.kaiko.io/v2/data/trades.v1/exchanges/bfnx/spot/btc-usd/trades?continuation_token=rbd28vrmb1cwaxfykuJBKAABhNi1Bfv1EY55P3QPSnYnm8VuX1LqLhA2d3yVfYgMKtfBYxJg7sHrkTfkQGysW23Lm9Lp9rsVpVk2Esmgz9VQZvNE4xWN8hh3LgLrCa7ty4B3YGCwtH",
  "access": {
    "access_range": {
      "start_timestamp": null,
      "end_timestamp": null
    },
    "data_range": {
      "start_timestamp": null,
      "end_timestamp": null
    }
  }
}

This endpoint retrieves trades for an instrument on a specific exchange. Trades are sorted by time, in a descendingly order unless it is specified otherwise. Note that taker_side_sell can be null in the cases where this information was not available at collection.

HTTP request

GET https://{region}.market-api.kaiko.io/v2/data/trades.v1/exchanges/{exchange}/{instrument_class}/{instrument}/trades{?start_time,end_time,page_size,continuation_token}

Parameters

Parameter Required Description Example
region Yes Choose between eu and us. No difference yet. eu
exchange1 Yes Exchange code. See Exchanges Reference Data Endpoint. okex
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
start_time2 No Starting time in ISO 8601 (inclusive).
end_time2 No Ending time in ISO 8601 (exclusive).
page_size2 No See Pagination (min: 1, default: 100, max: 100000).
continuation_token No See Pagination.

Fields

Field Description
timestamp The timestamp provided by the exchange or the collection timestamp in Unix Timestamp (in milliseconds)
trade_id Unique trade ID (unique to the exchange). In case the exchange does not provide an ID, we generate it ourselves.
price Price displayed in quote currency.
amount Quantity of asset bought or sold (can be in base_asset, quote_asset or the number of contracts).
taker_side_sell See Taker Side Sell

1: This endpoint serves both data from centralized as well as decentralized exchanges. 2: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Order Book data

Order Book Snapshots: Full

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/snapshots/full?slippage=100000&page_size=10&limit_orders=2&slippage_ref=best'

Response Example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 100000,
        "limit_orders": 2,
        "slippage_ref": "best",
        "sort": "desc",
        "metric": "full",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:10:06.320Z"
    },
    "time": "2020-05-26T14:10:06.418Z",
    "timestamp": 1590502206418,
    "data": [
        {
            "poll_timestamp": 1590502155757,
            "poll_date": "2020-05-26T14:09:15.757Z",
            "timestamp": null,
            "bid_volume0_1": "46.595",
            "bid_volume0_2": "110.570",
            "bid_volume0_3": "167.920",
            "bid_volume0_4": "198.416",
            "bid_volume0_5": "243.554",
            "bid_volume0_6": "346.467",
            "bid_volume0_7": "354.090",
            "bid_volume0_8": "359.058",
            "bid_volume0_9": "381.422",
            "bid_volume1": "384.066",
            "bid_volume1_5": "467.014",
            "bid_volume2": "522.441",
            "bid_volume4": "918.911",
            "bid_volume6": "1187.306",
            "bid_volume8": "1187.306",
            "bid_volume10": "1187.306",
            "ask_volume0_1": "13.158",
            "ask_volume0_2": "40.072",
            "ask_volume0_3": "71.129",
            "ask_volume0_4": "179.463",
            "ask_volume0_5": "259.140",
            "ask_volume0_6": "266.315",
            "ask_volume0_7": "324.288",
            "ask_volume0_8": "353.024",
            "ask_volume0_9": "376.738",
            "ask_volume1": "405.965",
            "ask_volume1_5": "467.665",
            "ask_volume2": "506.326",
            "ask_volume4": "862.843",
            "ask_volume6": "1322.553",
            "ask_volume8": "1428.856",
            "ask_volume10": "1428.856",
            "spread": "0.1",
            "mid_price": "8819.95",
            "ask_slippage": "0.0002782477139043083900226757369614512",
            "bid_slippage": "0.0",
            "asks": [
                {
                    "amount": "5.914",
                    "price": "8820"
                },
                {
                    "amount": "0.08",
                    "price": "8821"
                }
            ],
            "bids": [
                {
                    "amount": "11.814",
                    "price": "8819.9"
                },
                {
                    "amount": "4.197",
                    "price": "8819.8"
                }
            ]
        },
      /* ... */
],
    "result": "success",
    "continuation_token": "Ehad6pjoEpvpZSkvbtsyx8WxTj9vgc4s5VSow1USG8pXP1UGFSxSF7fTacxA54rYoqebnMTdCpE3ZxB3nSTM5CYNModkKRASDWMHymPFHNXnGL73RdkHSVUv6UYa4YwrRinH7JbwRqbB5HwmZdxWaonnaVkeZZc1wZiuK2oR4ePQdotGEnvKY8spPjYwnX8s3D6w1bCqZqL6ENaNH5Pa6b53MdbmyQBjE8F",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/snapshots/full?continuation_token=Ehad6pjoEpvpZSkvbtsyx8WxTjvgc4s5VSow1USG8pXP1UGFSxSF7fTacxA54rYoqebnMTdCpE3ZxB3nSTM5CYNModkKRASDWMHymPFHNXnGL73RdkHSVUv6UYa4YwrRinH7JbwRqbB5HwmZdxWaonnaVkeZZc1wZiuK2oR4ePQdotGEnvKY8spPjYwnX8s3D6w1bCqZqL6ENaNH5Pa6b53MdbmyQBjE8F",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint gives access to one month of historical 10% order book snapshots. The full endpoint returns all the following order book data: the snapshot itself (bids and asks), the depth of the order book (the cummulative volume of the base asset at 0.1%, 0.2%, 0.3%, 0.4%, 0.5%, 0.6%, 0.7%, 0.8%, 0.9%, 1%, 1.5%, 2%, 4%, 6%, 8% and 10% from the best ask and best bid respectively), the spread, the mid price and, when the slippage parameter is not empty, the percentage of slippage for a given order size, either calculated from the best bid/ask or calculated from the mid price. All data is returned in descending order.

HTTP request

GET https://us.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/snapshots/full{?start_time,end_time,page_size,continuation_token,slippage,slippage_ref,orders,limit_orders}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange Yes Exchange code. See Exchanges Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
limit_orders No Number of orders to return on bid and ask side per snapshot. To retreive the best bid/ask, set this parameter to 1 (default: 10)
page_size1 No Number of snapshots to return. See Pagination (default: 10, max: 100).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc
start_time1 No Starting time in ISO 8601 (inclusive).
slippage No Order size (in quote asset) for which to calculate the percentage of slippage. Default: 0. When null is returned, not enough volume is present on the order book to execute the order.
slippage_ref No Price point for which to calculate slippage from. Either from the mid price (mid_price) or from the best bid/ask (best). Default: mid_price.

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Fields

Field Description
poll_timestamp The timestamp at which the raw data snapshot was taken.
poll_date The date at which the raw data snapshot was taken.
timestamp The timestamp provided by the exchange. null when not provided.
bid_volume_x The volume of bids placed within 0 and x% of the midprice.
ask_volume_x The volume of asks placed within 0 and x% of the midprice.
spread The difference between the best bid and the best ask at the time the snapshot was taken.
mid_price The mid price between the best bid and the best ask.
ask_slippage The percentage price slippage for a market buy order placed at the time that the order book snapshot was taken.
bid_slippage The percentage price slippage for a market sell order placed at the time that the order book snapshot was taken.
asks The sell orders in the snapshot. If the limit_oders parameter is used, this will be reflected here. amount is the quantity of asset to sell, displayed in the base currency. price is displayed in the quote currency.
bids The buy orders in the snapshot. If the limit_oders parameter is used, this will be reflected here. amount is the quantity of asset to buy, displayed in the base currency. price is displayed in the quote currency.

Order Book Snapshots: Raw

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/snapshots/raw?page_size=10&limit_orders=2'

Response example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 0,
        "limit_orders": 2,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "metric": "raw",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:13:08.823Z"
    },
    "time": "2020-05-26T14:13:08.899Z",
    "timestamp": 1590502388899,
    "data": [
        {
            "poll_timestamp": 1590502335760,
            "poll_date": "2020-05-26T14:12:15.760Z",
            "timestamp": null,
            "asks": [
                {
                    "amount": "12",
                    "price": "8830"
                },
                {
                    "amount": "3.67",
                    "price": "8832.9"
                }
            ],
            "bids": [
                {
                    "amount": "13.316",
                    "price": "8829.9"
                },
                {
                    "amount": "0.097",
                    "price": "8829.4"
                }
            ]
        }
      /* ... */         
    ],
    "result": "success",
    "continuation_token": "Z8FjTagUoHd3UCqMvqmRJXlwzbTxSnSXpxxZpHWNCmrsrcnhSpMG2gdcmFKRPd88",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/cbse/spot/btc-usd/snapshots/raw?continuation_token=Z8FjTagUoHd3UCqMvqmRJXlwzbTxSnSXpxxZpHWNCmrsrcnhSpMG2gdcmFKRPd88",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint is identical to the Full endpoint but only returns the raw snapshots of bids and asks without any additional metrics. The Full specific parameters (such as slippage and slippage_ref) are disabled but won't yield any errors when used. All data is returned in descending order.

HTTP request

GET https://us.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/snapshots/raw{?start_time,end_time,page_size,continuation_token,limit_orders}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange Yes Exchange code. See Exchanges Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
limit_orders No Number of orders to return on bid and ask side per snapshot. To retreive the best bid/ask, set this parameter to 1 (default: 10)
page_size1 No Number of snapshots to return. See Pagination (default: 10, max: 100).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc
start_time1 No Starting time in ISO 8601 (inclusive).

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Fields

Field Description
poll_timestamp The timestamp at which the raw data snapshot was taken.
poll_date The date at which the raw data snapshot was taken.
timestamp The timestamp provided by the exchange. null when not provided.
asks The sell orders in the snapshot. If the limit_oders parameter is used, this will be reflected here. amount is the quantity of asset to sell, displayed in the base currency. price is displayed in the quote currency.
bids The buy orders in the snapshot. If the limit_oders parameter is used, this will be reflected here. amount is the quantity of asset to buy, displayed in the base currency. price is displayed in the quote currency.

Order Book Snapshots: Depth

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/snapshots/depth?page_size=10'

Response Example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 0,
        "limit_orders": 0,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "metric": "depth",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:29:44.757Z"
    },
    "time": "2020-05-26T14:29:44.816Z",
    "timestamp": 1590503384816,
    "data": [
        {
            "poll_timestamp": 1590503344916,
            "poll_date": "2020-05-26T14:29:04.916Z",
            "timestamp": null,
            "bid_volume0_1": "37.606",
            "bid_volume0_2": "102.304",
            "bid_volume0_3": "141.907",
            "bid_volume0_4": "177.446",
            "bid_volume0_5": "203.634",
            "bid_volume0_6": "218.450",
            "bid_volume0_7": "283.128",
            "bid_volume0_8": "293.533",
            "bid_volume0_9": "321.986",
            "bid_volume1": "348.213",
            "bid_volume1_5": "405.080",
            "bid_volume2": "444.782",
            "bid_volume4": "837.949",
            "bid_volume6": "1110.065",
            "bid_volume8": "1110.065",
            "bid_volume10": "1110.065",
            "ask_volume0_1": "7.401",
            "ask_volume0_2": "13.744",
            "ask_volume0_3": "58.917",
            "ask_volume0_4": "131.104",
            "ask_volume0_5": "165.971",
            "ask_volume0_6": "193.786",
            "ask_volume0_7": "257.001",
            "ask_volume0_8": "286.384",
            "ask_volume0_9": "312.040",
            "ask_volume1": "319.040",
            "ask_volume1_5": "382.927",
            "ask_volume2": "475.467",
            "ask_volume4": "909.144",
            "ask_volume6": "1229.664",
            "ask_volume8": "1323.505",
            "ask_volume10": "1323.505"
        },
      /* ... */
],
    "result": "success",
    "continuation_token": "Z8FjYwcAjf7MZEG382e5MpmZx7wkuziQTyy2k5fVgSrcF8jAYqUpRgPH5cbQ9MhJiFaxGRbwiERMp3cWhXJshy",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/cbse/spot/btc-usd/snapshots/depth?continuation_token=Z8FjYwcAjf7MZEG382e5MpmZx7wkuziQTyy2k5fVgSrcF8jAYqUpRgPH5cbQ9MhJiFaxGRbwiERMp3cWhXJshy",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint is identical to the Full endpoint but only returns metrics on the depth of the order book (the cummulative volume of the base asset at 0.1%, 0.2%, 0.3%, 0.4%, 0.5%, 0.6%, 0.7%, 0.8%, 0.9%, 1%, 1.5%, 2%, 4%, 6%, 8% and 10% from the mid price) per snapshot. The Full specific parameters (such as slippage, slippage_ref and limit_orders) are disabled but won't yield any errors when used. All data is returned in descending order.

HTTP request

GET https://us.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/snapshots/depth{?start_time,end_time,page_size,continuation_token}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange Yes Exchange code. See Exchanges Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
page_size1 No Number of snapshots to return data for. See Pagination (default: 10, max: 100).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc
start_time1 No Starting time in ISO 8601 (inclusive).

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Fields

Field Description
poll_timestamp The timestamp at which the raw data snapshot was taken.
poll_date The date at which the raw data snapshot was taken.
timestamp The timestamp provided by the exchange. null when not provided.
bid_volume_x The volume of bids placed within 0 and x% of the midprice.
ask_volume_x The volume of asks placed within 0 and x% of the midprice.

Order Book Snapshots: Slippage

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/snapshots/slippage?end_time=2019-12-09T00:00:00Z&slippage_ref=best&start_time=2019-12-01T00:00:00Z&slippage=1000000&page_size=10'

Response Example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "slippage": 100000,
        "limit_orders": 0,
        "slippage_ref": "best",
        "sort": "desc",
        "metric": "slippage",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:42:17.053Z"
    },
    "time": "2020-05-26T14:42:17.123Z",
    "timestamp": 1590504137123,
    "data": [
        {
            "poll_timestamp": 1590504124917,
            "poll_date": "2020-05-26T14:42:04.917Z",
            "timestamp": null,
            "ask_slippage": "0.0001057219873253085790064266041007855",
            "bid_slippage": "0.0001581287020485902479395059349031256"
        },
        {
            "poll_timestamp": 1590504075786,
            "poll_date": "2020-05-26T14:41:15.786Z",
            "timestamp": null,
            "ask_slippage": "0.00001534073225141691226479256404443437",
            "bid_slippage": "0.0002555856086571344339622641509433962"
        },
      /* ... */
    ],
    "result": "success",
    "continuation_token": "Z8Fj1yUWjj3uvv1U2d8fASeGLm4jZ4iHCopdsZLKUyDJE8KrBaDXwQQWXHJQxm",
    "next_url": "https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/cbse/spot/btc-usd/snapshots/slippage?continuation_token=Z8Fj1yUWjj3uvv1U2d8fASeGLm4jZ4iHCopdsZLKUyDJE8KrBaDXwQQWXHJQxm",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint is identical to the Full endpoint but only returns slippage for a given order size, either calculated from the best bid/ask or calculated from the mid price. The Full and Raw specific parameter limit_orders is disabled but won't yield any errors when used. All data is returned in descending order.

HTTP request

GET https://us.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/snapshots/slippage{?start_time,end_time,page_size,continuation_token,slippage,slippage_ref}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange Yes Exchange code. See Exchanges Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
page_size1 No Number of snapshots to return data for. See Pagination (default: 10, max: 100).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc
start_time1 No Starting time in ISO 8601 (inclusive).
slippage No Order size (in quote asset) for which to calculate the percentage of slippage. Default: 0. When null is returned, not enough volume is present on the order book to execute the order.
slippage_ref No Price point for which to calculate slippage from. Either from the mid price (mid_price) or from the best bid/ask (best). Default: mid_price.

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Fields

Field Description
poll_timestamp The timestamp at which the raw data snapshot was taken.
poll_date The date at which the raw data snapshot was taken.
timestamp The timestamp provided by the exchange. null when not provided.
ask_slippage The percentage price slippage for a market buy order placed at the time that the order book snapshot was taken.
bid_slippage The percentage price slippage for a market sell order placed at the time that the order book snapshot was taken.

Order Book Aggregations: Full

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/ob_aggregations/full?page_size=10&slippage=100000&interval=1h&start_time=2019-12-04T00:00:00Z&end_time=2019-12-06T00:00:00Z'

Response Example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1h",
        "slippage": 100000,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "aggregation": "full",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:46:00.561Z"
    },
    "time": "2020-05-26T14:46:03.776Z",
    "timestamp": 1590504363776,
    "data": [
        {
            "poll_timestamp": 1590501600000,
            "ask_slippage": "0.00032766083806437735",
            "bid_slippage": "0.0002206511273162024",
            "bid_volume0_1": "31.751239130434783",
            "bid_volume0_2": "87.33763043478261",
            "bid_volume0_3": "139.32403260869566",
            "bid_volume0_4": "177.62314130434783",
            "bid_volume0_5": "206.71984782608695",
            "bid_volume0_6": "251.4888043478261",
            "bid_volume0_7": "287.1503043478261",
            "bid_volume0_8": "317.3515869565217",
            "bid_volume0_9": "335.79671739130436",
            "bid_volume1": "352.03117391304346",
            "bid_volume1_5": "419.0988260869565",
            "bid_volume2": "470.6285",
            "bid_volume4": "859.7884347826086",
            "bid_volume6": "1134.0595760869564",
            "bid_volume8": "1134.4657173913045",
            "bid_volume10": "1134.4657173913045",
            "ask_volume0_1": "21.558043478260867",
            "ask_volume0_2": "37.20532608695652",
            "ask_volume0_3": "78.02648913043478",
            "ask_volume0_4": "143.83753260869565",
            "ask_volume0_5": "192.98572826086954",
            "ask_volume0_6": "235.31961956521738",
            "ask_volume0_7": "280.5659565217391",
            "ask_volume0_8": "309.4857717391304",
            "ask_volume0_9": "327.8923152173913",
            "ask_volume1": "341.79707608695657",
            "ask_volume1_5": "411.3568043478261",
            "ask_volume2": "475.6048586956521",
            "ask_volume4": "885.1007826086956",
            "ask_volume6": "1263.1216413043478",
            "ask_volume8": "1364.2838369565218",
            "ask_volume10": "1364.2838369565218",
            "mid_price": "8830.427717391303",
            "spread": "1.175"
        }
      /* ... */
    ],
    "result": "success",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint gives access to one month of historical 10% order book aggregated data. It returns metrics on the average depth of the order book (the cummulative volume of the base asset at 0.1%, 0.2%, 0.3%, 0.4%, 0.5%, 0.6%, 0.7%, 0.8%, 0.9%, 1%, 1.5%, 2%, 4%, 6%, 8% and 10% from the mid price), the average spread, the average mid price and, when the slippage parameter is not empty, the average percentage of slippage for a given order size, either calculated from the best bid/ask or calculated from the mid price for a given interval. For each interval, the aggregates are calculated by taking the average metrics of each snapshot within that interval. For example, the aggregated 1 hour spread is calculated by taking all spreads of each snapshot within an hour and calculating the average. All data is returned in descending order.

HTTP request

GET https://us.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/ob_aggregations/full{?start_time,end_time,page_size,continuation_token,slippage,slippage_ref,interval}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange Yes Exchange code. See Exchanges Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
interval No Interval period. Default 1h.
page_size1 No Number of snapshots to return data for. See Pagination (default: 10, max: 100).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc
start_time1 No Starting time in ISO 8601 (inclusive).
slippage No Order size (in quote asset) for which to calculate the percentage of slippage. Default: 0. When null is returned, not enough volume is present on the order book to execute the order.
slippage_ref No Price point for which to calculate slippage from. Either from the mid price (mid_price) or from the best bid/ask (best). Default: mid_price.

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Field Description
poll_timestamp The timestamp at which the interval begins.
bid_volume_x The average volume of bids placed within 0 and x% of the midprice over a specified interval.
ask_volume_x The average volume of asks placed within 0 and x% of the midprice over a specified interval.
spread The average difference between the best bid and the best ask over a specified interval.
mid_price The average mid price between the best bid and the best ask over a specified interval
ask_slippage The average percentage of price slippage for a market buy order over a specified interval.
bid_slippage The average percentage of price slippage for a market sell order over a specified interval.

Order Book Aggregations: Depth

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/ob_aggregations/depth?page_size=10&interval=1h'

Response Example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1h",
        "slippage": 0,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "aggregation": "depth",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T14:58:55.582Z"
    },
    "time": "2020-05-26T14:58:56.395Z",
    "timestamp": 1590505136395,
    "data": [
        {
            "poll_timestamp": 1590501600000,
            "bid_volume0_1": "31.31635593220339",
            "bid_volume0_2": "90.78996610169492",
            "bid_volume0_3": "144.16212711864407",
            "bid_volume0_4": "182.9676525423729",
            "bid_volume0_5": "219.1858220338983",
            "bid_volume0_6": "263.02182203389833",
            "bid_volume0_7": "296.666686440678",
            "bid_volume0_8": "322.5334237288136",
            "bid_volume0_9": "340.6282881355932",
            "bid_volume1": "356.4558474576271",
            "bid_volume1_5": "427.1106949152542",
            "bid_volume2": "475.76238135593223",
            "bid_volume4": "863.1048559322035",
            "bid_volume6": "1137.2281271186441",
            "bid_volume8": "1137.5447796610172",
            "bid_volume10": "1137.5447796610172",
            "ask_volume0_1": "22.772533898305085",
            "ask_volume0_2": "36.96916101694915",
            "ask_volume0_3": "78.57454237288135",
            "ask_volume0_4": "144.87783898305085",
            "ask_volume0_5": "195.61884745762714",
            "ask_volume0_6": "237.96824576271186",
            "ask_volume0_7": "282.3425338983051",
            "ask_volume0_8": "314.0606779661017",
            "ask_volume0_9": "330.76757627118644",
            "ask_volume1": "344.3153644067797",
            "ask_volume1_5": "413.4595423728814",
            "ask_volume2": "475.48172033898305",
            "ask_volume4": "886.8459152542373",
            "ask_volume6": "1272.5998644067795",
            "ask_volume8": "1371.7920847457626",
            "ask_volume10": "1371.7920847457626"
        },
      /* ... */
    ],
    "result": "success",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint is identical to the Full endpoint but only returns metrics on average the depth of the order book (the cummulative volume of the base asset at 0.1%, 0.2%, 0.3%, 0.4%, 0.5%, 0.6%, 0.7%, 0.8%, 0.9%, 1%, 1.5%, 2%, 4%, 6%, 8% and 10% from the mid price) per snapshot. For each interval, the aggregates are calculated by taking the average metrics of each snapshot within that interval. For example, the aggregated 1 hour spread is calculated by taking all spreads of each snapshot within an hour and calculating the average. The Full specific parameters (such as slippage, slippage_ref) are disabled but won't yield any errors when used. All data is returned in descending order.

HTTP request

GET https://us.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/ob_aggregations/depth{?start_time,end_time,page_size,continuation_token,interval}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange Yes Exchange code. See Exchanges Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
interval No Interval period. Default 1h.
page_size1 No Number of snapshots to return data for. See Pagination (default: 10, max: 100).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc
start_time1 No Starting time in ISO 8601 (inclusive).

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Fields

Field Description
poll_timestamp The timestamp at which the interval begins
bid_volume_x The average volume of bids placed within 0 and x% of the midprice over a specified interval.
ask_volume_x The average volume of asks placed within 0 and x% of the midprice over a specified interval.

Order Book Aggregations: Slippage

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/order_book_snapshots.v1/exchanges/krkn/spot/btc-usd/ob_aggregations/slippage?page_size=10&slippage=100000&interval=1h'

Response Example

{
    "query": {
        "page_size": 10,
        "exchange": "krkn",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1h",
        "slippage": 100000,
        "slippage_ref": "mid_price",
        "sort": "desc",
        "aggregation": "slippage",
        "data_version": "v1",
        "commodity": "order_book_snapshots",
        "request_time": "2020-05-26T15:07:06.840Z"
    },
    "time": "2020-05-26T15:07:07.260Z",
    "timestamp": 1590505627260,
    "data": [
        {
            "poll_timestamp": 1590505200000,
            "ask_slippage": "0.00012513598764468878",
            "bid_slippage": "0.0003678539692963374"
        },
        {
            "poll_timestamp": 1590501600000,
            "ask_slippage": "0.00030969034268815156",
            "bid_slippage": "0.00024353107110561094"
        },
      /* ... */
    ],
    "result": "success",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint is identical to the Full endpoint but only returns the average slippage for a given order size, either calculated from the best bid/ask or calculated from the mid price. For each interval, the aggregates are calculated by taking the average metrics of each snapshot within that interval. For example, the aggregated 1 hour spread is calculated by taking all spreads of each snapshot within an hour and calculating the average. All data is returned in descending order.

HTTP request

GET https://us.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/ob_aggregations/depth{?start_time,end_time,page_size,continuation_token,interval,slippage,slippage_ref}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange2 Yes Exchange code. See Exchanges Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
interval No Interval period. Default 1h.
page_size1 No Number of snapshots to return data for. See Pagination (default: 10, max: 100).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc
start_time1 No Starting time in ISO 8601 (inclusive).
slippage No Order size (in quote asset) for which to calculate the percentage of slippage. Default: 0. When null is returned, not enough volume is present on the order book to execute the order.
slippage_ref No Price point for which to calculate slippage from. Either from the mid price (mid_price) or from the best bid/ask (best). Default: mid_price.

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token. 2: This endpoint serves both data from centralized as well as decentralized exchanges.

Fields

Field Description
poll_timestamp The timestamp at which the interval begins.
ask_slippage The average percentage of price slippage for a market buy order over a specified interval.
bid_slippage The average percentage of price slippage for a market sell order over a specified interval.

Aggregates

OHLCV (Candles)

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/exchanges/cbse/spot/btc-usd/aggregations/ohlcv'

Response Example

{
    "query": {
        "page_size": 100,
        "exchange": "cbse",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1d",
        "sort": "desc",
        "aggregation": "ohlcv",
        "data_version": "v1",
        "commodity": "trades",
        "request_time": "2020-05-26T17:25:56.221Z"
    },
    "time": "2020-05-26T17:26:00.160Z",
    "timestamp": 1590513960160,
    "data": [
        {
            "timestamp": 1590451200000,
            "open": "8900.0",
            "high": "9016.99",
            "low": "8694.23",
            "close": "8811.36",
            "volume": "9014.60281966"
        },
        {
            "timestamp": 1590364800000,
            "open": "8715.69",
            "high": "8977.0",
            "low": "8632.93",
            "close": "8899.31",
            "volume": "12091.06145914"
        },
  /* ... */
  ],
  "result": "success",
  "continuation_token": "rbd2bcDp35GmDscQbvZ9YzQHZJkT3jdeFx9fSBDdVmcCZaHvQRTCTfmfQ6QCrvDNp5ciRRuGPTedVL5LMZv1qmSXhRpZFbpvBW2uA62RSYpfJ1hVykJKZfhtmXXrxz",
  "next_url": "https://us.market-api.kaiko.io/v2/data/trades.v1/exchanges/krkn/spot/btc-usd/aggregations/ohlcv?continuation_token=rbd2bcDp35GmDqdfaz3fZJkT3jdeFx9fSBDdVmcCZaHvQRTCTfmfQ6QCrvDNp5ciRRuGPTedVL5LMZv1qmSXhRpZFbpvBW2uA62RSYpfJ1hVykJKZfhtmXXrxz",
  "access": {
    "access_range": {
      "start_timestamp": null,
      "end_timestamp": null
    },
    "data_range": {
      "start_timestamp": null,
      "end_timestamp": null
    }
  }
}

This endpoint retrieves the OHLCV history for an instrument on an exchange. The interval parameter is suffixed with s, m, h or d to specify seconds, minutes, hours or days, respectively. By making use of the sort parameter, data can be returned in ascending asc or descending desc order.

HTTP request

GET https://<eu|us>.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/aggregations/ohlcv{?interval,start_time,end_time,page_size,continuation_token}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange2 Yes Exchange code.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
interval No Interval period. Default 1d.
page_size1 No See Pagination (min: 1, default: 100, max: 100000).
start_time1 No Starting time in ISO 8601 (inclusive).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token. 2: This endpoint serves both data from centralized as well as decentralized exchanges.

Fields

Field Description
timestamp Timestamp at which the interval begins.
open Opening price of interval. null when no trades reported.
high Highest price during interval. null when no trades reported.
low Lowest price during interval. null when no trades reported.
close Closing price of interval. null when no trades reported.
volume Volume traded in interval. 0 when no trades reported.

Intervals

Any arbitrary value between one second and one day can be used as an interval, as long as it sums up to 1 day. The suffixes are s (second), m (minute), h (hour) and d (day).

VWAP (Prices)

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/exchanges/cbse/spot/btc-usd/aggregations/vwap'

Response Example

{
    "query": {
        "page_size": 100,
        "exchange": "cbse",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1d",
        "sort": "desc",
        "aggregation": "vwap",
        "data_version": "v1",
        "commodity": "trades",
        "request_time": "2020-11-12T16:52:36.988Z"
    },
    "time": "2020-11-12T16:52:37.114Z",
    "timestamp": 1605199957114,
    "data": [
        {
            "timestamp": 1605139200000,
            "price": "15879.385939106618"
        },
        {
            "timestamp": 1605052800000,
            "price": "15664.643871798791"
        },
    /* ... */
  ],
  "result": "success",
  "continuation_token": "55qoNvASfrVdCIjrF8Ygw6TVJ4yamzUyeL9QXAmvWZZur3iaKoPcVBW1V4unNJi2zMjojbsYr9Pgt9XFCUpnAiuBiECm8X4cedvYc9t2WxHXnHKjgAp2wRAeV8ZPUSj8WNgpWTCBVymGaQZPj3oMDZwVeCPyuTLFdVPfTXVjZA94BtHeBmghoPv92JtWxN3yRvCkrw79hJBu",
  "next_url": "https://<eu|us>.market-api.kaiko.io/v2/data/trades.v1/exchanges/cbse/spot/btc-usd/aggregations/vwap?continuation_token=55qoNvASfrVdCIjrF8Ygw6TVJ4yamzUyeL9QXAmvWZZur3iaKoPcVBW1V4unNJi2zMjojbsYr9Pgt9XFCUpnAiuBiECm8X4cedvYc9t2WxHXnHKjgAp2wRAeV8ZPUSj8WNgpWTCBVymGaQZPj3oMDZwVeCPyuTLFdVPfTXVjZA94BtHeBmghoPv92JtWxN3yRvCkrw79hJBu",
  "access": {
    "access_range": {
      "start_timestamp": 1546300800000,
      "end_timestamp": 1577836800000
    },
    "data_range": {
      "start_timestamp": 1417391000000,
      "end_timestamp": 1577836800000
    }
  }
}

This endpoint retrieves aggregated VWAP (volume-weighted average price) history for an instrument on an exchange. The interval parameter is suffixed with s, m, h or d to specify seconds, minutes, hours or days, respectively. By making use of the sort parameter, data can be returned in ascending asc or descending desc (default) order.

HTTP request

GET https://<eu|us>.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/aggregations/vwap{?interval,start_time,end_time,page_size,continuation_token}

Parameters

Parameter Required Description
commodity Yes The data commodity. (trades)
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange2 Yes Exchange code. See Instruments Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
interval No Interval period. Default 1d.
page_size1 No See Pagination (min: 1, default: 100, max: 100000).
start_time1 No Starting time in ISO 8601 (inclusive).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token. 2: This endpoint serves both data from centralized as well as decentralized exchanges.

Fields

Field Description
timestamp Timestamp at which the interval begins.
price Volume-weighted average price. null when no trades reported.

Intervals

Any arbitrary value between one second and one day can be used as an interval, as long as it sums up to 1 day. The suffixes are s (second), m (minute), h (hour) and d (day).

Count-OHLCV-VWAP

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/exchanges/cbse/spot/btc-usd/aggregations/count_ohlcv_vwap'

Response Example

{
    "query": {
        "page_size": 100,
        "exchange": "cbse",
        "instrument_class": "spot",
        "instrument": "btc-usd",
        "interval": "1d",
        "sort": "desc",
        "aggregation": "count_ohlcv_vwap",
        "data_version": "v1",
        "commodity": "trades",
        "request_time": "2020-11-12T16:55:42.588Z"
    },
    "time": "2020-11-12T16:55:42.710Z",
    "timestamp": 1605200142710,
    "data": [
        {
            "timestamp": 1605139200000,
            "open": "15705.79",
            "high": "16185.87",
            "low": "15446.82",
            "close": "16139.93",
            "volume": "14829.124546730012",
            "price": "15880.01873841608",
            "count": 95111
        },
        {
            "timestamp": 1605052800000,
            "open": "15315.46",
            "high": "16000",
            "low": "15293.04",
            "close": "15705.79",
            "volume": "15123.844197729988",
            "price": "15664.643871798791",
            "count": 114205
        },
    /* ... */
  ],
  "result": "success",
  "continuation_token": "rbd1XbkjMwv2SyUfvJwsqFGmCKzg3WToTvqigui1bejckYnxd9DM1V3v58iqMCdXa4dJSXap6p6fBuvzz32tiHVrv5LC76MyRyYNbZyvSEoVzd1krSWWeXYEtEtR",
  "next_url": "https://<eu|us>.market-api.kaiko.io/v2/data/trades.v1/exchanges/cbse/spot/btc-usd/aggregations/count_ohlcv_vwap?continuation_token=rbd1XbkjMwv2SyUfvJwsui1bejckYnxd9DM1V3v58iqMCdXa4dJSXap6p6fBuvzz32tiHVrv5LC76MyRyYNbZyvSEoVzd1krSWWeXYEtEtR",
  "access": {
    "access_range": {
      "start_timestamp": 1546300800000,
      "end_timestamp": 1577836800000
    },
    "data_range": {
      "start_timestamp": 1417391000000,
      "end_timestamp": 1577836800000
    }
  }
}

This endpoint retrieves the trade count, OHLCV and VWAP history for an instrument on an exchange. The interval parameter is suffixed with s, m, h or d to specify seconds, minutes, hours or days, respectively. By making use of the sort parameter, data can be returned in ascending asc (default) or descending desc order.

HTTP request

GET https://<eu|us>.market-api.kaiko.io/v2/data/{commodity}.{data_version}/exchanges/{exchange}/{instrument_class}/{instrument}/aggregations/count_ohlcv_vwap{?interval,start_time,end_time,page_size,continuation_token}

Parameters

Parameter Required Description
commodity Yes The data commodity.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exchange2 Yes Exchange code.See Instruments Reference Data Endpoint.
instrument_class Yes Instrument class. See Instruments Reference Data Endpoint.
instrument Yes Instrument code. See Instruments Reference Data Endpoint.
interval No Interval period. Default 1d.
page_size1 No See Pagination (min: 1, default: 100, max: 100000).
start_time1 No Starting time in ISO 8601 (inclusive).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token. 2: This endpoint serves both data from centralized as well as decentralized exchanges.

Fields

Field Description
timestamp Timestamp at which the interval begins.
count Then number of trades. 0 when no trades reported.
open Opening price of interval. null when no trades reported.
high Highest price during interval. null when no trades reported.
low Lowest price during interval. null when no trades reported.
close Closing price of interval. null when no trades reported.
volume Volume traded in interval. 0 when no trades reported.
vwap The volume weighted price during the time interval. null when no trades reported.

Intervals

Any arbitrary value between one second and one day can be used as an interval, as long as it sums up to 1 day. The suffixes are s (second), m (minute), h (hour) and d (day).

Pricing and Valuation Services

Asset Price

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/spot_direct_exchange_rate/btc/usd?include_exchanges=cbse,bfnx&sources=true'

Response Example

{
    "query": {
        "page_size": 100,
        "interval": "1d",
        "sort": "desc",
        "base_asset": "btc",
        "quote_asset": "usd",
        "sources": true,
        "ch": true,
        "include_exchanges": [
            "cbse",
            "bfnx"
        ],
        "exclude_exchanges": [],
        "data_version": "v1",
        "commodity": "trades",
        "request_time": "2020-05-26T20:09:13.000Z",
        "instruments": [
            "bfnx:spot:btc-usd",
            "cbse:spot:btc-usd"
        ]
    },
    "time": "2020-05-26T20:09:14.277Z",
    "timestamp": 1590523754277,
    "data": [
        {
            "timestamp": 1590451200000,
            "price": "8847.968719074968",
            "volume": "13589.95633007",
            "count": 122143,
            "sources": [
                {
                    "exchange_code": "cbse",
                    "count": 66991,
                    "price": "8848.388264128678",
                    "volume": "10187.26739386"
                },
                {
                    "exchange_code": "bfnx",
                    "count": 55152,
                    "price": "8846.712648441991",
                    "volume": "3402.68893621"
                }
            ]
        },
    /* ... */
],
    "result": "success",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint generates an aggregated price for an asset pair across all exchanges with spot markets for the pair. Only asset combinations which are actively being traded on one of our covered exchanges are being taken into account for the calculation of the price. Unsupported asset combinations will return no data. To return data used as input for the calculation of the aggregated price, set the sources parameter to true. Setting the sources parameter to false (default) will yield a faster response time. By making use of the sort parameter, data can be returned in ascending asc or descending desc order (default).

HTTP request

GET https://<eu|us>.market-api.kaiko.io/v2/data/trades.v1/spot_direct_exchange_rate/{base_asset}/{quote_asset}/{?include_exchanges,exclude_exchanges,start_time,end_time,interval,page_size,sources}

Parameters

Parameter Required Description
base_asset Yes The desired base asset code. See Instruments Reference Data Endpoint.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exclude_exchanges1 No List of exchanges' code to exclude from the calculation. See Instruments Reference Data Endpoint. Only available in API v2.
interval1 No Interval period. Default 1d.
include_exchanges1 No List of exchanges' code to include in the calculation. See Instruments Reference Data Endpoint. Only available in API v2.
page_size1 No See Pagination (min: 1, default: 100, max: 1000).
quote_asset Yes The desired quote asset code. See Instruments Reference Data Endpoint.
start_time1 No Starting time in ISO 8601 (inclusive).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default is asc in API v1, desc in API v2.
sources1 No boolean. If true, returns all prices which were used to calculate aggregated price. Default is false

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.*

This endpoint uses data from CEXs as well as DEXs

Fields

Field Description
timestamp Timestamp at which the interval begins.
price Aggregated VWAP. null when no trades reported.
volume Total volume traded in interval. 0 when no trades reported.
count Total amount of trades reported during interval. 0 when no trades reported.

Cross Price

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/spot_exchange_rate/btc/gbp?sources=true&include_exchanges=cbse,bfnx'

Response Example

{
    "query": {
        "page_size": 100,
        "interval": "1d",
        "sort": "desc",
        "base_asset": "btc",
        "sources": true,
        "ch": true,
        "include_exchanges": [
            "cbse",
            "bfnx"
        ],
        "exclude_exchanges": [],
        "quote_asset": "gbp",
        "data_version": "v1",
        "commodity": "trades",
        "request_time": "2021-04-07T17:40:25.708Z",
        "instruments": [
            "bfnx:spot:btc-usd",
            "cbse:spot:btc-usd",
            "bfnx:spot:btc-usdt",
            "bfnx:spot:usdt-usd",
            "oer:usd-gbp"
        ]
    },
    "time": "2021-04-07T17:40:25.829Z",
    "timestamp": 1617817225829,
    "data": [
        {
            "timestamp": 1617753600000,
            "price": "41345.58171835934",
            "sources": {
                "btc-usdt": {
                    "data": [
                        {
                            "exchange_code": "bfnx",
                            "count": 40771.0,
                            "price": "57117.19387654953",
                            "volume": "1710.9980164799917"
                        }
                    ],
                    "price": "57117.19387654953"
                },
                "usdt-usd": {
                    "data": [
                        {
                            "exchange_code": "bfnx",
                            "count": 45284.0,
                            "price": "0.9991284598874877",
                            "volume": "140245332.3178564"
                        }
                    ],
                    "price": "0.9991284598874877"
                }
            }
        }
    /* ... */
],
    "result": "success",
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

This endpoint returns the price of any asset quoted in a Fiat currency within Open Exchange Rate. The USD price is calculated based on the path of the highest liquidity, with an additional step using forex rates to get the final fiat price. This means that, even though an asset might trade directly against all Open Exchange Rate currencies, the price might still be established by using cross-rates1. In cases where the most liquid path changed over time, this will be taken into account in the calculation of the price for each interval. To have an overview of what data was used to calculate the price, set the sources parameter to true. Setting the sourcesparameter to false (default) will yield a faster response time. By making use of the sort parameter, data can be returned in ascending asc (default) or descending desc order.

1: A cross rate is an intermediary currency pair that does not involve the target quote asset.

HTTP request

GET https://<eu|us>.market-api.kaiko.io/v2/data/trades.v1/spot_exchange_rate/{base_asset}/{quote_asset}{?include_exchanges,exclude_exchanges,start_time,end_time,interval,page_size,sources}

Parameters

Parameter Required Description
base_asset Yes The desired base asset code. See Instruments Reference Data Endpoint.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
exclude_exchanges1 No List of exchanges' code to exclude from the calculation. See Instruments Reference Data Endpoint. Only available in API v2.
interval1 No Interval period. Default 1d.
include_exchanges1 No List of exchanges' code to include in the calculation. See Instruments Reference Data Endpoint. Only available in API v2.
outliers_strategy No Either median_perc, modified_zscore or zscore. See the Outlier Management section below.
outliers_min_data No Number of minimum data points needed to trigger the outlier detecton. Default to 4.
outliers_threshold No Threshold to use. Usage depends on the chosen outlier management strategy.
page_size1 No See Pagination (min: 1, default: 100, max: 1000).
quote_asset Yes The desired quote asset code. See Instruments Reference Data Endpoint.
start_time1 No Starting time in ISO 8601 (inclusive).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default is asc
sources1 No boolean. If true, returns all prices which were used to calculate aggregated price. Default is false
extrapolate_missing_values2 No boolean. If true, reduce the amount of null values within the given interval of time for low liquidity pairs. Default is false

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token. 2: Some null values can still remain when turning the parameter to true. As this parameter makes use of extrapolation of previous values, at least one non-null value needs to be present within the queried time window.

Outlier Management

Field Description
median_perc Computes the median of all prices and excludes values that are off a certain % from the median. This is the simplest and most intuitive strategy. As it makes use of the median, it's better suited against extreme outliers. Usage of outliers_threshold: 0.1 for 10%
zscore Computes the Z-score of each data point and excludes the ones for which zscore > outliers_threshold, where outliers_threshold is specified by the user (i.e a good rules of thumb would be a value between 1.5 and 3.5). Z-score signals how many standard deviations away a given observation is from the mean. This strategy is more susceptible to extreme values, as it makes use of the mean. More details here
modified_zscore Similar to zscore but using the median instead of the mean, and the MAD (median absolute deviation) instead of standard deviation. This makes it less susceptible to extreme values. Usage of outliers_threshold: generally between 2 and 4

This endpoint uses data from CEXs as well as DEXs

Fields

Field Description
timestamp Timestamp at which the interval begins.
price Aggregated VWAP. null when no trades reported.
volume Total volume traded in interval. 0 when no trades reported.
count Total amount of trades reported during interval. 0 when no trades reported.

Valuation

The Valuation endpoint allows you to build completely customizable single-asset or multi-asset price feeds for NAV calculations, portfolio valuation, asset allocation strategies, and indices.

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/valuation?start_time=2021-04-01T16:00:00.000Z&end_time=2021-04-15T16:00:00.000Z&interval=1d&semi_length_window=30m&exchanges=cbse,stmp,bfnx,gmni&bases=btc,ltc,pdot,eth,ada&weights=0.4,0.2,0.1,0.2,0.1&percentages=0.9&quote=usd&sources=true'

Response Example

{
    "query": {
        "start_time": "2021-04-01T16:00:00.000Z",
        "end_time": "2021-04-15T16:00:00.000Z",
        "page_size": 100,
        "interval": "1d",
        "semi_length_window": "30m",
        "exchanges": [
            "cbse",
            "stmp",
            "bfnx",
            "gmni"
        ],
        "sources": false,
        "bases": [
            "btc",
            "ltc",
            "pdot",
            "eth",
            "ada"
        ],
        "weights": [
            "0.4",
            "0.2",
            "0.1",
            "0.2",
            "0.1"
        ],
        "percentages": [
            "0.9",
            "1"
        ],
        "quote": "usd",
        "data_version": "v1",
        "commodity": "trades",
        "request_time": "2021-08-05T15:29:01.797Z",
        "start_timestamp": 1617292800000,
        "end_timestamp": 1618502400000
    },
    "time": "2021-08-05T15:29:02.480Z",
    "timestamp": 1628177342480,
    "data": [
        {
            "datetime": "2021-04-01 16:00:00 UTC",
            "timestamp": 1617292800000,
            "response_by_percentages": [
                {
                    "percentage": 0.9,
                    "price": "100.0",
                    "response_by_pairs": [
                        {
                            "pair": "ada-usd",
                            "contribution": "10.0",
                            "ref_price": "1.1952953546487899",
                            "weight": 0.1
                        },
                        {
                            "pair": "btc-usd",
                            "contribution": "40.0",
                            "ref_price": "58975.26519568538",
                            "weight": 0.4
                        },
                        {
                            "pair": "eth-usd",
                            "contribution": "20.0",
                            "ref_price": "1944.7174052029602",
                            "weight": 0.2
                        },
                        {
                            "pair": "ltc-usd",
                            "contribution": "20.0",
                            "ref_price": "203.41030791068567",
                            "weight": 0.2
                        },
                        {
                            "pair": "pdot-usd",
                            "contribution": "10.000000000000002",
                            "ref_price": "37.88622037567283",
                            "weight": 0.1
                        }
                    ]
                },
                {
                    "percentage": 1.0,
                    "price": "100.0",
                    "response_by_pairs": [
                        {
                            "pair": "ada-usd",
                            "contribution": "10.0",
                            "ref_price": "1.1950047448446344",
                            "weight": 0.1
                        },
                        {
                            "pair": "btc-usd",
                            "contribution": "40.0",
                            "ref_price": "58967.98807937056",
                            "weight": 0.4
                        },
                        {
                            "pair": "eth-usd",
                            "contribution": "20.0",
                            "ref_price": "1945.0143276289953",
                            "weight": 0.2
                        },
                        {
                            "pair": "ltc-usd",
                            "contribution": "20.0",
                            "ref_price": "203.3154778118961",
                            "weight": 0.2
                        },
                        {
                            "pair": "pdot-usd",
                            "contribution": "10.0",
                            "ref_price": "37.88470890631195",
                            "weight": 0.1
                        }
                    ]
                }
            ]
        },
        {
            "datetime": "2021-04-02 16:00:00 UTC",
            "timestamp": 1617379200000,
            "response_by_percentages": [
                {
                    "percentage": 0.9,
                    "price": "102.65406334012563",
                    "response_by_pairs": [
                        {
                            "pair": "ada-usd",
                            "contribution": "10.157886022869157",
                            "ref_price": "1.2141673976187375",
                            "weight": 0.1
                        },
                        {
                            "pair": "btc-usd",
                            "contribution": "40.30999169598325",
                            "ref_price": "59432.31125766219",
                            "weight": 0.4
                        },
                        {
                            "pair": "eth-usd",
                            "contribution": "21.25300137809248",
                            "ref_price": "2066.5540846389476",
                            "weight": 0.2
                        },
                        {
                            "pair": "ltc-usd",
                            "contribution": "20.41100604813737",
                            "ref_price": "207.5904512509245",
                            "weight": 0.2
                        },
                        {
                            "pair": "pdot-usd",
                            "contribution": "10.522178195043386",
                            "ref_price": "39.864556192951305",
                            "weight": 0.1
                        }
                    ]
                },
                {
                    "percentage": 1.0,
                    "price": "102.67165672438934",
                    "response_by_pairs": [
                        {
                            "pair": "ada-usd",
                            "contribution": "10.16399109677373",
                            "ref_price": "1.2146017587203226",
                            "weight": 0.1
                        },
                        {
                            "pair": "btc-usd",
                            "contribution": "40.31602493751589",
                            "ref_price": "59433.871948076085",
                            "weight": 0.4
                        },
                        {
                            "pair": "eth-usd",
                            "contribution": "21.25496657463498",
                            "ref_price": "2067.060726047021",
                            "weight": 0.2
                        },
                        {
                            "pair": "ltc-usd",
                            "contribution": "20.419550174222547",
                            "ref_price": "207.58053001880216",
                            "weight": 0.2
                        },
                        {
                            "pair": "pdot-usd",
                            "contribution": "10.517123941242193",
                            "ref_price": "39.843817904556474",
                            "weight": 0.1
                        }
                    ]
                }
            ]
        },
  /* ... */
],
    "result": "success",
    "continuation_token": "6zEL19kG8ZZehSMyiuQ7Xir9uWneTvkPUAopSsPFZZ89BfGjGprvwjTQxSk1kMuHWE9dW4atmhckBeT1jXvTcUBhqgy4v6wXj3nD1kBqJtfmy1GJjpnNTMcJ5FpnpHYtRRkzPtcFGccnnbNGxmAcQaqyF7hrZFziaqR8CBUcqY9p7Z6mEQkZxmwL5Dc1soKfNvvDfu8JdE5mkZgimxQRx7zVnZG2Xaoz8MfjYA2TjiEjKJZ858dwsCkdWktKee22iBJrNwCX3KGMAvZd1pMYX98w3umATw8SfbqFsZZ1BRZDwRUAaF4sn3tufjKX6RirUUACWeqtfeZp1DWdfKrbXo3hckpMmZC3yVndjvfb5sFHBy73gkoSvJsQTsqnibgoR3dCQQq4cfmX6NWRe4Vucc5Qn6jUjvodqysCRnJjp",
    "next_url": "https://us.market-api.kaiko.io/v2/data/trades.v1/valuation?continuation_token=6zEL19kG8ZZehSMyiuQ7Xir9uWneTvkPUAopSsPFZZ89BfGjGprvwjTQxSk1kMuHWE9dW4atmhckBeT1jXvTcUBhqgy4v6wXj3nD1kBqJtfmy1GJjpnNTMcJ5FpnpHYtRRkzPtcFGccnnbNGxmAcQaqyF7hrZFziaqR8CBUcqY9p7Z6mEQkZxmwL5Dc1soKfNvvDfu8JdE5mkZgimxQRx7zVnZG2Xaoz8MfjYA2TjiEjKJZ858dwsCkdWktKee22iBJrNwCX3KGMAvZd1pMYX98w3umATw8SfbqFsZZ1BRZDwRUAaF4sn3tufjKX6RirUUACWeqtfeZp1DWdfKrbXo3hckpMmZC3yVndjvfb5sFHBy73gkoSvJsQTsqnibgoR3dCQQq4cfmX6NWRe4Vucc5Qn6jUjvodqysCRnJjp",
    "access": {
        "access_range": {
            "start_timestamp": 1601251200000,
            "end_timestamp": 1898639999000
        },
        "data_range": {
            "start_timestamp": 1514764800000,
            "end_timestamp": 1893542399000
        }
    }
}

HTTP request

GET https://us.market-api.kaiko.io/v2/data/trades.{data_version}/valuation{?start_time,end_time,interval,semi_length_window,exchanges,bases,quote,weights,percentages,sources,continuation_token}

Parameters

Parameter Required Description
bases Yes List of base components. Min. 1, max. 5
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time No Last fixing of the calculation in ISO 8601 (exclusive).
exchanges No List of exchanges to source data from. See Instruments Reference Data Endpoint. Default: all exchanges
interval No Frequency in time unit after the first fixing. Default: 1d.
percentages Yes List of percentages for outlier management. To not enforce any outlier management, use 1
start_time No First fixing of the calculation in ISO 8601 (inclusive).
semi_length_window Yes The time interval to compute the transaction.
sources No boolean. If true, returns all prices and volumes which were used to calculate valuation price. Default: false
quote Yes The fiat pricing currency.
weights Yes Weighting list of base assets. For single-asset price feeds use an asset weighting of “1”

This endpoint uses data from CEXs as well as DEXs

Fields

Field Description
timestamp Timestamp at which the interval begins.
percentage Percent of the price distribution centered around the median price.
price The composite price, with a base of 100.
pair The constituent pair.
contribution The asset contribution to the composite price.
ref_price The reference price per asset.
weight The weight per asset.

Computation and Constraints

Considering the volume of data points processed for the computation of each data point, some parameter constraints have been implemented in order to optimize computation time:

OANDA FX Rates

The OANDA FX Rates endpoint provides auditable, reliable and IFRS compliant FX rates for over 70 forex pairs.

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/analytics.v2/oanda_fx_rates?base=eur&page_size=2&sort=desc&interval=1d&quote=jpy'

Response Example

{
    "query": {
        "base": "eur",
        "quote": "jpy",
        "interval": "1d",
        "page_size": "2",
        "sort": "desc",
        "start_time": "null",
        "end_time": "2022-08-31T08:38:25.883Z"
    },
    "time": "2022-08-31T08:38:25.905Z",
    "timestamp": 1661935105,
    "data": [
        {
            "timestamp": 1660780800000,
            "fx_rate": "137.38630485436903"
        },
        {
            "timestamp": 1660694400000,
            "fx_rate": "137.15155641205303"
        }
    ],
    "continuation_token": "4tvMKJPYA6ESWsE7s87P2ujFvr6XRNvegzst2eg1EpdyQEPKWpuNic5XPGrhz47RzbbqC598E3XusLo34Hivgw4sYrrvdmYxL7WQVtebjtYVMUPPd97vqo2VjL22A6cTSNojTQsvHh8T6MPRjuJAMfx5LWyVZQWYyzLrSE",
    "next_url": "https://us.market-api.kaiko.io/v2/data/analytics.v2/oanda_fx_rates?continuation_token=4tvMKJPYA6ESWsE7s87P2ujFvr6XRNvegzst2eg1EpdyQEPKWpuNic5XPGrhz47RzbbqC598E3XusLo34Hivgw4sYrrvdmYxL7WQVtebjtYVMUPPd97vqo2VjL22A6cTSNojTQsvHh8T6MPRjuJAMfx5LWyVZQWYyzLrSE"
}

HTTP request

GET https://us.market-api.kaiko.io/v2/data/analytics.{data_version}/oanda_fx_rates{?start_time,end_time,interval,base,quote,sort,continuation_token}

Parameters

Parameter Required Description
base1 Yes The base fiat currency.
continuation_token No See Pagination.
data_version Yes The data version. (v1, v2 ... or latest)
end_time1 No Ending time in ISO 8601 (exclusive).
interval1 No Interval period. Default 1h.
page_size1 No See Pagination (min: 1, default: 100, max: 1000).
quote1 Yes The quote fiat currency.
start_time1 No Starting time in ISO 8601 (inclusive).
sort1 No Return the data in ascending (asc) or descending (desc) order. Default desc

1: When paginating, these parameters should only be included in the first request. For subsequent requests, they are encoded in the continuation token.

Fields

Field Description
timestamp Timestamp at which the interval ends.
fx_rate Average fx rate over the interval.

Methodology

For each interval, the resulting fx rate is an average of all available fx rates over that period.

DEX Liquidity

DEXs liquidity pools market data is composed of two API endpoints: liquidity events & liquidity snapshots.

Those data are made available historically and live by both endpoints, and all at a block-by-block granularity. The supported exchanges are Uniswap, Sushiswap, Balancer, and Curve.

Liquidity Events

Request Example

curl --compressed -H "Accept: application/json" -H "X-Api-Key: <client-api-key>" \
  "https://eu.market-api.kaiko.io/v2/data/liquidity.v1/events"

Response Example

{
  "query": {
    "exchange": "*",
    "pool_address": "0x7bea39867e4169dbe237d55c8242a8f2fcdcc387",
    "block_number": "*",
    "type": "*",
    "user_addresses": "*",
    "tx_hash": "*",
    "start_time": "2022-04-01 00:00:00 +0000 UTC",
    "end_time": "2022-05-01 00:00:00 +0000 UTC",
    "sort": "descending",
    "pool_contains": "*",
    "page_size": "1000"
  },
  "time": "2022-05-17T14:26:27.274Z",
  "timestamp": 1652797587,
  "data": [
    {
      "block_number": 14682526,
      "type": "mint",
      "pool_name": "USDC-WETH-0.010",
      "pool_address": "0x7bea39867e4169dbe237d55c8242a8f2fcdcc387",
      "exchange": "usp3",
      "transaction_hash": "0x02127cbf00c43fff6a1ec381703e66035b975e49f901ade55f1b12652e07b544",
      "log_index": 187,
      "user_address": "0x3cbd83d4a4ee504bf8b78d9c2927a9f22f27cce5",
      "price": 0.0003564194488230487,
      "amounts": [
        {"symbol": "USDC", "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": 31.063585},
        {"symbol": "WETH", "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "amount": 0.5833806413127403}
      ],
      "datetime": 1651280001,
      "metadata": {"lower_ticker": 192600, "upper_ticker": 197000}
    }
    /* ... */
  ],
  "continuation_token": "xxx",
  "next_url": "https://eu.market-api.kaiko.io/v2/data/liquidity.v1/events?continuation_token=xxx"
}

HTTP request

GET https://eu.market-api.kaiko.io/v2/data/liquidity.v1/events

Parameters

Parameter Required Description Example
protocol No Filter on a currently supported DEX. usp2
pool_address No Pool address related to the liquidity event. Default: all liquidity pools. 0x14de8287adc90f0f95bf567c0707670de52e3813
pool_contains No Liquidity events including the requested token. Default: all available tokens. weth or weth,usdt,usdc
block_number No Block height. 129876
user_addresses No Filter on specific user addresses (comma separated). 0x479bc**
tx_hash No Filter on a specific transaction hash. 0xe68b84740**
start_block No Starting block height (inclusive). 129870
end_block No Ending block height (inclusive). 130000
start_time No Starting time in ISO 8601 (inclusive). 2022-04-01T00:00:00.000Z
end_time No Ending time in ISO 8601 (inclusive). 2022-05-01T00:00:00.000Z
sort No Returns the data in ascending (asc) or descending (desc) order. Default: desc. asc
type No Event type. By default both burn and mint are shown. burn or mint
page_size1 No See Pagination (min: 1, default: 100, max: 1000).

Fields

Field Description Example
block_number The height of the block in which the transaction happened. 129876
type Event type: mint or burn. burn or mint
pool_name Name of the pool as it is written on the blockchain. USDC-WETH-0.001
pool_address Address of the contract of the pool. 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640
exchange Code of the DEX. usp3
transaction_hash Transaction hash 0x3d28ec9f35692ee6e9264735cd4f92c48bccda82487144d26ebc12376a418cdc
log_index The log index of the transaction (in base 10) 187
user_address Address that triggered the transaction. 0x479bc00624e58398f4cf59d78884d12fb515790a
price Price of the token at the moment of the event. 0.000358096
amounts Amounts of the tokens See example
datetime Timestamp at which the interval begins. In milliseconds. 1650441900000
metadata Only for Uniswap v3. Upper and lower ticker of the interval on which the liquidity is provided {"lower_ticker": 190650, "upper_ticker": 195610}

Liquidity Snapshots

Request Example

curl --compressed -H "Accept: application/json" -H "X-Api-Key: <client-api-key>" \
  "https://eu.market-api.kaiko.io/v2/data/liquidity.v1/snapshots"

Response Example

{
  "query":
  {
    "exchange": "*",
    "pool_address": "0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7",
    "start_block": "*",
    "end_block": "*",
    "start_time": "2016-02-02 00:00:00 +0000 UTC",
    "end_time": "2038-04-03 23:59:59 +0000 UTC",
    "sort": "descending",
    "page_size": "1000"
  },
  "time": "2022-05-17T14:33:56.432Z",
  "timestamp": 1652798036,
  "data": [
    {
      "block_number": 14737185,
      "pool_name": "3pool",
      "pool_address": "0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7",
      "exchange": "curv",
      "transaction_hash": "0x837cf2d72008d6fd01840777f297555e84fa2ecf921e9b18b2431239391cf6fe",
      "amounts": [
        {"symbol": "DAI", "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F", "amount": 844939427.8334135},
        {"symbol": "USDC", "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "amount": 812860376.59691},
        {"symbol": "USDT", "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "amount": 1348165795.920551}
      ],
      "datetime": 1652028160
    }
    /* ... */
  ],
  "continuation_token": "xxx",
  "next_url": "https://eu.market-api.kaiko.io/v2/data/liquidity.v1/snapshots?continuation_token=xxx"
}

HTTP request

GET https://eu.market-api.kaiko.io/v2/data/liquidity.v1/snapshots

Parameters

Parameter Required Description Example
pool_address Yes Pool address. 0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7
start_block No Starting block height (inclusive). 129870
end_block No Ending block height (inclusive). 130000
start_time No Starting time in ISO 8601 (inclusive). 2022-04-01T00:00:00.000Z
end_time No Ending time in ISO 8601 (inclusive). 2022-05-01T00:00:00.000Z
sort No Returns the data in ascending (asc) or descending (desc) order. Default: desc. asc
page_size1 No See Pagination (min: 1, default: 100, max: 1000). 100

Fields

Field Description Example
block_number The height of the block. 129876
pool_name Name of the pool as it is written on the blockchain. 3pool
pool_address Address of the contract of the pool. 0xbebc44782c7db0a1a60cb6fe97d0b483032ff1c7
exchange Code of the DEX. curv
amounts Snapshot of the liquidity pool's tokens. See example
datetime Timestamp at which the interval begins. In milliseconds. 1650441900000

Uniswap v3 Liquidity Snapshots

Uniswap’s v3 liquidity snapshots are represented by a distribution of liquidity amongst all possible price levels for a pair of tokens. Each price range is defined by the interval [lower_tick, upper_tick[. This dataset provides the amount of tokens and liquidity made available at each price level. The range of price levels is limited to ±10% around the current price of each block. The data is provided in a block-by-block granularity.

Request Example

curl --compressed -H "Accept: application/json" -H "X-Api-Key: <client-api-key>" \
  "https://eu.market-api.kaiko.io/v2/data/liquidity.v1/snapshots/usp3"

Response Example

{
  "query": 
  {
    "protocol": "usp3",
    "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
    "start_block": "*",
    "end_block": "*",
    "start_time": "2022-12-15T00:00:00.000Z",
    "end_time": "2038-04-03T23:59:59.000Z",
    "sort": "descending",
    "page_size": "1",
    "price_range": "0.02"
  },
  "time": "2023-01-10T13:47:17.068Z",
  "timestamp": 1673358437,
  "data": [
    {
      "block_number": 16376727,
      "pool_name": "USDC-WETH-0.001",
      "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "current_tick": 204408,
      "current_price": 0.0007531523038978548,
      "datetime": 1673357555,
      "snapshots": [
        {"amount0": 0,
        "amount1": 319.31621601508493,
        "amount": 23497518858492568000,
        "lower_tick": 204210,
        "upper_tick": 204220},
        {"amount0": 0,
        "amount1": 320.5286369101081,
        "amount": 23574947430043783000,
        "lower_tick": 204220,
        "upper_tick": 204230},

        /* ... */

        {"amount0": 341263.63629985636,
        "amount1": 0,
        "amount": 18917367912032326000,
        "lower_tick": 204600,
        "upper_tick": 204610}
      ],
      "exchange": "usp3"
    }
  ],
  "continuation_token": "xxx",
  "next_url": "https://eu.market-api.kaiko.io/v2/data/liquidity.v1/snapshots/usp3?continuation_token=xxx"
}

HTTP request

GET https://eu.market-api.kaiko.io/v2/data/liquidity.v1/snapshots/usp3

Parameters

Parameter Required Description Example
pool_address Yes Pool address. 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640
start_block No Starting block height (inclusive). 129870
end_block No Ending block height (inclusive). 130000
start_time No Starting time in ISO 8601 (inclusive). 2022-04-01T00:00:00.000Z
end_time No Ending time in ISO 8601 (inclusive). 2022-05-01T00:00:00.000Z
price_range No The interval of price around the current price, in % (min: 0, default: 0.1, max: 0.2). 0.05
page_size1 No See Pagination (min: 1, default: 10, max: 100). 100

Fields

Field Description Example
block_number The height of the block. 16028979
pool_name Name of the pool as it is written on the blockchain. USDC-WETH-0.001
pool_address Address of the contract of the pool. 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640
current_tick The current tick at this block. -58580
current_price The current price at this block, normalized using the pool’s tokens decimals. 0.0028577887443084
datetime The timestamp of the block. 1669161611000
snapshots The snapshot of the liquidity at each tick of the pool. See below.

Field snapshots details

Field Description Example
amount0 The amount of token0 in the specified tick range, normalized using the token0 decimals. 0
amount1 The amount of token1 in the specified tick range, normalized using the token1 decimals. 26.4381078606
amount The amount of liquidity in the specified tick range. 1.7305248294559624e+23
lower_tick The lower tick of the range. -59580
upper_tick The upper tick of the range. -59520

Methodology

Link to our methodology paper: https://www.kaiko.com/pages/dex-liquidity-pool-data

Lending & Borrowing Protocols

Lending & Borrowing Events

Transactions (borrows, repayments, withdrawals, deposits and liquidations) registered on-chain, for the main L&B protocols.

Request Example

curl --compressed -H "Accept: application/json" -H "X-Api-Key: <client-api-key>" \
  "https://eu.market-api.kaiko.io/v2/data/lending.v1/events"

Response Example

{
  "query": {
        "block_number": "*",
        "blockchain": "*",
        "asset": "*",
        "user_address": "*",
        "tx_hash": "*",
        "type": "*",
        "start_time": "*",
        "end_time": "*",
        "protocol": "*",
        "sort": "descending",
        "page_size": "1000",
        "start_block": "*",
        "end_block": "*"
    },
    "time": "2022-05-17T14:26:27.274Z",
    "timestamp": 1652797587,
    "data":
    [
        {
            "blockchain": "ethereum",
            "block_number": 16025918,
            "datetime": 1669124591,
            "transaction_hash":"0xa49cfa9c026e728614ca0bdf7272eaaad5b3dd8881fd263ea19ef7d648d9c941",
            "exchange_code": "aave/v2",
            "type": "repayment",
            "user_address": "0x4f381fb46dfde2bc9dcae2d881705749b1ed6e1a",
            "asset_symbol": "crv",
            "asset_address": "0xd533a949740bb3306d119cc777fa900ba034cd52",
            "asset_decimals": 18,
            "receipt_symbol": "acrv",
            "receipt_address": "0x8dae6cb04688c62d939ed9b68d32bc62e49970b1",
            "receipt_decimals": 18,
            "amount": 299894.78,
            "metadata": {
                "borrowRateMode": 2,
                "amountInReceiptAsset": "299894.77",
                "onBehalfOf": "0x4f381fb46dfde2bc9dcae2d881705749b1ed6e1a"
            }
        }
        /* ... */
    ],
    "continuation_token": "xxx",
    "next_url": "https://eu.market-api.kaiko.io/v2/data/lending.v1/events?continuation_token=xxx"
}

HTTP request

GET https://eu.market-api.kaiko.io/v2/data/lending.v1/events

Parameters

Parameter Required Description Example
blockchain No Should be one or several of the currently supported blockchain. ethereum
protocol No Should be one or several of the currently supported L&B protocols. aav1,aav2
user_address No Filter on a specific wallet addresses (comma separated). 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
tx_hash No Filter on a specific transaction hash. 0xe68b84740**
asset No L&B events including the requested token. Default: all available tokens. weth or weth,usdt,usdc
type No Event type: borrow, deposit, withdraw, repayment or liquidation. borrow,withdraw
block_number No Block height. 10795593
start_block No Starting block height (inclusive). 129870
end_block No Ending block height (inclusive). 130000
start_time No Starting time in ISO 8601 (inclusive). 2022-04-01T00:00:00.000Z
end_time No Ending time in ISO 8601 (inclusive). 2022-05-01T00:00:00.000Z
sort No Returns the data in ascending or descending order. Default: desc. ascending
page_size1 No See Pagination (min: 1, default: 100, max: 1000). 1000

Fields

Field Description Example
blockchain The blockchain on which the transaction happened. ethereum
block_number The height of the block in which the transaction happened. 16025918
datetime The timestamp of the block in which the transaction happened. 1669124591
transaction_hash Transaction hash ---
log_index Log index of the transaction 152
protocol Code of the L&B protocol. aave/v2
type Event type: Borrow, deposit, withdraw, repayment or liquidation. borrow, deposit, etc
user_address Address of the user. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
asset_symbol Symbol of the underlying asset. crv
asset_address Address of the underlying asset. 0xd533a949740bb3306d119cc777fa900ba034cd52
asset_decimals Decimals of the underlying asset. 18
receipt_symbol Symbol of the receipt asset. acrv
receipt_address Address of the receipt asset. 0x8dae6cb04688c62d939ed9b68d32bc62e49970b1
receipt_decimals Decimals of the receipt asset. 18
amount Amounts of the borrowed token. 299894.78
metadata Metadata linked to the event type and protocol. More information below.

Metadata

Borrow Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
rate Borrow rate (at the event level or at the contract level depending on the protocol). 0.02820253961814756
rate_type Stable (1) or Variable (2) 1 or 2
on_behalf_of The address of user who will incur the debt. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Deposit Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
rate Supply rate of the overall lending pool. 0.000203088325657998768898798
on_behalf_of The address that will receive the receipt tokens. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Withdraw Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
on_behalf_of The address that will receive the underlying token. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Repayment Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
on_behalf_of The address of user who will incur the debt. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31
borrow_rate_mode Stable (1) or Variable (2) 1 or 2

Liquidation Event

Field Description Example
liquidation_debt_asset_symbol Symbol of the debt asset. renfil
liquidation_debt_asset_address Address of the debt asset. 0xd5147bc8e386d91cc5dbe72099dac6c9b99276f5
liquidation_debt_asset_decimals Decimals of the debt asset. 18
liquidation_debt_amount_in_asset Amount of the debt asset. 1899
liquidation_caller_address The address that triggered the liquidation transaction. 0xdfd3bd446f1b7fd96dc995126ee845af0b1254cd
receive_receipt_token The liquidator chooses to receive the collateral's asset (False) or recept token (True). True or False
liquidation_type Debt (1) or Collateral (2) 1

Lending & Borrowing Rates and Liquidity

This endpoint provides information about lending pools. It shows data such as how many tokens has been deposited and borrowed, as well as the interest rates for lending and borrowing at each block.

Request Example

curl --compressed -H "Accept: application/json" -H "X-Api-Key: <client-api-key>" \
  "https://eu.market-api.kaiko.io/v2/data/lending.v1/snapshots"

Response Example

{
  "query": {
        "block_number": "*",
        "blockchain": "*",
        "asset": "usdt",
        "start_time": "*",
        "end_time": "*",
        "interval": "*",
        "protocol": "aav1",
        "sort": "descending",
        "page_size": "100",
        "start_block": "*",
        "end_block": "*"
    },
    "time": "2023-04-04T14:20:50.387Z",
    "timestamp": 1680618050,
    "data":
    [
        {
            "blockchain": "ethereum",
            "block_number": 16974429,
            "datetime": 1680597815,
            "protocol": "aav1",
            "asset_symbol": "usdt",
            "asset_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
            "asset_decimals": 6,
            "receipt_symbol": "ausdt",
            "receipt_address": "0x71fc860f7d3a592a4a98740e39db31d25db65ae8",
            "receipt_decimals": 6,
            "total_liquidity": 1486161.683036,
            "available_liquidity": 1279626.811227,
            "total_borrowed": 206534.871809,
            "supply_rate": 0.0028918593043333676,
            "stable_borrow_rate": 0.04426480046626246,
            "variable_borrow_rate": 0.0208089338773062,
            "metadata":
            {
                "total_borrowed_stable": "0",
                "total_borrowed_variable": "206534.871809"
            }
        }
        /* ... */
    ],
    "continuation_token": "xxx",
    "next_url": "https://eu.market-api.kaiko.io/v2/data/lending.v1/snapshots?continuation_token=xxx"
}

HTTP request

GET https://eu.market-api.kaiko.io/v2/data/lending.v1/snapshots

Parameters

Parameter Required Description Example
blockchain No One or several of the currently supported blockchain. Default: ethereum. ethereum
protocol Yes One or several of the currently supported L&B protocols. aav1,aav2
asset Yes L&B events including the requested token. Default: all available tokens. weth or weth,usdt,usdc
block_number No Block height. 10795593
start_block No Starting block height (inclusive). 129870
end_block No Ending block height (inclusive). 130000
start_time No Starting time in ISO 8601 (inclusive). 2022-04-01T00:00:00.000Z
end_time No Ending time in ISO 8601 (inclusive). 2022-05-01T00:00:00.000Z
interval No Interval between each snapshot. The suffixes are s (second), m (minute), h (hour), d (day), b (block), change (whenever a change happens). Default: 1b. 152s
sort No Returns the data in ascending or descending order. Default: desc. ascending
page_size1 No See Pagination (min: 1, default: 100, max: 1000). 1000

Fields

Field Description Example
blockchain The blockchain on which the transaction happened. ethereum
block_number The height of the block in which the transaction happened. 16025918
datetime The timestamp of the block in which the transaction happened. 1669124591
protocol Code of the L&B protocol. aave/v2
asset_symbol Symbol of the underlying asset. crv
asset_address Address of the underlying asset. 0xd533a949740bb3306d119cc777fa900ba034cd52
asset_decimals Decimals of the underlying asset. 18
receipt_symbol Symbol of the receipt asset. acrv
receipt_address Address of the receipt asset. 0x8dae6cb04688c62d939ed9b68d32bc62e49970b1
receipt_decimals Decimals of the receipt asset. 18
total_liquidity The total amount of liquidity for this pool. 1486160
available_liquidity The total amount of available liquidity for this pool. 1279630
total_borrowed The total amount of tokens borrowed for this pool. 206535
supply_rate The supply rate. 0.00289186
stable_borrow_rate The stable borrow rate. 0.0442648
variable_borrow_rate The variable borrow rate. 0.0208089
metadata Metadata specific to each protocol. { }

Metadata

AAVE v1

Field Description Example
total_borrowed_stable The total amount of assets borrowed with a stable rate for this pool. 0
total_borrowed_variable The total amount of assets borrowed with a variable rate for this pool. 41872.928778

AAVE v2

Field Description Example
total_borrowed_stable The total amount of assets borrowed with a stable rate for this pool. 4162389.524515
total_borrowed_variable The total amount of assets borrowed with a variable rate for this pool. 345075360.304631
total_reserves Total liquidity - All of the debt tokens supply. 51387128.92415

Compound

Field Description Example
total_reserves Total liquidity - All of the debt tokens supply. 3486037.365878

Cream

Field Description Example
total_reserves Total liquidity - All of the debt tokens supply. 033661.402437

Maker

Field Description Example
collateral_ratio Minimum ratio of collateral before liquidation. 1.5
debt_ceiling Maximum amount of DAI that can be emitted on this type of vault. 2500000
debt_floor Minimum amount of DAI that can be minted for this type of Vault. 2000

Risk Management

Value at Risk

Daily Value at Risk (VaR) estimator for single and multi-asset portfolios. Computed by a proprietary and thoroughly backtested methodology that accounts for the idiosyncrasies of crypto market structure.

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk?bases=eth,btc,ltc&exchanges=krkn,bfnx,cbse&quantities=3,2,5&quote=usd&risk_level=0.95&start_time=2021-12-01T00:00:00.000Z&end_time=2022-01-31T00:00:00.000Z&sources=true'

Response Example


{'query': {'bases': 'eth,btc,ltc',
  'quote': 'usd',
  'quantities': '3,2,5',
  'exchanges': 'krkn,bfnx,cbse',
  'risk_level': '0.95',
  'sources': False,
  'data_version': 'v2',
  'commodity': 'value_at_risk',
  'request_time': '2022-05-11T14:42:47.314Z'},
 'time': '2022-05-11T14:42:48.799Z',
 'timestamp': 1652280168799,
 'data': [{'var_time': 1638316800000,
   'value_at_risk': {'value': 7648.7047100842665, 'risk_level': 0.95},
   'additional_vars': [{'value': 5216.766813519607, 'risk_level': 0.9},
    {'value': 7648.7047100842665, 'risk_level': 0.95},
    {'value': 10695.158816273437, 'risk_level': 0.975},
    {'value': 11521.662806007604, 'risk_level': 0.99}]},
  {'var_time': 1638403200000,
   'value_at_risk': {'value': 7608.531173554313, 'risk_level': 0.95},
   'additional_vars': [{'value': 5172.594911635809, 'risk_level': 0.9},
    {'value': 7608.531173554313, 'risk_level': 0.95},
    {'value': 10601.094511103178, 'risk_level': 0.975},
    {'value': 11453.74286744954, 'risk_level': 0.99}]},
    /*...*/ 
    ]
 'sources': {'prices': [{'pair': 'btc-usd',
    'prices': [{'ref_price': 19654.54367375727,
      'date': {'seconds': 1606780800}},
     {'ref_price': 18635.848095178895, 'date': {'seconds': 1606867200}},
     {'ref_price': 19258.534066235912, 'date': {'seconds': 1606953600}},
     /*...*/
    }]}],
  'quantities': [3, 2, 5],
  'start_date': {'seconds': 1638316800},
  'end_date': {'seconds': 1643587200},
  'risk_level': 0.95,
  'additional_risk_levels': [0.9, 0.95, 0.975, 0.99],
  'decay': 30,
  'bases': ['eth', 'btc', 'ltc']},
   /*...*/
   }          
  }

HTTP request

GET https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk?bases=eth,btc,ltc&exchanges=krkn,bfnx,cbse&quantities=3,2,5&quote=usd&risk_level=0.95&start_time=2021-12-01T00:00:00.000Z&end_time=2022-01-31T00:00:00.000Z&sources=true

Parameters

Parameter Required Description
bases Yes List of portfolio base components. Min 1, max 5.
quote Yes The fiat currency.
quantities Yes Quantities list of base asset in the portfolio.
risk_level Yes The Value at Risk confidence level. Between 0.90 (included) and 1 (excluded).
start_time Yes First fixing of the calculation in ISO 8601 (inclusive).
end_time Yes Last fixing of the calculation in ISO 8601 (inclusive).
exchanges Yes List of exchanges to source data from. See Instruments Reference Data Endpoint
sources No boolean. If true, returns all pair prices which were used to compute the Value at Risk. (Default: false)
data_version Yes The data version. (v1, v2 ... or latest)

This endpoint uses data from CEXs as well as DEXs.

Fields

Parameter Description
var_time The time at which the VaR is computed.
value_at_risk Composed of two fields: value and risk_level (the Value at Risk estimator at the specified risk_level.)
additional_vars List of additional VaRs for standard risk levels.
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)

Computation and constraints

Considering the volume of data points processed for the computation of each data point, some parameter constraints have been implemented in order to optimize computation time:

Derivatives Metrics

Derivatives Metrics API endpoint provides derivatives-specific data of futures, options, and perpetual futures. We currently provide historical derivatives data - beginning in July 2020 - updated once per minute. List of 6 supported exchanges are as follows: BitMEX, Deribit, OKEx, Kraken, Binance, and Bybit. More to be added soon.

It is comprised of 3 endpoints: reference, risk, and price. The reference endpoint provides details of the contracts, including base asset, quote asset, contract size, contract size unit, listing_timestamp, expiry, strike price, and underlying index. The risk endpoint indicates data that can be used to analyze risks related with derivatives, such as open interest, funidng rates, and option greeks. The price endpoint shows the mark price, index price, and price (last traded price).

Reference

The reference API endpoint provides details of a contract, which is the smallest unit of derivatives trading in most cases. The details include base asset, quote asset, contract size, contract size unit for all the types of derivatives, expiry for futures and options, and strike price for options. You can find a list of instruments using a parameter or several parameters. For example, you can find all the instruments whose base_assets is btc and quote_assets is usdt, if you put btc as an base_assets and usdt as an quote_assets.

Request Example

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'

Response Example

{
    "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
        }
    }
}

HTTP request

GET https://<eu|us>.market-api.kaiko.io/v2/data/derivatives.v2/reference

Parameters

Parameter Required Description Example
exchange Yes Should be one of the exchanges currently supported okex
instrument_class Yes future, perpetual-future, or option future
instrument No Instrument code. See Instruments Reference Data Endpoint. ethusd220624, btc*220624, *usdt, btc*may22*
base_assets No For finding the instruments with the certain base asset btc, eth
quote_assets No For finding the instruments with the certain quote asset usd, usdt
option_type No option only. For finding either only the call options or put options C, P
start_time No future & option only. Used to retrieve futures and options that expire after this date and time (inclusive) 2022-06-23T00:01:00.000Z
end_time No future & option only. Used to retrieve futures and options that are listed before this date and time (exclusive) 2022-06-25T23:59:00.000Z
page_size No See Pagination (min: 1, default: 1000, max: 1000) 500

Fields

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 btcusd220624
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
funding_rate_frequency perpetual-future only. Interval at which the funding rate is paid 8h
listing_timestamp future & option only. The timestamp when a certain option instrument is listed on the exchange 2020-03-28 03:21:00 UTC
expiry future & option only. Expiration date of the contract 2022-06-24 08:00:00 UTC
strike_price option only. The strike price of the contract in USD. 60000
underlying_index option only. Name of the underlying asset SYN.BTC-10APR20

Risk

The risk API endpoint indicates the information that can be used to analyze risks related with derivatives, such as open interest, funding rates, and option greeks. As instrument is a required parameter, the data of a single instrument is returned per query. When interval is greater than 1m (1 minute), the last minutely value is shown as an output. For instance, when interval is 1h, the data for 09:00 timestamp is the data from 09:59 timestamp with interval 1m.

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/derivatives.v2/risk?exchange=okex&instrument_class=perpetual-future&instrument=btc-usdt&page_size=2'

Response Example

{
    "query": {
        "page_size": "2",
        "exchange": "okex",
        "instrument_class": "perpetual-future",
        "instrument": "btc-usdt",
        "sort": "desc",
        "data_version": "v2",
        "commodity": "derivatives",
        "request_time": "2022-04-28T10:17:48.180Z"
    },
    "time": "2022-04-28T10:17:48.698Z",
    "timestamp": 1651141068698,
    "data": [
        {
            "timestamp": 1651141020000,
            "24h_volume": "10428503",
            "open_interest": "1084816",
            "funding_rate": "-0.0001225804461251",
            "predicted_funding_rate": "-0.0000652655998942"
        },
        {
            "timestamp": 1651140960000,
            "24h_volume": "10423219",
            "open_interest": "1086823",
            "funding_rate": "-0.0001225804461251",
            "predicted_funding_rate": "-0.0000654154039082"
        },

    ],

    /* ... */

    "access": {
        "access_range": {
            "start_timestamp": 1646006400,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

HTTP request

GET https://eu.market-api.kaiko.io/v2/data/derivatives.v2/risk

Parameters

Parameter Required Description Example
exchange Yes Should be one of the exchanges currently supported okex
instrument_class Yes future, perpetual-future, or option future
instrument Yes Instrument code. See Instruments Reference Data Endpoint btcusd220624
interval No Interval period (can be one of 1m, 1h, 4h, and 1d). Default 1m 1h
page_size No See Pagination (min: 1, default: 100, max: 1000). 10
sort No Return the data in ascending (asc) or descending (desc) order. Default desc asc
start_time No Starting time in ISO 8601 (inclusive). 2022-04-20T00:03:00.000Z
end_time No Ending time in ISO 8601 (exclusive). 2022-04-20T08:05:00.000Z

Fields

Field Description Example
timestamp Timestamp at which the interval begins. In milliseconds. 1650441900000
24h_volume The volume of the trades executed in the last 24 hours (can be in base_asset, quote_asset or the number of contracts) 5270648
open_interest The total oustanding number of contracts (units in which open interest metrics are quoted vary by exchange) 1127623
funding_rate perpetual-future only. The current funding rate. -0.0000756735759807
predicted_funding_rate perpetual-future only. The predicted funding rate for the next period. -0.0000845044644161
time_to_expiry future & option only. The number of minutes remaining before expiry. 41504
nearby future & option only. The soonest expiring contract with the same base & quote asset on the specified exchange boolean value
quarterly_nearby future & option only. The soonest expiring quarterly contract with the same base & quote asset on the specified exchange boolean value
ask_iv option only. Implied volatility for the best ask. 57.5
bid_iv option only. Implied volatility for the best bid. 65.4
mark_iv option only. The implied volatility for the mark price. 69.42
delta option only. The delta value for the option. 0.8841
gamma option only. The gamma value for the option. 0.00003
rho option only. The rho value for the option. 21.26122
theta option only. The theta value for the option. -26.18193
vega option only. The vega value for the option. 2.36321

Price

The price API endpoint shows the mark price, index price, and price (last traded price). These prices are collected once every minute. As instrument is a required parameter, the data of a single instrument is returned per query. When interval is greater than 1m (1 minute), the last minutely value is shown as an output. For instance, when interval is 1h, the data for 09:00 timestamp is the data from 09:59 timestamp with interval is 1m.

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://eu.market-api.kaiko.io/v2/data/derivatives.v2/price?exchange=okex&instrument_class=perpetual-future&instrument=btc-usdt&page_size=2'

Response Example

{
    "query": {
        "exchange": "okex",
        "instrument_class": "perpetual-future",
        "instrument": "btc-usdt",
        "interval": "1m",
        "page_size": 2,
        "sort": "desc",
        "data_version": "v2",
        "commodity": "derivatives",
        "request_time": "2022-04-28T12:36:34.981Z"
    },
    "time": "2022-04-28T12:36:37.166Z",
    "timestamp": 1651149397166,
    "data": [
        {
            "timestamp": 1651149360000,
            "index_price": null,
            "mark_price": "39707.8",
            "price": "39709.7"
        },
        {
            "timestamp": 1651149300000,
            "index_price": "39713.3",
            "mark_price": "39745.9",
            "price": "39767"
        }
    ],

    /*---*/

    "access": {
        "access_range": {
            "start_timestamp": 1646006400000,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    }
}

HTTP request

GET https://eu.market-api.kaiko.io/v2/data/derivatives.v2/price

Parameters

Parameter Required Description Example
exchange Yes Should be one of the exchanges currently supported okex
instrument_class Yes future, perpetual-future, or option future
instrument Yes Instrument code. See Instruments Reference Data Endpoint btcusd220624
interval No Interval period (can be one of 1m, 1h, 4h, and 1d). Default 1m 1h
page_size No See Pagination (min: 1, default: 100, max: 1000). 10
sort No Return the data in ascending (asc) or descending (desc) order. Default desc asc
start_time No Starting time in ISO 8601 (inclusive). 2022-04-20T00:03:00.000Z
end_time No Ending time in ISO 8601 (exclusive). 2022-04-20T08:05:00.000Z

Fields

Field Description Example
timestamp Timestamp at which the interval begins. In milliseconds. 1650441900000
index_price The price of the underlying index, often as a weighted average across multiple exchanges' spot prices 39713.3
mark_price The mark price of the contract. It is used for calculating profit and loss (PnL) and liquidation price. Designed to be fair and avoid price manipulation. 39745.9
price Most recent traded price of derivative contract 39767

Derivatives Analytics

Implied Volatility Smile

This analytics API suite provides calibrated implied volatilities extracted from options market prices. The implied_volatility_smile endpoint returns a volatility curve for a listed expiry date computed on a set of strike prices. The computation includes space interpolation and allows users to compute consistent volatilities on non-listed strikes. Implied volatilities for non-listed expiries will be coming soon.

Data from Deribit & OKX can be included in the computation of implied volatility.

List of currently supported assets: BTC, ETH. More to be added soon.

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile?base=btc&quote=usd&exchange=drbt&time=2022-09-20T16:15:00.000Z&expiry=2022-12-30T00:00:00.000Z&strikes=10000,15000,20000,40000'

Response Example

{
    "query": {
        "base": "btc",
        "quote": "usd",
        "exchange": "drbt",
        "time": "2022-11-28T16:15:00.000Z",
        "expiry": "2022-12-30T00:00:00.000Z",
        "data_version": "v2",
        "commodity": "analytics",
        "request_time": "2022-12-06T09:34:30.239Z"
    },
    "time": "2022-11-28T16:15:00.000Z",
    "expiry": "2022-12-30T00:00:00.000Z",
    "time_to_expiry": 0.08679977796739592,
    "implied_volatilities": [
        {
            "strike": 10000,
            "forward_log_moneyness": -0.4776318615692172,
            "implied_volatility": 1.0740308058964807,
            "delta": -0.04769169501102011,
            "gamma": 0.000019523790284227208
        },
        {
            "strike": 20000,
            "forward_log_moneyness": 0.21551531899072807,
            "implied_volatility": 0.5854937657743687,
            "delta": 0.12238690311373696,
            "gamma": 0.00007314557734786866
        },
        {
            "strike": 40000,
            "forward_log_moneyness": 0.9086624995506734,
            "implied_volatility": 0.9088355521899045,
            "delta": 0.0005576514757374973,
            "gamma": 4.567434848993305e-7
        },
        {
            "strike": 15000,
            "forward_log_moneyness": -0.07216675346105281,
            "implied_volatility": 0.6234182556166117,
            "delta": -0.3139268868260898,
            "gamma": 0.00012013816990700113
        }
    ]
}

HTTP request

GET https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_smile?base=btc&quote=usd&exchange=drbt&time=2022-09-20T16:15:00.000Z&expiry=2022-12-30T00:00:00.000Z&strikes=10000,15000,20000,40000

Parameters

Parameter Required Description Comments Example
base Yes The desired base as the underlying of the options. btc and eth only available for now. btc, eth
quote Yes The desired quote as the underlying of the options. usd only available for now. usd
exchange No The desired exchange as source of options data. drbt only or drbt & okx available for now. drbt
time Yes The time at which to compute implied volatilities The time t should be smaller than the expiry T 2022-09-20T16:15:00.000Z
expiry Yes The expiry for which the implied volatilities are to be computed - It must be an existing expiry on the selected exchange and tradable at the time of the computation.
- The time to expiry must be higher than 1 full week.		 2022-12-30T08:00:00.000Z
strikes Yes, if forward_log_moneynesses parameter is not used. The strike prices for which the implied volatilities are to be computed. Strike prices can be exiting or non existing ones (space interpolation included) Either strikes or forward_log_moneynesses should be filled.

singular: 10000
plural: 10000,15000,20000
forward_log_moneynesses Yes, if strikes is not used. The forward log moneyness for which the implied volatilities are to be computed Either strikes or forward_log_moneynesses should be filled.

singular: 1
plural: 0.5,1,1.5

Fields

Field Description Example
time The time in parameter 2022-09-20T16:15:00.000Z
expiry The expiry in parameter 2022-12-30T00:00:00.000Z
time_to_expiry The associated time to expiry in year 0.27580868156450355
implied_volatilities The list of requested implied volatilities [{"strike": 40000,
"forward_log_moneyness": 0.7348555803648208,
"implied_volatility": 0.7341747093260883,
"delta": 0.04334612697660922,
"gamma": 0.000012437991693543254},
{"strike": 20000,
"forward_log_moneyness": 0.041708399804875465,
"implied_volatility": 0.6670092468551713,
"delta": 0.5223606946028295,
"gamma": 0.00005929353471794603}, ... ]
delta The first derivative of the price with regards to the underlying price 2.8863019124747424e-7
gamma The second derivative of the price with regards to the underlying price 2.416523346501216e-10

Implied Volatility Surface

Retrieve calibrated and interpolated implied volatilities from options market prices. The implied_volatility_surface endpoint returns a volatility surface for a given list of expiries or time-to-expiries grid and a given set of strike prices or forward log moneyness grid. The computation includes space and time interpolation and allows users to compute consistent volatilities on non-listed strikes and non-listed expiries.

Data from Deribit & OKX can be included in the computation of implied volatility.

List of currently supported assets: BTC, ETH. More to be added soon.

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_surface?base=eth&quote=usd&time=2022-06-25T16:00:00.000Z&f_log_m_min=-1.5&f_log_m_max=1.5&f_log_m_step=0.05&expiry_list=2023-03-31T02:00:00.000Z,2022-08-28T08:00:00.000Z,2022-08-30T08:00:00.000Z,2022-09-01T08:00:00.000Z&exchange=drbt,okex'

Response Example

{
    "query": {
        "base": "eth",
        "quote": "usd",
        "time": "2022-06-25T16:00:00.000Z",
        "data_version": "v2",
        "commodity": "analytics",
        "request_time": "2023-04-06T08:37:04.051Z"
    },
    "time": "2023-04-06T08:37:05.456Z",
    "timestamp": 1680770225456,
    "data": [
        {
            "expiry": "2022-08-28T08:00:00.000Z",
            "time_to_expiry": 0.17442922374429223,
            "strike": 265.88827409960714,
            "forward_log_moneyness": -1.5,
            "implied_volatility": 1.8088997727784055,
            "delta": -0.009058250602524742,
            "gamma": 0.000027152549142705487
        },
        {
            "expiry": "2022-08-28T08:00:00.000Z",
            "time_to_expiry": 0.17442922374429223,
            "strike": 279.52065742622284,
            "forward_log_moneyness": -1.45,
            "implied_volatility": 1.7845929767916238,
            "delta": -0.01022163771763096,
            "gamma": 0.000030587874591936054
        },
        {
            "expiry": "2022-08-28T08:00:00.000Z",
            "time_to_expiry": 0.17442922374429223,
            "strike": 293.85198799221234,
            "forward_log_moneyness": -1.4,
            "implied_volatility": 1.7600100465171926,
            "delta": -0.011539347423429991,
            "gamma": 0.00003446720778881564
        },
        {
            "expiry": "2022-08-28T08:00:00.000Z",
            "time_to_expiry": 0.17442922374429223,
            "strike": 308.91810158884726,
            "forward_log_moneyness": -1.35,
            "implied_volatility": 1.7351444179560156,
            "delta": -0.013032741725007235,
            "gamma": 0.00003884923744431701
        },
        {
            "expiry": "2022-08-28T08:00:00.000Z",
            "time_to_expiry": 0.17442922374429223,
            "strike": 324.7566713477074,
            "forward_log_moneyness": -1.3,
            "implied_volatility": 1.7099896053160146,
            "delta": -0.01472630482905779,
            "gamma": 0.000043800533412823644
        },
        {
            "expiry": "2022-08-28T08:00:00.000Z",
            "time_to_expiry": 0.17442922374429223,
            "strike": 341.4073019431325,
            "forward_log_moneyness": -1.25,
            "implied_volatility": 1.6845392816389113,
            "delta": -0.016648129709696202,
            "gamma": 0.00004939658874760391
        },
        /* ... */
    ]
}

HTTP request

GET https://us.market-api.kaiko.io/v2/data/analytics.v2/implied_volatility_surface?base=eth&quote=usd&time=2022-06-25T16:00:00.000Z&f_log_m_min=-1.5&f_log_m_max=1.5&f_log_m_step=0.05&expiry_list=2023-03-31T02:00:00.000Z,2022-08-28T08:00:00.000Z,2022-08-30T08:00:00.000Z,2022-09-01T08:00:00.000Z&exchange=drbt,okex

Parameters

Parameter Required Description Comments Example
base Yes The desired base as the underlying of the options. btc and eth only available for now. btc, eth
quote Yes The desired quote as the underlying of the options. usd only available for now. usd
exchange Yes The desired exchange as source of options data. drbt only or drbt & okx available for now. drbt
time Yes The time at which to compute implied volatilities The time t should be smaller than the lowest requested expiry. 2022-06-25T16:00:00.000Z
expiry_list Yes, if the set of parameters (tte_min, tte_max, tte_step) is not used. The expiries for which the implied volatilities are to be computed. Expiries can be listed or non-listed ones. - Expiries must be between minimum and maximum listed maturities on exchanges.
- Either expiry_list or (tte_min, tte_max, tte_step) should be filled.		 expiry_list=2022-08-28T08:00:00.000Z, 2022-08-30T08:00:00.000Z
or tte_min=0.034288&tte_max=1&tte_step=0.02
tte_min Yes, if expiry_list is not used. To be used along with tte_max, tte_step. Minimum time-to-expiry on the time grid. - Strictly positive value allowed.
- Either expiry_list or (tte_min, tte_max, tte_step) should be filled.		 0.034288
tte_max Yes, if expiry_list is not used. To be used along with tte_min, tte_step. Maximum time-to-expiry on the time grid. - Maximum value is the highest time-to-maturities listed on exchanges.
- Either expiry_list or (tte_min, tte_max,tte_step) should be filled.		 1
tte_step Yes, if expiry_list is not used. To be used along with tte_min, tte_max. Step between two time-to-expiries in time grid. - Strictly positive value allowed.
Either expiry_list or (tte_min, tte_max, tte_step) should be filled.		 0.02
strike_list Yes, if the set of parameters (f_log_min, f_log_max, f_log_step) is not used. The strike prices for which the implied volatilities are to be computed. Strike prices can be listed or non-listed ones. - Strictly positives values allowed.
- Either strike_list or (f_log_m_min, f_log_m_max, f_log_m_step) should be filled.		 strike_list=25000, 29150, 29155, 29160
or f_log_m_min=-1.5&f_log_m_max=1.5&f_log_m_step=0.05
f_log_m_min Yes, if strike_list is not used. To be used along with f_log_m_max, f_log_m_step. Minimum forward log-moneyness on the space grid. Either strike_list or (f_log_m_min, f_log_m_max, f_log_m_step) should be filled. -1.5
f_log_m_max Yes, if strike_list is not used. To be used along with f_log_m_min, f_log_m_step. Maximum forward log-moneyness on the space grid. Either strike_list or (f_log_m_min, f_log_m_max, f_log_m_step) should be filled. 1
f_log_m_step Yes, if strike_list is not used. To be used along with f_log_m_min, f_log_m_max. Step between two forward log moneyness in space grid. Either strike_list or (f_log_m_min, f_log_m_max, f_log_m_step) should be filled. 0.02

Fields

Below information will be returned for each couple of strike/forward log-moneyness and expiry/time-to-expiry :

Field Description Example
time The time in parameter 2022-06-25T16:00:00Z
expiry The expiry at which the IV has been interpolated. 2022-08-28T08:00:00Z
time_to_expiry The associated time-to-expiry (in year). 0.17442922374429223
strike The strike at which the IV has been computed. 265.88827409960714
forward_log_moneyness The associated forward log-moneyness. -1.5
implied_volatility The calibrated and interpolated implied volatilities. 1.8088997727784055
delta The first derivative of the price with regards to the underlying price -0.009058250602524742
gamma The second derivative of the price with regards to the underlying price 0.000027152549142705487

Market & Asset Analytics

Asset Metrics

Retrieve off-chain and on-chain metrics that help performing asset analysis. Data is aggregated across all instruments trading the given asset (See Instruments Reference Data Endpoint).

Trading activity includes total volume (in USD and asset unit), total trade count, total CeX volume (in USD and asset unit), total CeX trade count, total DeX volume (in USD and asset unit), total DeX trade count and detailed information by exchange

Liquidity information includes total buy market depth (CeX only) for several price deviations (from 0.1% to 10%), total sell market depth (CeX only) for several price deviations (from 0.1% to 10%) and detailed information by exchange. Market Depth for DeXs available soon.

Token’s information include token’s address, total supply, number of holders (addresses), main holders (who owns more than 1% of the total supply). Only available for some ERC-20 tokens (new tokens can be added on demand).

Request Example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/analytics.v2/asset_metrics?interval=1d&asset=agix&start_time=2023-01-25T00:00:00.000Z&end_time=2023-01-26T00:00:00.000Z&page_size=100'

Response Example

{
    "data": [
        {
            "timestamp": "2023-01-25T00:00:00.000Z",
            "price": 0.1699233217119519,
            "total_volume_usd": 30508181.43789653,
            "total_volume_asset": 179540872.49784896,
            "total_trade_count": 159684,
            "off_chain_liquidity_data": {
                "total_off_chain_volume_usd": 30038710.382665947,
                "total_off_chain_volume_asset": 176778031.87949985,
                "total_off_chain_trade_count": 159115,
                "trade_data": [
                    {
                        "exchange": "binc",
                        "volume_usd": 27539301.29722444,
                        "volume_asset": 162068991,
                        "trade_count": 125188
                    },
                    {
                        "exchange": "cnex",
                        "volume_usd": 21755.03691474754,
                        "volume_asset": 128028.55249985002,
                        "trade_count": 1788
                    },
                    {
                        "exchange": "kcon",
                        "volume_usd": 2477654.0485267574,
                        "volume_asset": 14581012.327000001,
                        "trade_count": 32139
                    }
                ],
                "buy_market_depths": [
                    {
                        "exchange": "binc",
                        "volume_assets": {
                            "bid_volume0_1": 41225.09409594903,
                            "bid_volume0_2": 81128.84113629845,
                            "bid_volume0_3": 136713.70478078758,
                            "bid_volume0_4": 184468.7299124847,
                            "bid_volume0_5": 247978.1185353273,
                            "bid_volume0_6": 342865.65293127106,
                            "bid_volume0_7": 406858.0448413238,
                            "bid_volume0_8": 459003.4424915804,
                            "bid_volume0_9": 522211.069076861,
                            "bid_volume1": 594835.7130254924,
                            "bid_volume1_5": 985661.3971213808,
                            "bid_volume2": 1383255.3184562484,
                            "bid_volume4": 2486995.56685969,
                            "bid_volume6": 3575289.9565086393,
                            "bid_volume8": 4607508.4622772895,
                            "bid_volume10": 5450575.489737925
                        },
                        "volume_usds": {
                            "bid_volume0_1": 7005.104926671436,
                            "bid_volume0_2": 13785.68217252108,
                            "bid_volume0_3": 23230.846839898582,
                            "bid_volume0_4": 31345.539338714305,
                            "bid_volume0_5": 42137.26561340296,
                            "bid_volume0_6": 58260.87064701882,
                            "bid_volume0_7": 69134.67044466802,
                            "bid_volume0_8": 77995.38962539023,
                            "bid_volume0_9": 88735.8394922898,
                            "bid_volume1": 101076.46023018903,
                            "bid_volume1_5": 167486.8586821084,
                            "bid_volume2": 235047.33848780958,
                            "bid_volume4": 422598.5478036973,
                            "bid_volume6": 607525.145493328,
                            "bid_volume8": 782923.1427260847,
                            "bid_volume10": 926179.8924580172
                        }
                    }, 
                    /* ... */
                ],
                "sell_market_depths": [
                    {
                        "exchange": "binc",
                        "volume_assets": {
                            "ask_volume0_1": 63097.937138186375,
                            "ask_volume0_2": 121244.77666025238,
                            "ask_volume0_3": 188368.2488331742,
                            "ask_volume0_4": 253497.14370876888,
                            "ask_volume0_5": 315548.76436700544,
                            "ask_volume0_6": 368190.619211487,
                            "ask_volume0_7": 423885.42767195025,
                            "ask_volume0_8": 467798.8285213832,
                            "ask_volume0_9": 522878.5636214623,
                            "ask_volume1": 585135.1043450626,
                            "ask_volume1_5" :890220.5253171908,
                            "ask_volume2": 1192143.5688009772,
                            "ask_volume4": 2532666.2734223614,
                            "ask_volume6": 3837115.046884952,
                            "ask_volume8": 5175369.837650129,
                            "ask_volume10":6768831.15961039
                        },
                        "volume_usds": {
                            "ask_volume0_1": 10721.811071692562,
                            "ask_volume0_2": 20602.315190333822,
                            "ask_volume0_3": 32008.15854679647,
                            "ask_volume0_4": 43075.07670348604,
                            "ask_volume0_5": 53619.09420334357,
                            "ask_volume0_6": 62564.173039596295,
                            "ask_volume0_7": 72028.01989530912,
                            "ask_volume0_8": 79489.93083531322,
                            "ask_volume0_9": 88849.26238253305,
                            "ask_volume1": 99428.10058058261,
                            "ask_volume1_5": 151269.22871805582,
                            "ask_volume2": 202572.9951682029,
                            "ask_volume4": 430359.0659677582,
                            "ask_volume6": 652015.3345576031,
                            "ask_volume8": 879416.0339013551,
                            "ask_volume10":1150182.2747483607
                        }
                    }, 
                    /* ... */
                ],
                "total_buy_market_depth": {
                    "volume_assets": {
                        "bid_volume0_1": 66457.58211817831,
                        "bid_volume0_2": 125185.9379288117,
                        "bid_volume0_3": 204613.1694994421,
                        "bid_volume0_4": 277494.5823368924,
                        "bid_volume0_5": 372601.9870467177,
                        "bid_volume0_6": 501087.8551682802,
                        "bid_volume0_7": 595763.6983429149,
                        "bid_volume0_8": 674006.0040558478,
                        "bid_volume0_9": 761054.5994914122,
                        "bid_volume1": 851527.8858990098,
                        "bid_volume1_5": 1308167.4725325403,
                        "bid_volume2": 1727267.6160426897,
                        "bid_volume4": 2857166.5002753674,
                        "bid_volume6": 3971020.5977636343,
                        "bid_volume8": 5039070.880604726,
                        "bid_volume10":5903204.180101198
                    },
                    "volume_usds": {
                        "bid_volume0_1": 11292.693106465675,
                        "bid_volume0_2": 21272.010404489913,
                        "bid_volume0_3": 34768.54942735584,
                        "bid_volume0_4": 47152.801187755496,
                        "bid_volume0_5": 63313.76731545195,
                        "bid_volume0_6": 85146.51281971163,
                        "bid_volume0_7": 101234.1465778254,
                        "bid_volume0_8": 114529.33906296897,
                        "bid_volume0_9": 129320.92554973993,
                        "bid_volume1": 144694.44690231569,
                        "bid_volume1_5": 222288.16228825782,
                        "bid_volume2": 293503.0508034582,
                        "bid_volume4": 485499.222410903,
                        "bid_volume6": 674769.0105585777,
                        "bid_volume8": 856255.6623743254,
                        "bid_volume10":1003092.0630266753
                    }
                },
                "total_sell_market_depth": {
                    "volume_assets": {
                        "ask_volume0_1": 95923.98869360151,
                        "ask_volume0_2": 164213.70054806085,
                        "ask_volume0_3": 241848.44402388143,
                        "ask_volume0_4": 322655.2962131856,
                        "ask_volume0_5": 397630.666876821,
                        "ask_volume0_6": 460964.9874801942,
                        "ask_volume0_7": 524623.7489308078,
                        "ask_volume0_8": 575130.9078532174,
                        "ask_volume0_9": 636084.5501058105,
                        "ask_volume1": 703521.8123616874,
                        "ask_volume1_5": 1029473.840498065,
                        "ask_volume2": 1340846.321464341,
                        "ask_volume4": 2735683.341099355,
                        "ask_volume6": 4090342.103239072,
                        "ask_volume8": 5451549.738159413,
                        "ask_volume10":7058043.970665543
                    },
                    "volume_usds": {
                        "ask_volume0_1": 16299.722790676484,
                        "ask_volume0_2": 27903.737467738276,
                        "ask_volume0_3": 41095.690959404994,
                        "ask_volume0_4": 54826.65970049826,
                        "ask_volume0_5": 67566.72373024802,
                        "ask_volume0_6": 78328.70186554291,
                        "ask_volume0_7": 89145.81006729993,
                        "ask_volume0_8": 97728.15428162923,
                        "ask_volume0_9": 108085.59964363185,
                        "ask_volume1": 119544.76325331048,
                        "ask_volume1_5": 174931.61459299136,
                        "ask_volume2": 227841.06084847247,
                        "ask_volume4": 464856.40047165315,
                        "ask_volume6": 695044.5171206347,
                        "ask_volume8": 926345.4399859692,
                        "ask_volume10":1199326.2762845035
                    }
                }
            },
            "on_chain_liquidity_data": {
                "total_on_chain_volume_usd": 2762840.6183491,
                "total_on_chain_volume_asset": 2762840.6183491,
                "total_on_chain_trade_count": 569,
                "trades_data": [
                    {
                        "exchange": "usp2",
                        "volume_usd": 327680.4492221988,
                        "volume_asset": 1928401.8575017697,
                        "trade_count": 448
                    },
                    {
                        "exchange": "usp3",
                        "volume_usd": 141790.6060083834,
                        "volume_asset": 834438.7608473302,
                        "trade_count": 121
                    }
                ],
                "token_information": [
                    {
                        "blockchain": "ethereum",
                        "token_address": "0x5B7533812759B45C2B44C19e320ba2cD2681b542",
                        "nb_of_holders": 38231,
                        "main_holders": [
                            {
                                "address": "0xf977814e90da44bfa03b6295a0616a897441acec",
                                "amount": 250774980,
                                "percentage": 22.61839
                            },
                            {
                                "address": "0x13e1367a455c45aa736d7ff2c5656ba2bd05ad46",
                                "amount": 112149660,
                                "percentage": 10.11522
                            }, 
                            /* ... */
                        ],
                        "total_supply": 1108721700
                    }
                ]
            }
        }
    ]
}

HTTP request

GET https://us.market-api.kaiko.io/v2/data/analytics.v2/asset_metrics?interval=1d&asset=agix&start_time=2023-01-25T00:00:00.000Z&end_time=2023-01-26T00:00:00.000Z&page_size=100

Parameters

Parameter Required Description Comments Example
asset Yes The desired asset code. See Instruments Reference Data Endpoint. agix
start_time Yes Starting time in ISO 8601 (inclusive). 2023-01-25T00:00:00.000Z
end_time Yes Ending time in ISO 8601 (exclusive). 2023-01-26T00:00:00.000Z
interval Yes The interval at which we want information 1h (available intervals: 1h/1d) 1h
sources No boolean. If true, returns trading information and market depths detailed by exchanges as well as main holders. (Default: false)
page_size No See Pagination (min: 1, default: 100, max: 100). Default: 10 100

Fields

Field Category Description Example
timestamp Trading activity Timestamp at which the interval begins. 2023-01-25T00:00:00.000Z
price Trading activity Average price in usd. null when no trades are reported. 0.1699233217119519
total_volume_usd Trading activity Total volume in usd traded in the interval. 0 when no trades are reported. 30508181.43789653
total_volume_asset Trading activity Total volume in number of assets traded in the interval. 0 when no trades are reported. 179540872.49784896
total_trade_count Trading activity The total amount of trades reported during the interval. 0 when no trades are reported. 159684
total_off_chain_volume_usd Trading activity Total off-chain volume in usd traded in the interval. 0 when no trades are reported. 30038710.382665947
total_off_chain_volume_asset Trading activity Total off-chain volume in number of assets traded in the interval. 0 when no trades are reported. 176778031.87949985
total_off_chain_trade_count Trading activity The total amount of trades reported off-chain during the interval. 0 when no trades are reported. 159115
trades_data Trading activity List of volume in usd, volume in number of assets and total amount of trades by centralized exchange. [{"exchange": "binc",
"volume_usd": 27539301.29722444,
"volume_asset": 162068991,
"trade_count": 125188}, ...]
total_on_chain_volume_usd Trading activity Total on-chain volume in usd traded in the interval. 0 when no trades are reported. 1036710779.1918713
total_on_chain_volume_asset Trading activity Total on-chain volume in number of assets traded in the interval. 0 when no trades are reported. 1036710779.1918713
total_on_chain_trade_count Trading activity The total amount of trades reported on-chain during the interval. 0 when no trades are reported. 20513
trades_data Trading activity List of volume in usd, volume in number of assets and total amount of trades by decentralized exchange. [{'exchange': 'blc2',
'volume_usd': 673716.6525764248,
'volume_asset': 674153.2032810001,
'trade_count': 129}, ...]
market_depth Liquidity information Dictionary from 0.1% to 10% market depth.
blockchain Token information Blockchain name. ethereum
token_address Token information Token address. 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
number_of_holders Token information Total amount of holders. 1622286
main_holders Token information List of addesses holding at least 1% of the total supply and the amounts of tokens. [{'address': '0x0a59649758aa4d66e25f08dd01271e891fe52199',
'amount': 3262712000,
'percentage': 7.91745}, ...]
total_supply Token information Blockchain total supply. 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

CSV Files

Trade data

A CSV file of tick-by-tick trades.

File Structure Details

Column Description Example
id Unique trade ID (unique to the exchange). In case the exchange does not provide an ID, we generate it ourselves. 1661990400274591751
exchange Kaiko legacy slug for an exchange bw
symbol Data feed code in lower case btcusd_perp
date The timestamp provided by the exchange in Unix Timestamp (in milliseconds) 1676246400344
price Executed price 21779.5
amount Quantity of asset bought or sold (can be in base_asset, quote_asset or the number of contracts). 402
sell See Taker Side Sell true

Order Book Snapshots (Raw)

A CSV file of Order Book Snapshots: Raw.

File Structure Details

Column Description Example
date The timestamp when we send the REST API requests to exchanges in Unix Timestamp (in milliseconds) 1676246400344
type Type(side) of the limit orders on the orderbook snapshot. a: ask. b: bid. a
price Quoted price 21779.5
amount Amount of limit orders at the specific price (can be in base_asset, quote_asset or the number of contracts). 402

Tick-Level Order Book

CSV tick by tick full order book files are designed for institutional clients engaged in strategy backtesting and quantitative modeling, with a precision level that order book snapshots cannot provide. All data is normalized and the exchange format is independent making file integration quick and easy. The data includes all necessary information to rebuild an exchange order book for a given instrument:

File Structure Details

Column Description Example
timestamp Timestamp when the exchanges send the data or we collect the data, depending on exchanges. In the epoch format. 1661990400274591751
type Type of the message. s: snapshot. u: update. s
asks List of [ask price, volume] [[20103,0],[20207,0],[20057,1.00111351]]
bids List of [bid price, volume] [[19584,0],[19904,21.9973]]

How to create a local order book with CSV files

  1. Download the CSV files, which usually start with updates (type: u).
  2. Ignore the updates before the 1st snapshot (type: s) that appears in the CSV file.
  3. If the prices in the updates exist in the locally managed order book, update the amount. The amount 0 means to remove the price level from the order book, because it is cancelled or filled.
  4. If the prices in the updates do not exist in the locally managed order book, insert that price level in the order book.
  5. Receiving an update that removes a price level that is not in your local order book is a normal exchange's behavior that can happen. In this case, you can just ignore the updates.

Top of Book

A CSV file of tick-level updates of the best bid and best ask on an order book (quotes).

File Structure Details

Column Description Example
ts_exchange Timestamp when the exchanges send the data. In the epoch format. 1661990400274591751
ts_collection Timestamp when we collect the data. In the epoch format. 1661990400274591751
exchange Exchange code. See Exchanges Reference Data Endpoint binc
class The instrument class of the instrument 1676246400344
symbol Kaiko identifier for the instrument 21779.5
type a stands for ask, while b stands for bid. Tells which side has an update on price or size a
price Price displayed in quote currency 20289.2
size Limit order size of the quotes 0.8

Derivatives Metrics

A CSV file of derivatives metrics, with the data from Risk and Price endpoints.

File Structure Details

Column Description Example
timestamp The starting timestamp of the time interval, expressed in Unix Timestamp (in seconds) 1685405460
24h_volume The volume of the trades executed in the last 24 hours (can be in base_asset, quote_asset or the number of contracts) 1849370
ask The price of the best ask within one minute interval 0.4941
bid The price of the best bid within one minute interval 0.4940
ask_amount The amount of the best ask, associated with the best ask price.
bid_amount The amount of the best bid, associated with the best bid price.
funding_rate perpetual-future only. The current funding rate. 0.00020546
mark_price The mark price of the contract. It is used for calculating profit and loss (PnL) and liquidation price. Designed to be fair and avoid price manipulation. 39713.5
predicted_funding_rate perpetual-future only. The predicted funding rate for the next period. 0.00010447
price Most recent traded price of derivative contract 39767
index_price The price of the underlying index, often as a weighted average across multiple exchanges' spot prices 39745.9

OHLCV candles

A CSV file of OHLCV candles.

File Structure Details

Column Description Example
timestamp The starting timestamp of the time interval, expressed in Unix Timestamp (in milliseconds) 1672531200000
open The opening price of a candle 0.4935
high The highest price of a candle 0.4941
low The lowest price of a candle 0.4930
close The closing price of a candle 0.4937
volume The volume of the trades executed within the time interval of a candle (can be in base_asset, quote_asset or the number of contracts) 86092.08

VWAP

A CSV file of VWAP.

File Structure Details

Column Description Example
timestamp The starting timestamp of the time interval, expressed in Unix Timestamp (in milliseconds) 1672531200000
vwap The volume weighted price during the time interval. null when no trades reported. 0.4935

Count-OHLCV-VWAP

A CSV file of Count-OHLCV-VWAP.

File Structure Details

Column Description Example
timestamp The starting timestamp of the time interval, expressed in Unix Timestamp (in milliseconds) 1672531200000
count Then number of trades. 0 when no trades reported. 321
open Opening price of interval. null when no trades reported. 0.4935
high Highest price during interval. null when no trades reported. 0.4951
low Lowest price during interval. null when no trades reported. 0.4911
close Closing price of interval. null when no trades reported. 0.4939
volume Volume traded in interval. 0 when no trades reported. 62.32
vwap The volume weighted price during the time interval. null when no trades reported. 0.4945

DEX Liquidity Events

File Structure Details

Field Description Example
block_number The height of the block. 16028979
timestamp The timestamp of the block. 1669161611000
datetime The date equivalent. 2023-02-12T00:00:11Z
pool_name Name of the pool as it is written on the blockchain. USDC-WETH
type Event type. By default both burn and mint are shown. burn or mint
transaction_hash Filter on a specific transaction hash. 0xe68b84740**
price The price at this block. 0.0006495312950691
symbols The symbols of the tokens in the pool, separated by a semi-colon. USDC;WETH
addresses The addresses of the tokens in the pool, separated by a semi-colon. 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48;0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
amounts The amounts of liquidity of each token, separated by a semi-colon. 4.3800141550673e+07;28449.56266562047

DEX Liquidity Snapshots

File Structure Details

Field Description Example
block_number The height of the block. 16028979
timestamp The timestamp of the block. 1669161611000
datetime The date equivalent. 2023-02-12T00:00:11Z
pool_name Name of the pool as it is written on the blockchain. USDC-WETH
price The price at this block. 0.0006495312950691
symbols The symbols of the tokens in the pool, separated by a semi-colon. USDC;WETH
addresses The addresses of the tokens in the pool, separated by a semi-colon. 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48;0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
amounts The amounts of liquidity of each token, separated by a semi-colon. 4.3800141550673e+07;28449.56266562047

Uniswap v3 Liquidity Snapshots

Uniswap’s v3 liquidity snapshots are represented by a distribution of liquidity amongst all possible price levels for a pair of tokens. Each price range is defined by the interval [lower_tick, upper_tick[. This dataset provides the amount of tokens and liquidity made available at each price level. The range of price levels is limited to ±10% around the current price of each block. The data is provided in a block-by-block granularity.

File Structure Details

Field Description Example
block_number The height of the block. 16028979
timestamp The timestamp of the block. 1669161611000
lower_tick The lower tick of the range. -59580
upper_tick The upper tick of the range. -59520
current_price The current price at this block, normalized using the pool’s tokens decimals. 0.0028577887443084
current_tick The current tick at this block. -58580
amount The amount of liquidity in the specified tick range. 1.7305248294559624e+23
amount0 The amount of token0 in the specified tick range, normalized using the token0 decimals. 0
amount1 The amount of token1 in the specified tick range, normalized using the token1 decimals. 26.4381078606

Lending and Borrowing Protocols Events

File Structure Details

Field Description Example
blockchain The blockchain on which the transaction happened. ethereum
protocol Code of the L&B protocol. aave/v2
block_number The height of the block in which the transaction happened. 16025918
datetime The timestamp of the block in which the transaction happened. 1669124591
transaction_hash Transaction hash ---
log_index Log index of the transaction 152
type Event type: Borrow, deposit, withdraw, repayment or liquidation. borrow, deposit, etc
user_address Address of the user. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
asset_symbol Symbol of the underlying asset. crv
asset_address Address of the underlying asset. 0xd533a949740bb3306d119cc777fa900ba034cd52
asset_decimals Decimals of the underlying asset. 18
receipt_symbol Symbol of the receipt asset. acrv
receipt_address Address of the receipt asset. 0x8dae6cb04688c62d939ed9b68d32bc62e49970b1
receipt_decimals Decimals of the receipt asset. 18
amount Amounts of the borrowed token. 299894.78

As well as the following fields specific to each event type:

Borrow Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
rate Borrow rate (at the event level or at the contract level depending on the protocol). 0.02820253961814756
rate_type Stable (1) or Variable (2) 1 or 2
on_behalf_of The address of user who will incur the debt. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Deposit Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
rate Supply rate of the overall lending pool. 0.000203088325657998768898798
on_behalf_of The address that will receive the receipt tokens. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Withdraw Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
on_behalf_of The address that will receive the underlying token. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Repayment Event

Field Description Example
amount_receipt Amounts of the receipt token. 299899
on_behalf_of The address of user who will incur the debt. 0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31
borrow_rate_mode Stable (1) or Variable (2) 1 or 2

Liquidation Event

Field Description Example
liquidation_debt_asset_symbol Symbol of the debt asset. renfil
liquidation_debt_asset_address Address of the debt asset. 0xd5147bc8e386d91cc5dbe72099dac6c9b99276f5
liquidation_debt_asset_decimals Decimals of the debt asset. 18
liquidation_debt_amount_in_asset Amount of the debt asset. 1899
liquidation_caller_address The address that triggered the liquidation transaction. 0xdfd3bd446f1b7fd96dc995126ee845af0b1254cd
receive_receipt_token The liquidator chooses to receive the collateral's asset (False) or recept token (True). True or False
liquidation_type Debt (1) or Collateral (2) 1

Data Feed

Receive historical and on-going data directly to your cloud provider. If you purchased a monthly subscription of Trade Data, 10% Order Books, OHLCV or VWAP, your data will be delivered once a day to your cloud bucket. We currently support Amazon Web Services S3 and Google storage. Cloud storage services allow us to easily synchronize our data with you once a day.

Cloud providers offer extensive storage services that will help you store large amounts of data. This eases the integration setup to feed whatever system you choose to integrate the data with.

If you do not already have a cloud provider, we suggest working with Amazon Web Services which is a major provider with a strong track record.

AWS S3 - How to receive our data through

  1. You will need to have access to an AWS account, which can be created here https://aws.amazon.com/resources/create-account/
  2. You will also need to retrieve your AWS account ID, as well as your AWS canonical ID, the instructions regarding this step can be found here: https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html
  3. The AWS account ID as well as the canonical ID should be sent to: support@kaiko.com.
  4. Our team will create an AWS bucket to which you have all the needed permissions to access its objects and will contact you to confirm the details. If you have any questions regarding this process, you can contact: support@kaiko.com

GCS - How to receive our data through

  1. Open https://console.cloud.google.com/storage/
  2. We suggest calling the bucket kaiko-delivery-nameofyourcompany
  3. Once created, click on the "3 dots" on the right side of the corresponding bucket
  4. Click on Edit bucket permissions: GCS_Bucket_Permissions_Tab
  5. Press Add members and add our service account kaiko-facteur@kaiko-facteur.iam.gserviceaccount.com
  6. Press on Select a role, select Storage, then select Storage Admin as follows:
    GCS_Bucket_Add_Perm
  7. Press on Add to validate the changes
  8. Enter the details into this form
  9. You should receive a confirmation email within a few working days confirming that the integration was set up correctly

For other cloud providers

Please contact us at support@kaiko.com.

Future development

We are continously extending the feature set across all our products. We are very happy to receive your feedback on our services and documentation. Do you have a proposal on how we can make your day better? Give us a shout!

curl python