Borrows, repayments, liquidations, and withdrawals

What is this endpoint for?

This endpoint returns transactions (borrows, repayments, withdrawals, deposits and liquidations) registered on-chain, for the main L&B protocols.

Endpoint

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

Parameters

Parameter	Required	Description	Example
blockchain	No	Should be one or several of the currently supported blockchains. See Blockchain codes	ethereum
protocol	No	Should be one or several of the currently supported L&B protocols.	aav1,aav2
user_address	No	Filter on a specific wallet addresses (comma separated).	0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
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**
asset	No	L&B events including the requested token. Default: all available tokens.	weth or weth,usdt,usdc
type	No	Event type: borrow, deposit, withdraw, repayment or liquidation.	borrow,withdraw
block_number	No	Block height.	10795593
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 or descending order. Default: desc.	ascending
page_size	No	Number of snapshots to return data for. (default: 100, min: 1, max: 1000). See Pagination	1000

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.	16025918
datetime	The timestamp of the block in which the transaction happened.	1669124591
transaction_hash	Transaction hash	---
log_index	Log index of the transaction	152
protocol	Code of the L&B protocol.	aave/v2
type	Event type: Borrow, deposit, withdraw, repayment or liquidation.	borrow, deposit, etc
user_address	Address of the user.	0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
asset_symbol	Symbol of the underlying asset.	crv
asset_address	Address of the underlying asset.	0xd533a949740bb3306d119cc777fa900ba034cd52
asset_decimals	Decimals of the underlying asset.	18
receipt_symbol	Symbol of the receipt asset.	acrv
receipt_address	Address of the receipt asset.	0x8dae6cb04688c62d939ed9b68d32bc62e49970b1
receipt_decimals	Decimals of the receipt asset.	18
amount	Amounts of the borrowed token.	299894.78
metadata	Metadata linked to the event type and protocol.	More information below.

Metadata information

Borrow event:

Field	Description	Example
amount_receipt	Amounts of the receipt token.	299899
rate	Borrow rate (at the event level or at the contract level depending on the protocol).	0.02820253961814756
rate_type	Stable (1) or Variable (2)	1 or 2
on_behalf_of	The address of user who will incur the debt.	0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Deposit event:

Field	Description	Example
amount_receipt	Amounts of the receipt token.	299899
rate	Supply rate of the overall lending pool.	0.000203088325657998768898798
on_behalf_of	The address that will receive the receipt tokens.	0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Withdraw event:

Field	Description	Example
amount_receipt	Amounts of the receipt token.	299899
on_behalf_of	The address that will receive the underlying token.	0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31

Repayment event

Field	Description	Example
amount_receipt	Amounts of the receipt token.	299899
on_behalf_of	The address of user who will incur the debt.	0xeffc18fc3b7eb8e676dac549e0c693ad50d1ce31
borrow_rate_mode	Stable (1) or Variable (2)	1 or 2

Liquidation event

Field	Description	Example
liquidation_debt_asset_symbol	Symbol of the debt asset.	renfil
liquidation_debt_asset_address	Address of the debt asset.	0xd5147bc8e386d91cc5dbe72099dac6c9b99276f5
liquidation_debt_asset_decimals	Decimals of the debt asset.	18
liquidation_debt_amount_in_asset	Amount of the debt asset.	1899
liquidation_caller_address	The address that triggered the liquidation transaction.	0xdfd3bd446f1b7fd96dc995126ee845af0b1254cd
receive_receipt_token	The liquidator chooses to receive the collateral's asset (False) or recept token (True).	True or False
liquidation_type	Debt (1) or Collateral (2)	1

Request examples

cURL

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: KAIKO_API_KEY' \
  'https://us.market-api.kaiko.io/v2/data/lending.v1/events?blockchain=ethereum&start_time=2024-09-27T13:13:53.441Z&end_time=2024-09-29T13:13:53.441Z'

Python

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

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
blockchain = "ethereum" 
protocol = "aav2"

# ---- Optional parameters ---- #
user_address = None
live = "false"
tx_hash = None
asset = "weth"
type = "borrow"
block_number = None
start_block = None
end_block = None
start_time = "2025-03-01T13:00:00Z"
end_time = None
sort = "desc"
page_size = 1000

# ---- 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, user_address: str, live: str, tx_hash: str, asset: str, type: str, block_number: int, start_block: int, end_block: int, start_time: str, end_time: 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/events'
    params = {
        "blockchain": blockchain,
        "protocol": protocol,
        "user_address": user_address,
        "live": live,
        "tx_hash": tx_hash,
        "asset": asset,
        "type": type,
        "block_number": block_number,
        "start_block": start_block,
        "end_block": end_block,
        "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, blockchain=blockchain, protocol=protocol, user_address=user_address, live=live, tx_hash=tx_hash, asset=asset, type=type, block_number=block_number, start_block=start_block, end_block=end_block, start_time=start_time, end_time=end_time, sort=sort, page_size=page_size)
print (df)

Response example

{
  "query": {
        "blockchain": "*",
        "block_number": "*",
        "asset": "*",
        "user_address": "*",
        "tx_hash": "*",
        "type": "*",
        "start_time": "*",
        "end_time": "*",
        "protocol": "*",
        "sort": "descending",
        "page_size": "1000",
        "start_block": "*",
        "end_block": "*"
    },
    "time": "2022-05-17T14:26:27.274Z",
    "timestamp": 1652797587,
    "data":
    [
        {
            "blockchain": "ethereum",
            "block_number": 16025918,
            "datetime": 1669124591,
            "transaction_hash":"0xa49cfa9c026e728614ca0bdf7272eaaad5b3dd8881fd263ea19ef7d648d9c941",
            "exchange_code": "aave/v2",
            "type": "repayment",
            "user_address": "0x4f381fb46dfde2bc9dcae2d881705749b1ed6e1a",
            "asset_symbol": "crv",
            "asset_address": "0xd533a949740bb3306d119cc777fa900ba034cd52",
            "asset_decimals": 18,
            "receipt_symbol": "acrv",
            "receipt_address": "0x8dae6cb04688c62d939ed9b68d32bc62e49970b1",
            "receipt_decimals": 18,
            "amount": 299894.78,
            "metadata": {
                "borrowRateMode": 2,
                "amountInReceiptAsset": "299894.77",
                "onBehalfOf": "0x4f381fb46dfde2bc9dcae2d881705749b1ed6e1a"
            }
        }
        /* ... */
    ],
    "continuation_token": "xxx",
    "next_url": "https://eu.market-api.kaiko.io/v2/data/lending.v1/events?continuation_token=xxx"
}