Tick-level trades

This data is included in the following Kaiko packages:

• Level 1 & Level 2 Data [Level 1 Tick-Level Tier]
• Level 1 & Level 2 Data [Level 2 Aggregations Tier]
• Level 1 & Level 2 Data [Level 2 Tick-Level Tier]

CeFi Spot ticker packs.

What is this endpoint for?

Tick-level data is the most granular level of trading data and contains every single trade that occurs on centralized and decentralized exchanges. The data is normalized and timestamped and contains information such as the price and volume of each trade. For DEXs specifically, we also provide additional information on the user address, the blockchain, the pool address, and the transaction hash related to the trade. Read our DEX trade data methodology here.

You can use this same endpoint to get data for all market types. Kaiko subscriptions are sold per market type.

Endpoint

https://{region}.market-api.kaiko.io/v3/data/trades.v1/exchanges/{exchange}/spot/{instrument}/trades

Path Parameters

Parameter	Required?	Description
region	Yes	Choose between eu and us.
exchange	Yes	Exchange code. See
instrument_class	Yes	Instrument class. See
instrument	Yes	Instrument code. See

Query Parameters

Parameter	Required	Description
start_time	No	Starting time in ISO 8601 (inclusive). Automatically included in continuation tokens.
end_time	No	Ending time in ISO 8601 (exclusive). Automatically included in continuation tokens.
page_size	No	See Pagination Automatically included in continuation tokens.
continuation_token	No	See Pagination
sort	No	Return the data in ascending (asc) or descending (desc) order. Default desc.

Fields

Field	Description
timestamp	The timestamp provided by the exchange or the collection timestamp in Unix Timestamp (in nanoseconds)
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" Explained

Field	Description
blockchain	The blockchain on which the trade happened.
transaction_hash	Transaction hash.
log_index	The log index of the event (in base 10).
pool_address	The address of the pool in which the trade happened.
user_address	Trader address (beneficiary).

Request examples

cURL

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

Python

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

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
exchange = "cbse" 
instrument_class = "spot"
pair = "btc-usd" #called "instrument" in the documentation

# ---- Optional parameters ---- #
sort = "desc"
page_size = "100"
start_time= "2023-01-01T00:00:00Z"
end_time= "2023-01-01T00:03:00Z"

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, exchange: str, pair: str, instrument_class: str, start_time: str, end_time: str, sort: str, page_size: int):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v3/data/trades.v1/exchanges/{exchange}/{instrument_class}/{pair}/trades'
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "page_size": page_size
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, exchange=exchange, pair=pair, instrument_class=instrument_class, start_time=start_time, end_time=end_time ,sort=sort, page_size=int(page_size))

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,
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    },
    "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/v3/data/trades.v1/exchanges/bfnx/spot/btc-usd/trades?continuation_token=rbd28vrmb1cwaxfykuJBKAABhNi1Bfv1EY55P3QPSnYnm8VuX1LqLhA2d3yVfYgMKtfBYxJg7sHrkTfkQGysW23Lm9Lp9rsVpVk2Esmgz9VQZvNE4xWN8hh3LgLrCa7ty4B3YGCwtH"
}

JSON

{
    "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,
    "access": {
        "access_range": {
            "start_timestamp": null,
            "end_timestamp": null
        },
        "data_range": {
            "start_timestamp": null,
            "end_timestamp": null
        }
    },
    "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/v3/data/trades.v1/exchanges/bfnx/spot/btc-usd/trades?continuation_token=rbd28vrmb1cwaxfykuJBKAABhNi1Bfv1EY55P3QPSnYnm8VuX1LqLhA2d3yVfYgMKtfBYxJg7sHrkTfkQGysW23Lm9Lp9rsVpVk2Esmgz9VQZvNE4xWN8hh3LgLrCa7ty4B3YGCwtH"
}