> ## 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.

# Score History

> Get the recorded credit score history of an Ethereum address

## Overview

Returns the scores recorded for an address over a window, newest first, so you can see how a wallet's creditworthiness has moved rather than only where it stands today.

A score is recorded every time it is computed:

* by any API request that scores the address (`GET /score/address/{address}`, the batch and aggregate endpoints, the report endpoints that compute a score);
* by the cache warmer, for frequently requested addresses;
* by a refresh after on-chain activity on an address watched by a [`score_change` webhook](https://docs.credprotocol.com/guides/webhooks#score-events).

An unchanged score is re-recorded at most once an hour; every change is recorded. Provisional scores (computed before all of the address's lending history had been read) are not recorded.

> [!NOTE]
>
> An address that has never been scored has an empty history. Request its score once, or watch it with a `score_change` webhook to keep its history current without polling.

## Authentication

| Method | Header | Cost |
| - | - | - |
| API Token | `Authorization: Bearer YOUR_API_KEY` | 1 Cred Unit |
| x402 Payment | `X-PAYMENT: <signed_payment>` | \$0.01 USDC |

## Path Parameters

**address** `string` *required*

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

## Query Parameters

**days** `integer` (default: 90)

Window length, in days before now. Maximum 365.

**limit** `integer` (default: 100)

Maximum number of points to return. Maximum 1000.

## Response

**address** `string`

The resolved Ethereum address

**days** `integer`

The window length that was applied

**count** `integer`

Number of points returned

**points** `array`

Recorded scores in the window, newest first. Each point has `timestamp` (ISO 8601), `score` (300-1000), `decile` (1-10), `range` (`low`, `fair`, `good`, `very_good`, `excellent`) and `model_version`.

```bash cURL theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.credprotocol.com/api/v2/score/address/vitalik.eth/history?days=180"
```

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

response = httpx.get(
    "https://api.credprotocol.com/api/v2/score/address/vitalik.eth/history",
    params={"days": 180},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
history = response.json()
```

```json 200 theme={null}
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "days": 180,
  "count": 2,
  "points": [
    {
      "timestamp": "2026-10-30T09:12:44+00:00",
      "score": 741,
      "decile": 8,
      "range": "good",
      "model_version": "andromeda_1.4"
    },
    {
      "timestamp": "2026-10-02T17:40:03+00:00",
      "score": 726,
      "decile": 8,
      "range": "good",
      "model_version": "andromeda_1.4"
    }
  ]
}
```


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