Balances

What is this endpoint for?

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

Wallet Data can also be accessed through Google BigQuery. To get started, read our guide.

Endpoint

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

Parameters

Parameter	Required	Description	Example
blockchain	No	Should be one of the currently supported blockchains.	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