Tick-Level Trades

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.

Endpoint

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

Parameters

Parameter	Required?	Description
region	Yes	Choose between eu and us.
exchange	Yes	Exchange code. See Exchanges
instrument_class	Yes	Instrument class. See Instruments
instrument	Yes	Instrument code. See Instruments
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.

The following parameters are unique to on-chain instruments.

Parameter	Required?	Description
blockchain	No	Filter on a specific blockchain. (Default: ethereum).
pool_address	No	Filter on a specific pool address.
transaction_hash	No	Filter on a specific transaction hash. (Several trades can happen within a single transaction).
user_address	No	Filter on a specific address.

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" Explained

The following fields are unique to on-chain instruments.

Field	Description
blockchain	The blockchain on which the trade happened.
transaction_hash	Transaction hash.
log_index	The log index of the transaction (in base 10).
pool_address	The address of the pool in which the trade happened.
user_address	Address that triggered the transaction.

Request examples

cURL

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'

Python

import http.client
import json

# Enter your Kaiko API Key
api_key = "KAIKO_API_KEY"
api_host = "us.market-api.kaiko.io"
api_base_endpoint = "/v3/data/trades.v1/exchanges/{exchange}/{instrument_class}/{instrument}/trades"

# Start of mandatory parameter configuration
exchange = "bfnx"
instrument_class = "spot"
instrument = "btc-usd"
# End of mandatory parameter configuration

# Start of optional parameter configuration
optional_params = {
    "sort": "desc",
    "start_time": "2024-09-25T11:16:35.947Z",
    "end_time": "2024-09-27T11:16:35.947Z",
}
# End of optional parameter configuration

conn = http.client.HTTPSConnection(api_host)
headers = {
    "X-Api-Key": api_key,
    "Accept": "application/json"
}

api_endpoint = api_base_endpoint.format(exchange=exchange, instrument_class=instrument_class, instrument=instrument)

url_params = []
for param, value in optional_params.items():
    url_params.append(f"{param}={value}")
url_params = '&'.join(url_params)

# Initial request
endpoint_with_params = f"{api_endpoint}?{url_params}"

# Pagination for next pages
all_trades = []
next_url = endpoint_with_params
while next_url:
    conn.request("GET", next_url, headers=headers)
    response = conn.getresponse()
    data = json.loads(response.read().decode("utf-8"))
    all_trades.extend(data.get("data", []))
    print(f"Fetched {len(data.get('data', []))} datapoints. Total: {len(all_trades)}")
    next_url = data.get("next_url", "").replace("https://us.market-api.kaiko.io", "")
    if not next_url:
        break
conn.close()
print(f" datapoints fetched: {(all_trades)}")

Ruby

message = "hello world"
puts message

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

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