Tokens in a liquidity pool (Uniswap)

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 aslower_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 blockchain.	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).	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
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

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 = "/v2/data/liquidity.v1/snapshots/usp3"

# Start of mandatory parameter configuration
mandatory_params = {
    "pool_address": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
}
# End of mandatory parameter configuration

# Start of optional parameter configuration
optional_params = {
}
# End of optional parameter configuration
conn = http.client.HTTPSConnection(api_host)
headers = {
    "X-Api-Key": api_key,
    "Accept": "application/json"
}

all_params = {**mandatory_params, **optional_params}

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

# Pagination for next pages
all_data = []
next_url = f"{api_base_endpoint}?{url_params}"
while next_url:
    conn.request("GET", next_url, headers=headers)
    response = conn.getresponse()
    data = json.loads(response.read().decode("utf-8"))
    all_data.extend(data.get("data", []))
    print(f"Fetched {len(data.get('data', []))} datapoints. Total: {len(all_data)}")
    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_data)}")

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