Tokens in a liquidity pool (Uniswap v3)

What is this endpoint for?

The Uniswap V3 Liquidity Estimator offers insight into the token reserves on Uniswap V3.

This data shows the liquidity across all the price levels for a specific pair of tokens on Uniswap V3. Each price level has a range, which is shown as lower_tick (the lowest price of the level) and upper_tick (the highest price of the level). The data shows you the amount of tokens and liquidity available at each price level. We display all price-levels up to 10% either side of the current block price. The data is provided in a block-by-block granularity. Access the methodology here.

Endpoint

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

Parameters

Parameter	Required	Description	Example
pool_address	Yes	Pool address.	0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640
blockchain	No	Should be one of the currently supported blockchains. Blockchain codes	ethereum
live	No	Shows the data as soon as the block is validated. (Default: false, in case of block reorganization).	true
start_block	No	Starting block height (inclusive).	19645000
end_block	No	Ending block height (inclusive).	19645010
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_size	No	Number of snapshots to return data for. (default: 10, min: 1, max: 10). See Pagination	10

Fields

Field	Description	Example
blockchain	The blockchain on which the transaction happened.	ethereum
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. In seconds.	1669161611
snapshots	The snapshot of the liquidity at each tick of the pool.	See table below.

Field snapshots

Field snapshot	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

Request examples

cURL

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: KAIKO_API_KEY' \
  'https://us.market-api.kaiko.io/v2/data/liquidity.v1/snapshots/usp3?pool_address=0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640'

Python

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

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
pool_address = "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"

# ---- Optional parameters ---- #
blockchain = "ethereum"
live = "false"
start_block = None
end_block = None
start_time = "2022-04-01T00:00:00.000Z"
end_time = "2022-04-01T00:02:00.000Z"
sort = "desc"
price_range = None
page_size = 100

# ---- 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, pool_address: str, blockchain: str, live: str, 
                  start_block: str, end_block: str, start_time: str, 
                  end_time: str, sort: str, price_range: 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/snapshots/usp3'
    params = {
        "pool_address": pool_address,
        "blockchain": blockchain,
        "live": live,
        "start_block": start_block,
        "end_block": end_block,
        "start_time": start_time,
        "end_time": end_time,
        "sort": sort,
        "price_range": price_range,
        "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:
            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:
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, pool_address=pool_address, blockchain=blockchain, 
                   live=live, start_block=start_block, end_block=end_block, 
                   start_time=start_time, end_time=end_time, sort=sort, 
                   price_range=price_range, page_size=int(page_size))

Response example

{
    "query": {
        "blockchain": "ethereum",
        "protocol": "usp3",
        "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
        "start_block": "*",
        "end_block": "*",
        "start_time": "*",
        "end_time": "*",
        "sort": "descending",
        "page_size": "10",
        "live": "false",
        "price_range": "0.1"
    },
    "time": "2024-09-27T14:03:53.973Z",
    "timestamp": 1727445833,
    "data": [
        {
            "block_number": "20842364",
            "pool_name": "liquidity_pool",
            "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
            "current_tick": "197507",
            "current_price": 0.00037773843033961135,
            "datetime": 1727444963,
            "blockchain": "ethereum",
            "exchange": "usp3",
            "snapshots": [
                {
                    "amount0": 0,
                    "amount1": 21.540770877363897,
                    "amount": 2335301572930716700,
                    "lower_tick": 196460,
                    "upper_tick": 196470
                },
                {
                    "amount0": 0,
                    "amount1": 21.58927177741234,
                    "amount": 2339389776616961000,
                    "lower_tick": 196470,
                    "upper_tick": 196480
                },
                ...
            ]
        },
        ...
     ],
    "continuation_token": "xxx",
    "next_url": "https://us.market-api.kaiko.io/v2/data/liquidity.v1/snapshots/usp3?continuation_token=xxx"
 }