Getting started
ZentraScore API v1
A REST API for on-chain credit scoring. Index wallet behaviour across 18+ DeFi protocols and expose credit scores directly to your lending contracts, risk systems, and user interfaces.
Base URL
https://api.zentrascore.io/v1
Sandbox
https://sandbox.zentrascore.io/v1
Response format
JSON · ISO 8601 timestamps · Native token units
SDKs available
@zentrascore/sdk (JS/TS) · zentrascore-py · go-zentrascore
Quick start
Up in 5 minutes
Install the SDK, paste your API key, and make your first score request — that's it.
Install the SDK
npm install @zentrascore/sdk
Set your API key
ZENTRASCORE_API_KEY=cs_live_xxxx
Make your first request
client.score.get('0x...')
# Install the JavaScript / TypeScript SDK npm install @zentrascore/sdk # Add your key to .env ZENTRASCORE_API_KEY=cs_live_xxxxxxxxxxxx # Make your first call import ZentraScore from '@zentrascore/sdk'; const cs = new ZentraScore({ apiKey: process.env.ZENTRASCORE_API_KEY }); const result = await cs.score.get('0x71C7...'); console.log(result.score); // 734
Authentication
API Keys
All API requests require a Bearer token in the Authorization header. Keys are prefixed with cs_live_ for production and cs_test_ for sandbox.
curl https://api.zentrascore.io/v1/score/0x71C7... -H "Authorization: Bearer cs_live_xxxxxxxxxxxx"
Errors & Limits
Errors & Rate Limits
ZentraScore uses conventional HTTP status codes. Errors include a machine-readable code and a human-readable message.
| Code | Meaning | Common cause |
|---|---|---|
| 200 | Success | Request completed normally |
| 400 | Bad request | Missing or invalid parameter |
| 401 | Unauthorized | Invalid or missing API key |
| 404 | Not found | Wallet has no scoring history |
| 429 | Rate limited | Check X-RateLimit-Reset header |
Rate limits by plan
| Plan | Requests / min | Batch size | Daily queries |
|---|---|---|---|
| Consumer | 10 | — | 100 |
| Protocol API | 300 | 500 | 50,000 |
| Analytics | 60 | 1,000 | 10,000 |
| Enterprise | Custom | Custom | Unlimited |
Scoring
Get score
Retrieve the current credit score and full factor breakdown for a wallet address. Scores are cached for 1 hour; pass fresh=true to force recomputation.
Returns the ZentraScore for a given Ethereum address. If the wallet has no history or fails hard gates (age < 180 days), returns 404.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| address | string | required | Checksummed Ethereum address (EIP-55) |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| fresh | boolean | optional | Force recomputation, costs 5× query credit |
| include_history | boolean | optional | Include 12-month score history in response |
| chains | string[] | optional | Chain IDs to include. Default: 1,42161,8453 |
curl -G https://api.zentrascore.io/v1/score/0x71C7656EC7ab88b098defB751B7401B5f6d8973F -d fresh=false -d include_history=true -H "Authorization: Bearer cs_live_xxxxxxxxxxxx"
Example response
{ "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8973F", "score": 734, "grade": "Good", "valid": true, "factors": { "repaymentHistory": { "score": 84, "weight": 0.35 }, "liquidationRecord": { "score": 90, "weight": 0.20 }, "walletAge": { "score": 55, "weight": 0.15 } }, "loanTerms": { "maxLtvBps": 8000, "interestRateBps": 720 } }
Live sandbox — paste any Ethereum address
Webhooks
Webhooks
Receive real-time POST requests when a wallet's score changes. Payloads are signed with HMAC-SHA256.
On-chain Oracle
Oracle
The on-chain oracle writes scores to the CreditScoreOracle contract on each supported chain. Smart contracts read scores directly — zero API cost, fully trustless.
Analytics
Portfolio risk
Aggregate risk metrics for a portfolio of borrowers. Available on Analytics and Enterprise plans.