Balances

What is this endpoint for?

This endpoint offers in-depth insights into Bitcoin wallets including transfers and wallet balances over time.

Endpoint

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

Parameters

Parameter	Required	Description	Example
blockchain	No	Always bitcoin.	bitcoin
sort	No	The sorting order for the results.	asc or desc
page_size	No	Number of results to return data for. (max: 5000). See Pagination	100
start_date	No	Starting time in ISO 8601 (inclusive).	2022-05-01T00:00:00.000Z
end_date	No	Ending time in ISO 8601 (inclusive).	2022-05-01T00:00:00.000Z
transaction_hash	No	The transaction hash to filter on.	5ae688ab08139338e3024e150339ffa94c9d2ba23f38d0838025a41dc2fac3e6
user_address	No	The address to filter on.	bc1qm8ktha9m745u2gh54kprk72eu9t6n5xa2adckn

Fields

Field	Description	Example
blockchain	Blockchain name.	bitcoin
block_number	The height of the block.	871899
timestamp	The timestamp of the block.	1732536300000000000
address	The address on which the row is focused.	bc1qhyar38j6catjs8y30naptzrs8jhgudhzcv8s98
transaction_hash	Transaction hash.	e84b146c3f26545b525772a38425513f36a1738bfbb49a474aefe14a8c6d7903
transaction_id	Transaction ID.	334480d40ca84435bf440da99e9454cca25d06163996cd9a6ba4b517b9da1608
transaction_type	Transaction type. See information below.	witness_v0_keyhash
transaction_index	The index of the transaction.	4695
internal_transaction_index		1
token_symbol	Symbol of the token or coin transfered	BTC
direction	Inflow or outflow from the user_address.	out
amount	Amount of asset transfered.	0.0022931
amount_usd	Amount of asset transferred in usd.	225.6601111753002
balance_after	Wallet balance for the user_address for this asset.	0
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"

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": "bitcoin",
    "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": 1732536300000,
    "access":
    {
        "access_range":
        {
            "start_timestamp": 1073001600000,
            "end_timestamp": "None"
        },
        "data_range":
        {
            "start_timestamp": "None",
            "end_timestamp": "None"
        }
    },
    "data":
    [
        {
            "blockchain": "bitcoin",
            "block_number": 871899,
            "timestamp": 1732536300000000000,
            "address": "bc1qt42fgv262u3d2qvpmwecpxdwfmxpjug6mxn532",
            "transaction_hash": "e84b146c3f26545b525772a38425513f36a1738bfbb49a474aefe14a8c6d7903",
            "transaction_id": "334480d40ca84435bf440da99e9454cca25d06163996cd9a6ba4b517b9da1608",
            "transaction_type": "witness_v0_keyhash",
            "transaction_index": 4695,
            "internal_transaction_index": 0,
            "token_symbol": "BTC",
            "direction": "in",
            "amount": 0.00228863,
            "amount_usd": 225.22022599935772,
            "balance_after": 1.06076911,
            "balance_after_usd": 104388.50259209116
        },
        /* ... */
    ],
    "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
minerReward
multisig
pubkey
pubkeyhash
scripthash
witness_unknown
witness_v0_keyhash
witness_v0_scripthash
witness_v1_taproot
nulldata
nonstandard