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

# API Overview

> Overview of the Cred Protocol API

## Base URL

All API requests should be made to:

```
https://api.credprotocol.com
```

## Authentication

All API endpoints require authentication using a Bearer token. Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Info>
  Get your API key from the [Dashboard](https://app.credprotocol.com/dashboard).
</Info>

## API Endpoints

The Cred Protocol API is organized into the following categories:

### Score Endpoints

| Endpoint                          | Method | Description                                  |
| --------------------------------- | ------ | -------------------------------------------- |
| `/api/v2/score/address/{address}` | GET    | Get credit score for a single address        |
| `/api/v2/score/`                  | GET    | Get aggregated score for multiple addresses  |
| `/api/v2/score/batch/`            | GET    | Get individual scores for multiple addresses |
| `/api/v2/score/address/{address}` | POST   | Get enhanced score with off-chain data       |

### Report Endpoints

| Endpoint                                               | Method | Description                                  |
| ------------------------------------------------------ | ------ | -------------------------------------------- |
| `/api/v2/report/address/{address}`                     | GET    | Get comprehensive credit report              |
| `/api/v2/report/address/{address}`                     | POST   | Get enhanced report with off-chain data      |
| `/api/v2/report/`                                      | GET    | Get aggregated report for multiple addresses |
| `/api/v2/report/address/{address}/summary`             | GET    | Get lightweight summary report               |
| `/api/v2/report/address/{address}/chain/{chain_id}`    | GET    | Get chain-specific report                    |
| `/api/v2/report/address/{address}/total/usd`           | GET    | Get portfolio composition by chain           |
| `/api/v2/report/address/{address}/total/usd/aggregate` | GET    | Get total portfolio value                    |

### Identity Endpoints

| Endpoint                                          | Method | Description               |
| ------------------------------------------------- | ------ | ------------------------- |
| `/api/v2/identity/address/{address}/attestations` | GET    | Get identity attestations |

### Sandbox Endpoints

All production endpoints have sandbox equivalents. See [Sandbox Overview](/api-reference/sandbox/overview) for the full list.

| Endpoint                                   | Method | Description            |
| ------------------------------------------ | ------ | ---------------------- |
| `/api/v2/sandbox/score/address/{address}`  | GET    | Get mock credit score  |
| `/api/v2/sandbox/report/address/{address}` | GET    | Get mock credit report |

## Request Format

### Path Parameters

Some endpoints accept path parameters (e.g., `{address}`). These support:

* **Ethereum addresses**: `0x742d35Cc6634C0532925a3b844Bc9e7595f0Ab17`
* **ENS names**: `vitalik.eth`

### Query Parameters

Query parameters should be URL-encoded and appended to the URL:

```bash theme={null}
GET /api/v2/score/batch?addresses=0x123...,0x456...
```

## Response Format

All responses are returned in JSON format:

```json theme={null}
{
  "address": "0x...",
  "score": 847,
  "decile": 7,
  "range": "very_good",
  "model_version": "andromeda_1.0",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### Common Response Fields

| Field           | Type    | Description                                          |
| --------------- | ------- | ---------------------------------------------------- |
| `address`       | string  | The resolved Ethereum address                        |
| `score`         | integer | Credit score between 300-1000                        |
| `decile`        | integer | Score decile (1-10)                                  |
| `range`         | string  | Score range (low, fair, good, very\_good, excellent) |
| `model_version` | string  | Scoring model version                                |
| `timestamp`     | string  | ISO 8601 timestamp of the response                   |

## Usage Limits

API usage is measured in Cred Units (CUs). Each endpoint consumes a specific number of CUs based on computational complexity.

| Plan       | Cred Units/Month | Price    |
| ---------- | ---------------- | -------- |
| Free       | 1,000            | \$0      |
| Pro        | 50,000           | \$249/mo |
| Enterprise | Unlimited        | Custom   |

<Info>
  See the [Pricing FAQ](https://credprotocol.com/pricing#what-are-cred-units) for details on Cred Units.
</Info>

When you exceed your monthly limit, you'll receive a `429 Too Many Requests` response. Upgrade your plan or wait for the next billing cycle to continue making requests.

## Cred Unit Costs

Every API request consumes Cred Units based on the complexity of the operation. Simple queries cost less, while comprehensive reports that aggregate data across multiple blockchains cost more.

### Cost Tiers

| Operation Type            | Cost Range | Examples                                                       |
| ------------------------- | ---------- | -------------------------------------------------------------- |
| **Basic Queries**         | 1-2 CU     | Credit scores, single-chain summaries, asset values            |
| **Standard Reports**      | 3-5 CU     | Single-chain reports, cross-chain summaries, boosted scores    |
| **Comprehensive Reports** | 7-10 CU    | Full cross-chain reports, enhanced reports with off-chain data |

### What Affects Cost?

* **Scope**: Single-chain queries cost less than cross-chain aggregations
* **Detail Level**: Summaries cost less than full reports with balances, NFTs, and transaction history
* **Data Enrichment**: Reports enhanced with off-chain data require additional processing

### Example Usage

| Use Case                            | Typical Cost |
| ----------------------------------- | ------------ |
| Check a wallet's credit score       | 1 CU         |
| Get a quick portfolio summary       | 3-5 CU       |
| Full credit report for underwriting | 7-10 CU      |

<Tip>
  Use the [Sandbox environment](/api-reference/sandbox/overview) for unlimited free testing during development.
</Tip>

## Caching

Responses are cached for **5 minutes** per address to optimize performance.

To force a fresh calculation, wait for the cache to expire or contact support for cache invalidation.

## Error Handling

See the [Error Handling Guide](/guides/error-handling) for detailed information on handling API errors.

### Common Error Codes

| Code | Description                               |
| ---- | ----------------------------------------- |
| 400  | Bad Request - Invalid parameters          |
| 401  | Unauthorized - Invalid or missing API key |
| 404  | Not Found - Address not found or invalid  |
| 429  | Too Many Requests - Rate limit exceeded   |
| 500  | Internal Server Error                     |

## SDKs & Libraries

Coming soon:

* JavaScript/TypeScript SDK
* Python SDK
* Go SDK

In the meantime, you can use any HTTP client to interact with the API.