Lending Users Positions

This data is included in the following Kaiko packages:

• Level 1 & Level 2 Data [Level 2 Aggregations]
• Level 1 & Level 2 Data [Level 2 Tick-Level]

DeFi lending & borrowing ticker packs.

What is this endpoint for?

This endpoint returns a user's positions on lending and borrowing protocols. For a given wallet address, it reports the assets supplied and borrowed, their principal and accrued interest (in both token and USD terms), the applicable interest rates and APYs, and position-level health metrics such as the health factor and available borrowing capacity, at each block over the requested time range.

Endpoint

https://eu.market-api.kaiko.io/v2/data/lending.v1/addresses/{user_address}/positions

Parameters

Parameter	Mandatory?	Description	Example
block_number	No	Block height.	21795593
start_block	No	Starting block height, inclusive.	21795593
end_block	No	Ending block height, inclusive.	22795593
datetime	No	Time in ISO 8601, inclusive.	2022-04-01T00:00:00.000Z
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
interval	No	Interval between snapshots. Use s, m, h, d, b, or change. Default: 1d.	1h
sort	No	Sort order. Default: desc.	ascending
page_size	No	Snapshots per response. Default: 100; minimum: 1; maximum: 1000. See Pagination.	1000

Fields

Field	Description	Example
user_address	Address of the user's wallet.	0x1d296f5efbbb235c7a90734c2469fe8dc21e132d
blockchain	Blockchain on which the position exists.	ethereum
block_number	Block height at which the position was read.	25225970
timestamp	Timestamp of the block.	2026-06-02T00:00:00Z
protocol	Lending and borrowing protocol code.	aav3
health_factor	Position health factor. Values below 1 are eligible for liquidation.	1.839684
total_collateral_usd	Total collateral value in USD.	42075.46
total_supplied_usd	Total supplied value in USD.	42075.46
total_debt_usd	Total debt value in USD.	18982.95
available_borrows_usd	Remaining borrowing capacity in USD.	14887.79
net_worth_usd	Position net worth in USD.	23092.51
net_apy	Net APY across the position.	-0.003917
total_supply_accrued_interest_usd	Total accrued supply interest in USD.	6.58
total_borrow_accrued_interest_usd	Total accrued borrow interest in USD.	6.97
total_principal_supplied_usd	Principal supplied, excluding interest, in USD.	42068.88
total_principal_borrowed_usd	Principal borrowed, excluding interest, in USD.	18975.99
roi	Return on investment across the position.	-0.000017
supplies	Array of supplied assets.	See Supplies.
borrows	Array of borrowed assets.	See Borrows.

Supplies

Field	Description	Example
asset	Symbol of the supplied asset.	weth
asset_address	Underlying asset address.	0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
atoken_address	Receipt aToken address.	0x4d5f47fa6a74757f35c14fd3a6ef8e3c9bc514e8
scaled_balance	Scaled aToken balance in raw units.	19697531323085677000
supplied_amount	Supplied amount in token units.	21.0032861479522399
supplied_amount_usd	Supplied amount in USD.	42075.46
principal_supplied	Principal supplied, excluding interest, in token units.	21
principal_supplied_usd	Principal supplied, excluding interest, in USD.	42068.88
accrued_interest	Accrued supply interest in token units.	0.0032861479522399
accrued_interest_usd	Accrued supply interest in USD.	6.58
supply_apy	Supply APY for the asset.	0.014136
current_liquidity_rate	Current liquidity rate for the asset.	0.014037
is_collateral	Whether the asset is used as collateral.	true
liquidation_threshold	Liquidation threshold for the asset.	0.830000
ltv	Maximum loan-to-value ratio for the asset.	0.805000
roi	Return on investment for the supply.	0.000156

Borrows

Field	Description	Example
asset	Symbol of the borrowed asset.	usdt
asset_address	Underlying asset address.	0xdac17f958d2ee523a2206206994597c13d831ec7
borrow_type	Borrow type: stable or variable.	variable
scaled_debt_balance	Scaled debt balance in raw units.	15440253275
borrowed_amount	Borrowed amount in token units.	19006.977599660540473
borrowed_amount_usd	Borrowed amount in USD.	18982.95
principal_borrowed	Principal borrowed, excluding interest, in token units.	19000
principal_borrowed_usd	Principal borrowed, excluding interest, in USD.	18975.99
accrued_interest	Accrued borrow interest in token units.	6.977599660540473
accrued_interest_usd	Accrued borrow interest in USD.	6.97
variable_borrow_rate	Variable borrow rate for the asset.	0.035461
borrow_apy	Borrow APY for the asset.	0.036097

Request example

cURL

curl --compressed \
  -H 'Accept: application/json' \
  -H 'X-Api-Key: <client-api-key>' \
  'https://eu.market-api.kaiko.io/v2/data/lending.v1/addresses/0x1d296f5efbbb235c7a90734c2469fe8dc21e132d/positions?start_time=2026-06-01T00:00:00.000Z&end_time=2026-06-02T00:00:00.000Z&interval=1d'

Python

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

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

# ---- Optional parameters ---- #
start_time = "2026-06-01T00:00:00.000Z"
end_time = "2026-06-02T00:00:00.000Z"
interval = "1d"
page_size = 10
sort = "asc"

# ---- 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,
    user_address: str,
    start_time: str,
    end_time: str,
    interval: str,
    sort: str,
    page_size: int,
):
    headers = {"Accept": "application/json", "X-Api-Key": api_key}

    url = f"https://eu.market-api.kaiko.io/v2/data/lending.v1/addresses/{user_address}/positions"
    params = {
        "start_time": start_time,
        "end_time": end_time,
        "interval": interval,
        "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 data.get("next_url"):
            res = requests.get(data["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,
    user_address=user_address,
    start_time=start_time,
    end_time=end_time,
    interval=interval,
    sort=sort,
    page_size=page_size,
)
print(df)

Response example

{
    "query":
    {
        "user_address": "0x1d296f5efbbb235c7a90734c2469fe8dc21e132d",
        "start_time": "2026-06-01T00:00:00.000Z",
        "end_time": "2026-06-02T00:00:00.000Z",
        "interval": "1d"
    },
    "time": "2026-07-02T14:38:15.282665557Z",
    "timestamp": 1783003095,
    "data":
    [
        {
            "user_address": "0x1d296f5efbbb235c7a90734c2469fe8dc21e132d",
            "blockchain": "ethereum",
            "block_number": "25225970",
            "timestamp": "2026-06-02T00:00:00Z",
            "protocol": "aav3",
            "health_factor": "1.839684",
            "total_collateral_usd": "42075.46",
            "total_supplied_usd": "42075.46",
            "total_debt_usd": "18982.95",
            "available_borrows_usd": "14887.79",
            "net_worth_usd": "23092.51",
            "net_apy": "-0.003917",
            "total_supply_accrued_interest_usd": "6.58",
            "total_borrow_accrued_interest_usd": "6.97",
            "total_principal_supplied_usd": "42068.88",
            "total_principal_borrowed_usd": "18975.99",
            "roi": "-0.000017",
            "supplies":
            [
                {
                    "asset": "weth",
                    "asset_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                    "atoken_address": "0x4d5f47fa6a74757f35c14fd3a6ef8e3c9bc514e8",
                    "scaled_balance": "19697531323085677000",
                    "supplied_amount": "21.0032861479522399",
                    "supplied_amount_usd": "42075.46",
                    "principal_supplied": "21",
                    "principal_supplied_usd": "42068.88",
                    "accrued_interest": "0.0032861479522399",
                    "accrued_interest_usd": "6.58",
                    "supply_apy": "0.014136",
                    "current_liquidity_rate": "0.014037",
                    "is_collateral": "True",
                    "liquidation_threshold": "0.830000",
                    "ltv": "0.805000",
                    "roi": "0.000156"
                }
            ],
            "borrows":
            [
                {
                    "asset": "usdt",
                    "asset_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
                    "borrow_type": "variable",
                    "scaled_debt_balance": "15440253275",
                    "borrowed_amount": "19006.977599660540473",
                    "borrowed_amount_usd": "18982.95",
                    "principal_borrowed": "19000",
                    "principal_borrowed_usd": "18975.99",
                    "accrued_interest": "6.977599660540473",
                    "accrued_interest_usd": "6.97",
                    "variable_borrow_rate": "0.035461",
                    "borrow_apy": "0.036097"
                }
            ]
        },
    ],
    "result": "success",
    "access":
    {
        "access_range":
        {
            "start_timestamp": 1073001600000,
            "end_timestamp": 1861830000000
        },
        "data_range":
        {
            "start_timestamp": "None",
            "end_timestamp": 1861830000000
        }
    }
}