Balances and transactions

Endpoint

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

Parameters

Parameter	Description	Example	Required?
blockchain	Should be one of the currently supported blockchains.	ethereum
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_date	Starting time in ISO 8601 (inclusive).	2022-05-01T00:00:00.000Z
end_date	Ending time in ISO 8601 (inclusive).	2022-05-01T00:00:00.000Z
transaction_hash	The transaction hash to filter on.	0xf7825247b9a9355c0fb45ec0d008fe638ce5bae9cb877c6a28a91d9ea5f17341
user_address	The address to filter on.	0x000000fee13a103a10d593b9ae06b3e05f2e7e1c

Fields

Field	Description	Example
chain	Blockchain name.	ethereum
block_number	The height of the block.	7005997
timestamp	The timestamp of the block.	1546560004
user_address	The address on which the row is focused.	0xc8c939539efb7f5ba903fc99b61656979c46c045
transaction_hash	Transaction hash.	0x5a9e11432e5c7e2fccf598606858619cbd72f1de40db625fc4749ec1b032e144
transaction_type	Event type. See more information below.	gas_buy
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.	0xc8c939539efb7f5ba903fc99b61656979c46c045
receiver_address	The address that receives tokens or coins.	0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c
initiator_address	The address that signed the transaction.	0xc8c939539efb7f5ba903fc99b61656979c46c045
token_symbol	Symbol of the token or coin transfered	ETH
token_address	The address of the token or coin transfered.	0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
direction	Inflow or outflow from the user_address.	out
amount	Amount of asset transfered.	0.16
amount_usd	Amount of asset transferred in usd.	23.863262042004745
balance_after	Wallet balance for the user_address for this asset.	0.4814735188
balance_after_usd	Wallet balance for the user_address for this asset in usd.	71.80955465881561

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"

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/wallet.v1/audit"

# Start of parameter configuration
optional_params = {
    "blockchain": "ethereum",
    "start_time":'2024-01-01T00:00:00.000Z",
    "end_time":'2024-01-02T00:00:00.000Z",
}
# End of parameter configuration

conn = http.client.HTTPSConnection(api_host)
headers = {
    "X-Api-Key": api_key,
    "Accept": "application/json"
}

url_params = []
for param, value in optional_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":
    {
        "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": "ethereum",
            "block_number": 21264197,
            "timestamp": 1732530743000000000,
            "user_address": "0xd2674da94285660c9b2353131bef2d8211369a4b",
            "transaction_hash": "0x4ae1bc32d34a7b66fd23c6527a46cf9bb3158452044eea43762e351aa2fdabca",
            "transaction_type": "coin_transfer",
            "transaction_index": 188,
            "ordinal": 0,
            "sender_address": "0xd2674da94285660c9b2353131bef2d8211369a4b",
            "receiver_address": "0x90cdc2572f170178ac5027af0dcf141870a962e3",
            "initiator_address": "0xd2674da94285660c9b2353131bef2d8211369a4b",
            "token_symbol": "ETH",
            "token_address": "0",
            "direction": "out",
            "amount": 0.00237201,
            "amount_usd": 8.217764039189689,
            "balance_after": 6966.056486974737,
            "balance_after_usd": 24133712.966482032
        },
        /* ... */
    ],
    "continuation_token": "xxx",
    "next_url": "https://us.market-api.kaiko.io/v2/data/wallet.v1/audit?continuation_token=xxx"
    }
}

Possible values for the field transaction_type:

Value	Description
reward_mine_uncle	Uncle block rewards are awarded to miners who generate an uncle block that gets included in a valid block added to the chain. These uncle blocks are analogous to stale blocks in Bitcoin. However, rather than being disregarded, uncle blocks receive rewards dependent on their novelty.
reward_mine_block	Rewards granted to the miner who mines the current block.
dao_refund_contract	This is related to the execution of the DAO hard-fork, an event that occurred as a response to the notorious DAO hack in 2016. This hard-fork moved all the Ether initially stored in The DAO (and its child DAOs) to a refund contract. From this contract, original DAO token holders could claim their proportional share of the funds.
dao_adjust_balance	Refers to any adjustment made to an account’s balance in relation to DAO-related hard-fork or operations.
coin_transfer	A coin transfer operation.
genesis_balance	Refers to the balance attributed to addresses during the genesis block.
gas_buy	The amount of gas purchased by the initiator to execute the transaction.
reward_transaction_fee	Reward earned by the miner for including the transaction in the block.
reward_fee_reset
gas_refund	The process of refunding gas to the initiator when the state store is cleared.
touch_account	Refers to the process of interacting with an account in some way, such as updating its nonce.
suicide_refund	The process of refunding gas to a contract owner when the SELFDESTRUCT operation is called, as it clears the store.
suicide_withdraw	This action allows the withdrawal of the remaining coin (ex: ETH) in a self-destructed account to a specific address.
call_balance_override	This operation overrides the default balance of an account.
burn	Burning coins in chains where this process occurs.
withdrawal	Allows the withdrawal of rewards or stake for validators.
token_transfer	This operation involves the transfer of (ERC20) tokens.
wrap_coin	This operation mints WETH tokens after a coin (ex: ETH) deposit.
unwrap_coin	This operation burns WETH tokens before a coin (ex: ETH) withdrawal.
token_deposit	This operation allows the deposit of (ERC20) tokens into staking contracts or escrow.
token_withdrawal	This operation allows the withdrawal of (ERC20) tokens from the staking contracts or escrow.
unknown	Unknown balance_change reason, only happens for the chain’s coin.