# Balances and transactions

### Endpoint

{% code overflow="wrap" %}

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

{% endcode %}

### Parameters

<table><thead><tr><th width="220">Parameter</th><th width="211">Description</th><th width="208">Example</th><th data-type="checkbox">Required?</th></tr></thead><tbody><tr><td><code>blockchain</code></td><td>Always <code>ethereum</code>.</td><td><code>ethereum</code></td><td>true</td></tr><tr><td><code>sort</code></td><td>The sorting order for the results.</td><td><code>asc</code> or <code>desc</code></td><td>false</td></tr><tr><td><code>page_size</code></td><td><p>Number of results to return data for. (max: 5000).</p><p>See <a href="https://docs.kaiko.com/kaiko-rest-api/general/getting-started/pagination">Pagination</a></p></td><td><code>100</code></td><td>false</td></tr><tr><td><code>start_time</code></td><td>Starting time in ISO 8601 (inclusive).</td><td><code>2022-05-01T00:00:00.000Z</code></td><td>false</td></tr><tr><td><code>end_time</code></td><td>Ending time in ISO 8601 (inclusive).</td><td><code>2022-05-01T00:00:00.000Z</code></td><td>false</td></tr><tr><td><code>transaction_hash</code></td><td>Filter by transaction hash.</td><td><code>0xf7825247b9a9355c0fb45ec0d008fe638ce5bae9cb877c6a28a91d9ea5f17341</code></td><td>false</td></tr><tr><td><code>user_address</code></td><td>Filter by user address.</td><td><code>0x000000fee13a103a10d593b9ae06b3e05f2e7e1c</code></td><td>false</td></tr><tr><td><code>token_address</code></td><td>Filter by token address. <br><br>For <code>ETH</code>, include the <code>token_address</code> field with an empty value.</td><td><a data-footnote-ref href="#user-content-fn-1"><code>0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2</code></a></td><td>false</td></tr><tr><td><code>token_symbol</code></td><td>Filter by token symbol. </td><td><a data-footnote-ref href="#user-content-fn-2"><code>LINK</code></a></td><td>false</td></tr></tbody></table>

### 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`  | <p>Event type. <br><br><strong>See more information</strong> <a href="#possible-values-for-the-field-transaction_type"><strong>below</strong></a><strong>.</strong></p> | `token_transfer`                                                     |
| `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

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```url
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=ethereum"
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

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

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

# ---- 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)
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response example

```json
{
  "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`:**

<table><thead><tr><th width="397">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>coin_transfer</code></td><td>Native ETH transfer.</td></tr><tr><td><code>tx_value</code></td><td>Native ETH transfer happening in a transaction.</td></tr><tr><td><code>token_transfer</code></td><td>This operation involves the transfer of (ERC20) tokens.</td></tr><tr><td><code>block_rewards</code></td><td>Rewards granted to the miner who mined a block before the Merge.</td></tr><tr><td><code>uncle_rewards</code></td><td>Rewards granted to the miner who mined an uncle block before the Merge.</td></tr><tr><td><code>uncle_inclusion_rewards</code></td><td>Rewards granted to the miner who included an uncle block into a mined block before the Merge.</td></tr><tr><td><code>genesis_balance</code></td><td>Refers to the balance attributed to addresses during the genesis block.</td></tr><tr><td><code>dao_adjust_balance</code></td><td>Refers to any adjustment made to an account’s balance in relation to DAO-related hard-fork or operations.</td></tr><tr><td><code>reward_transaction_fee</code></td><td>Reward earned by the miner for including the transaction in the block.</td></tr><tr><td><code>burnt_transaction_fee</code></td><td>Burnt amount of ETH transaction fees, post EIP-1559.</td></tr><tr><td><code>token_burn</code></td><td>Burn of a ERC20 token.</td></tr><tr><td><code>token_mint</code></td><td>Mint of a ERC20 token.</td></tr><tr><td><code>staking_deposit</code></td><td>Deposit of stake for validators.</td></tr><tr><td><code>staking_withdrawal</code></td><td>Withdrawal of rewards or stake for validators.</td></tr><tr><td><code>wrap_coin</code></td><td>Wrapping ETH into WETH.</td></tr><tr><td><code>unwrap_coin</code></td><td>Unwrapping WETH back to ETH.</td></tr></tbody></table>

[^1]: Find a full list of token addresses using the reference api.\
    \
    Eg `https://reference-data-api.kaiko.io/v1/assets?code=eth`

[^2]: Find a full list of tokens using the reference api.\
    \
    Eg `https://reference-data-api.kaiko.io/v1/assets`