curl -X GET "https://api.credprotocol.com/api/v2/report/address/vitalik.eth/balance-history" \
-H "Authorization: Bearer YOUR_API_KEY"
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`);
}
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")
{
"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"}
]
}
]
}
{
"detail": "Balance history is temporarily unavailable from upstream data providers; please retry shortly"
}
Report
Balance History
Get a wallet’s positions today and 30, 60 and 90 days ago
GET
/
api
/
v2
/
report
/
address
/
{address}
/
balance-history
curl -X GET "https://api.credprotocol.com/api/v2/report/address/vitalik.eth/balance-history" \
-H "Authorization: Bearer YOUR_API_KEY"
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`);
}
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")
{
"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"}
]
}
]
}
{
"detail": "Balance history is temporarily unavailable from upstream data providers; please retry shortly"
}
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.Balances and prices are read as of each point’s block, so a past point reflects that day’s prices, not today’s.
Path Parameters
string
required
Ethereum address or ENS name (e.g.,
vitalik.eth or 0x742d35Cc6634C0532925a3b844Bc454e4438f44e)Response
string
The resolved Ethereum address (checksummed)
string
ISO 8601 timestamp when the history was computed
string
complete when every chain answered at every point, otherwise partialinteger[]
Chains this endpoint cannot read (currently Celo,
42220). They are not part of any point.integer[]
Present only when
coverage is partial: chains the data provider could not answer for at one or more pointsarray
Four points, ordered today first
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 blockinteger
0, 30, 60 or 90number | null
USD value of tokens held directly in the wallet, excluding lending receipt tokens and debt tokens
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 measuresnumber | null
Equal to
deposit_usd while the wallet has debt at that point, otherwise 0: the deposits backing a loannumber | null
USD value of outstanding borrowing (Aave V3 Ethereum variable-debt tokens)
string
complete or partial for this point. When every covered chain is unavailable at a point, its four USD fields are nullarray
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 pointHow 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 innot_covered.
Use Cases
- Leverage trend: compare
debt_usd / collateral_usdacross the four points - Deleveraging check: a falling
debt_usdwith stable deposits shows voluntary repayment - Asset drain: a falling
asset_in_wallet_usdahead of a credit decision - Underwriting context: pair with the credit score to size a facility on a quarter of history, not a snapshot
curl -X GET "https://api.credprotocol.com/api/v2/report/address/vitalik.eth/balance-history" \
-H "Authorization: Bearer YOUR_API_KEY"
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`);
}
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")
{
"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"}
]
}
]
}
{
"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 |