# All 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

{% code overflow="wrap" %}

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

{% endcode %}

### Path Parameters

<table><thead><tr><th width="203">Parameter</th><th>Required?</th><th>Description</th></tr></thead><tbody><tr><td><code>region</code></td><td>Yes</td><td>Choose between <code>eu</code> and <code>us</code>.</td></tr><tr><td><code>exchange</code></td><td>Yes</td><td><p>Exchange <code>code.</code> </p><p><br>See <a data-mention href="../../reference-data/basic-tier/exchange-codes">exchange-codes</a></p></td></tr><tr><td><code>instrument_class</code></td><td>Yes</td><td>Instrument <code>class</code>. <br><br>See <a data-mention href="../../reference-data/basic-tier/exchange-trading-pair-codes-instruments">exchange-trading-pair-codes-instruments</a></td></tr><tr><td><code>instrument</code></td><td>Yes</td><td>Instrument <code>code</code>.<br><br>See <a data-mention href="../../reference-data/basic-tier/exchange-trading-pair-codes-instruments">exchange-trading-pair-codes-instruments</a></td></tr></tbody></table>

### Query Parameters

<table><thead><tr><th width="231">Parameter</th><th width="109">Required</th><th width="379">Description</th></tr></thead><tbody><tr><td><code>start_time</code></td><td>No</td><td>Starting time in ISO 8601 (inclusive). <br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>end_time</code></td><td>No</td><td>Ending time in ISO 8601 (exclusive). <br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>page_size</code></td><td>No</td><td>See <a data-mention href="../../../general/getting-started/pagination">pagination</a><br><br><em>Automatically included in continuation tokens.</em></td></tr><tr><td><code>continuation_token</code></td><td>No</td><td>See <a data-mention href="../../../general/getting-started/pagination">pagination</a></td></tr><tr><td><code>sort</code></td><td>No</td><td>Return the data in ascending (asc) or descending (desc) order. Default desc.</td></tr></tbody></table>

**The following parameters are unique to on-chain instruments.**

<table><thead><tr><th width="233">Parameter</th><th width="113">Required?</th><th>Description</th></tr></thead><tbody><tr><td><code>blockchain</code></td><td>No</td><td>Filter on a specific blockchain. (Default: ethereum).</td></tr><tr><td><code>pool_address</code></td><td>No</td><td>Filter on a specific pool address.</td></tr><tr><td><code>transaction_hash</code></td><td>No</td><td>Filter on a specific transaction hash. (Several trades can happen within a single transaction).</td></tr><tr><td><code>user_address</code></td><td>No</td><td>Filter on a specific address.</td></tr><tr><td><code>start_block</code></td><td>No</td><td>Starting block height (inclusive).</td></tr><tr><td><code>end_block</code></td><td>No</td><td>Ending block height (inclusive).</td></tr></tbody></table>

### 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](https://docs.kaiko.com/rest-api/general/getting-started/api-output/taker_side_sell-explained "mention") |

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

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```url
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'
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

```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))
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response example

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

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

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

{% endtab %}
{% endtabs %}