Balances and transactions

Endpoint

https://us.market-api.kaiko.io/v2/data/wallet.v1/audit

Parameters

Parameter	Description	Example	Required?
blockchain	Always provenance.	provenance
sort	The sorting order for the results.	asc or desc
page_size	Number of results to return data for. (max: 5000). See Pagination	100
start_time	Starting time in ISO 8601 (inclusive).	2022-05-01T00:00:00.000Z
end_time	Ending time in ISO 8601 (inclusive).	2022-05-01T00:00:00.000Z
transaction_hash	The transaction hash to filter on.	10CC4474038E6F902174708DA275AECA36C5B507616FD17810BD36591F00B8FA
user_address	The address to filter on.	0x000000fee13a103a10d593b9ae06b3e05f2e7e1c
token_address	The token address to filter on.	nhash

Fields

Field	Description	Example
chain	Blockchain name.	provenance
block_number	The height of the block.	22820298
timestamp	The timestamp of the block. (ns)	1742804594956710217
user_address	The address on which the row is focused.	pb1zsherr3eat6gvq9ptg3m0n3dj33xf2mwevk3ca
transaction_hash	Transaction hash.	D1CEE1A5B92FAE712B10627D72B2F185153A3249BC54B0B10589EE1D016CB0AF
event_type	Event type. See more information below.	transaction_fee
transaction_index	The index of the transaction.	0
ordinal	Generated number that gives the order of each balance impact, for one file. Based on call index and log indexes.	2
sender_address	The address that sends tokens or coins.	pb1zsherr3eat6gvq9ptg3m0n3dj33xf2mwevk3ca
receiver_address	The address that receives tokens or coins.	pb17xpfvakm2amg962yls6f84z3kell8c5lehg9xp
token_symbol	Symbol of the token or coin transfered	HASH
token_address	The address of the token or coin transfered.	nhash
direction	Inflow or outflow from the user_address.	out
raw_amount	Amount of asset transfered. Without decimals.	2178337020
amount	Amount of asset transfered.	2.178337020
amount_usd	Amount of asset transferred in usd.	0
raw_balance_after	Raw wallet balance for the user_address for this asset. Without decimals.	1928056609014953
balance_after	Wallet balance for the user_address for this asset.	1928056.609014953
balance_after_usd	Wallet balance for the user_address for this asset in usd.	0

Request example

cURL

curl --compressed -H "Accept: application/json" -H "X-Api-Key: <client-api-key>" \
  "https://eu.market-api.kaiko.io/v2/data/wallet.v1/audit?blockchain=provenance"

Python

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

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

# ---- Optional parameters ---- #
start_time = "2025-03-05T00:00:00Z"
end_time = "2025-03-05T00:02:00Z"
page_size = 100
sort = "desc"
transaction_hash = None
user_address = None
token_address = None

# ---- 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, start_time: str, end_time: str, page_size: int, sort: str, transaction_hash: str, user_address: str, token_address: str):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/wallet.v1/audit'
    params = {
        "blockchain": blockchain,
        "start_time": start_time,
        "end_time": end_time,
        "page_size": page_size,
        "sort": sort,
        "transaction_hash": transaction_hash,
        "user_address": user_address,
        "token_address": token_address
    }

    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, start_time=start_time, end_time=end_time, page_size=page_size, sort=sort, transaction_hash=transaction_hash, user_address=user_address, token_address=token_address)
print (df)

Response example

{
  "query":
    {
        "live": "False",
        "start_time": "2024-01-01T00:00:00.000Z",
        "end_time": "2024-01-02T00:00:00.000Z",
        "start_block": 0,
        "end_block": 0,
        "page_size": 100,
        "sort": "0",
        "data_version": "v1",
        "commodity": "wallet_data",
        "request_time": "2024-01-01T00:00:00.000Z"
    },
    "time": "2024-01-01T00:00:00.000Z",
    "timestamp": 1732530743000,
    "access":
    {
        "access_range":
        {
            "start_timestamp": 1073001600000,
            "end_timestamp": "None"
        },
        "data_range":
        {
            "start_timestamp": "None",
            "end_timestamp": "None"
        }
    },
    "data":
    [
    	{
            "chain": "provenance",
            "block_number": 22805233,
            "timestamp": 1742738984211330688,
            "user_address": "pb17xpfvakm2amg962yls6f84z3kell8c5lehg9xp",
            "transaction_hash": "67DA09E9450ECE844392FA8C6F9DC90AEA1A3727D9D7681744BFEFD56CF0A6E2",
            "transaction_index": 2,
            "event_type": "transaction_fee",
            "event_index": 59,
            "sender_address": "pb1xvd4k9jg5h0d4dhzr4z0txtwe9p5zxf58xcmxd",
            "receiver_address": "pb17xpfvakm2amg962yls6f84z3kell8c5lehg9xp",
            "token_symbol": "HASH",
            "token_address": "nhash",
            "direction": "in",
            "raw_amount": "8048464980",
            "amount": 8.04846498,
            "amount_usd": 0,
            "raw_balance_after": "200558873034833202",
            "balance_after": 200558873.03489527,
            "balance_after_usd": 0
        },
        /* ... */
    ],
    "continuation_token": "xxx",
    "next_url": "https://us.market-api.kaiko.io/v2/data/wallet.v1/audit?continuation_token=xxx"
    }
}

Possible values for the field event_type:

Value	Description
transfer	This operation involves the transfer of native coin or tokens.
transaction_fee	The amount of transaction fee paid to execute the transaction.
token_mint	Minting new tokens.
token_burn	Burning tokens.
token_withdraw	Removing assets from the Marker account. That includes the movement of newly-minted tokens to other accounts.
withdraw_rewards	Coming soon.