> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance History

> Get a wallet's positions today and 30, 60 and 90 days ago

## Overview

Returns the wallet's positions at four dated points: today and 30, 60 and 90 days ago, summed across the covered chains. Each point separates what the wallet holds directly from what it has deposited in lending protocols, how much of that backs a loan, and how much it owes. Use it to see whether a wallet is levering up, deleveraging, or draining assets over the last quarter.

> [!NOTE]
>
> Balances **and** prices are read as of each point's block, so a past point reflects that day's prices, not today's.

**Cost:** 6 Cred Units per request.

## Path Parameters

**address** `string` *required*

Ethereum address or ENS name (e.g., `vitalik.eth` or `0x742d35Cc6634C0532925a3b844Bc454e4438f44e`)

## Response

**address** `string`

The resolved Ethereum address (checksummed)

**timestamp** `string`

ISO 8601 timestamp when the history was computed

**coverage** `string`

`complete` when every chain answered at every point, otherwise `partial`

**not\_covered** `integer[]`

Chains this endpoint cannot read (currently Celo, `42220`). They are not part of any point.

**unavailable\_chains** `integer[]`

Present only when `coverage` is `partial`: chains the data provider could not answer for at one or more points

**balance\_history** `array`

Four points, ordered today first

**balance\_history\[].date** `string`

The point's date (`YYYY-MM-DD`, UTC). Past points are taken at 00:00 UTC of that day; today's point is the current block

**balance\_history\[].days\_ago** `integer`

`0`, `30`, `60` or `90`

**balance\_history\[].asset\_in\_wallet\_usd** `number | null`

USD value of tokens held directly in the wallet, excluding lending receipt tokens and debt tokens

**balance\_history\[].deposit\_usd** `number | null`

USD value of lending-protocol supply positions (Aave aTokens, Compound cTokens). These are the same tokens the summary report's `total_collateral_usd` measures

**balance\_history\[].collateral\_usd** `number | null`

Equal to `deposit_usd` while the wallet has debt at that point, otherwise `0`: the deposits backing a loan

**balance\_history\[].debt\_usd** `number | null`

USD value of outstanding borrowing (Aave V3 Ethereum variable-debt tokens)

**balance\_history\[].coverage** `string`

`complete` or `partial` for this point. When every covered chain is unavailable at a point, its four USD fields are `null`

**balance\_history\[].chains** `array`

One entry per covered chain: `chain_id`, the `block_number` the point was read at (`null` for a chain the wallet had not used yet, which contributes zeros), and the chain's `coverage` at this point

## How the fields relate

| Field | Counts | Does not count |
| - | - | - |
| `asset_in_wallet_usd` | Native coin, ERC-20s, stablecoins, LP and wrapped tokens held directly | Lending receipt tokens, debt tokens, NFTs |
| `deposit_usd` | Lending receipt tokens (supply positions) | Anything held directly |
| `collateral_usd` | `deposit_usd` when `debt_usd > 0` | Deposits with no loan against them |
| `debt_usd` | Debt tokens | Debt on protocols without a debt token (Compound V3) |

`asset_in_wallet_usd + deposit_usd - debt_usd` is the wallet's net position at that point.

## Data Sources

* **Balances**: block-pinned wallet token balances
* **Prices**: block-pinned prices; lending receipt and debt tokens are valued through their underlying asset at the same block, never through their own thin DEX pairs
* **Blocks**: the last block at or before 00:00 UTC on each date, per chain

## Supported Chains

Ethereum, Optimism, BNB Chain, Polygon, Base, Arbitrum, Avalanche, Linea and Robinhood Chain. Celo is listed in `not_covered`.

## Use Cases

* **Leverage trend**: compare `debt_usd / collateral_usd` across the four points
* **Deleveraging check**: a falling `debt_usd` with stable deposits shows voluntary repayment
* **Asset drain**: a falling `asset_in_wallet_usd` ahead of a credit decision
* **Underwriting context**: pair with the credit score to size a facility on a quarter of history, not a snapshot

```bash cURL theme={null}
curl -X GET "https://api.credprotocol.com/api/v2/report/address/vitalik.eth/balance-history" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.credprotocol.com/api/v2/report/address/vitalik.eth/balance-history', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
for (const point of data.balance_history) {
  console.log(`${point.date}: debt $${point.debt_usd} on $${point.collateral_usd} collateral`);
}
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.credprotocol.com/api/v2/report/address/vitalik.eth/balance-history',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

for point in response.json()['balance_history']:
    print(f"{point['date']}: debt ${point['debt_usd']:,.0f} on ${point['collateral_usd']:,.0f} collateral")
```

```json 200 theme={null}
{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "timestamp": "2026-10-23T14:02:11+00:00",
  "coverage": "complete",
  "not_covered": [42220],
  "balance_history": [
    {
      "date": "2026-10-23",
      "days_ago": 0,
      "asset_in_wallet_usd": 18420.55,
      "deposit_usd": 25000.0,
      "collateral_usd": 25000.0,
      "debt_usd": 9000.0,
      "coverage": "complete",
      "chains": [
        {"chain_id": 1, "block_number": 26259290, "coverage": "complete"},
        {"chain_id": 8453, "block_number": 41230112, "coverage": "complete"}
      ]
    },
    {
      "date": "2026-09-23",
      "days_ago": 30,
      "asset_in_wallet_usd": 20110.2,
      "deposit_usd": 25000.0,
      "collateral_usd": 25000.0,
      "debt_usd": 12000.0,
      "coverage": "complete",
      "chains": [
        {"chain_id": 1, "block_number": 26043610, "coverage": "complete"},
        {"chain_id": 8453, "block_number": 39934800, "coverage": "complete"}
      ]
    },
    {
      "date": "2026-08-24",
      "days_ago": 60,
      "asset_in_wallet_usd": 31500.0,
      "deposit_usd": 0.0,
      "collateral_usd": 0.0,
      "debt_usd": 0.0,
      "coverage": "complete",
      "chains": [
        {"chain_id": 1, "block_number": 25828100, "coverage": "complete"},
        {"chain_id": 8453, "block_number": 38638900, "coverage": "complete"}
      ]
    },
    {
      "date": "2026-07-25",
      "days_ago": 90,
      "asset_in_wallet_usd": 29870.4,
      "deposit_usd": 0.0,
      "collateral_usd": 0.0,
      "debt_usd": 0.0,
      "coverage": "complete",
      "chains": [
        {"chain_id": 1, "block_number": 25612700, "coverage": "complete"},
        {"chain_id": 8453, "block_number": 37343000, "coverage": "complete"}
      ]
    }
  ]
}
```

```json 503 theme={null}
{
  "detail": "Balance history is temporarily unavailable from upstream data providers; please retry shortly"
}
```

## Performance

* **Response Time**: 2–10 seconds for a wallet whose past points have not been read before (three past points per active chain); well under a second afterwards
* **Caching**: past points are cached per wallet and day, today's point and the assembled response for 5 minutes
* **Not billed**: a `503` (no provider could answer) consumes no Cred Units

## Related Endpoints

| Endpoint | Returns |
| - | - |
| `/summary` | Current totals, including `total_collateral_usd` and `total_debt_usd` |
| `/total/usd` | Current value by chain |
| `/balance-history` | The same positions at four dates |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.