Mints and burns

What is this endpoint for?

This endpoint includes event data related to the addition (mint) and removal (burn) of tokens from a liquidity pool.

Endpoint

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

Parameters

Parameter	Required	Description	Example
blockchain	No	Should be one of the currently supported blockchains. See Blockchain codes	ethereum
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	Mints and burns 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**
live	No	Shows the data as soon as the block is validated. (Default: false, in case of block reorganization).	true
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_size	No	Number of snapshots to return data for. (default: 1000, min: 1, max: 1000). See Pagination	500

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.	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)	152
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 seconds.	1650441900
metadata	Only for Uniswap v3. Upper and lower ticker of the interval on which the liquidity is provided	{"lower_ticker": 190650, "upper_ticker": 195610}

Request example

cURL

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

Python

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

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
blockchain = "ethereum" 
protocol = "usp2"
pool_address = None
pool_contains = "weth"
block_number = None
user_addresses = None
live = "false"
tx_hash = None
start_block = None
end_block = None
start_time = "2025-03-05T13:00:00Z"
end_time = None
sort = "asc"
type = "burn"
page_size = 500

# ---- 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, blockchain: str, protocol: str, pool_address: str, pool_contains: str, block_number: int, user_addresses: str, live: str, tx_hash: str, start_block: int, end_block: int, start_time: str, end_time: str, sort: str, type: str, page_size: int):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://eu.market-api.kaiko.io/v2/data/liquidity.v1/events'
    params = {
        "blockchain": blockchain,
        "protocol": protocol,
        "pool_address": pool_address,
        "pool_contains": pool_contains,
        "block_number": block_number,
        "user_addresses": user_addresses,
        "live": live,
        "tx_hash": tx_hash,
        "start_block": start_block,
        "end_block": end_block,
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "type": type,
        "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, blockchain=blockchain, protocol=protocol, pool_address=pool_address, pool_contains=pool_contains, block_number=block_number, user_addresses=user_addresses, live=live, tx_hash=tx_hash, start_block=start_block, end_block=end_block, start_time=start_time, end_time=end_time, sort=sort, type=type, page_size=page_size)
print (df)

Response example

{
  "query": {
    "blockchain": "*",
    "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": [
    {
      "blockchain": "ethereum",
      "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"
}