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:

Authorization: Bearer YOUR_API_KEY

Get your API key from the Dashboard.

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 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:

GET /api/v2/score/batch?addresses=0x123...,0x456...

Response Format

All responses are returned in JSON format:

{
  "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

See the Pricing FAQ for details on Cred Units.

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

Use the Sandbox environment for unlimited free testing during development.

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