Base URL
All API requests should be made to:
https://api-mainnet.onzks.com
Authentication
ZKScore API uses Bearer token authentication. Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Never expose your API key in client-side code. Always make API calls from your backend server.
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"success": true,
"data": {
// Response data here
},
"timestamp": "2025-10-22T10:30:00Z"
}
Error Responses
Error responses include an error code and message:
{
"success": false,
"error": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again later.",
"timestamp": "2025-10-22T10:30:00Z"
}
Rate Limits
API rate limits depend on your subscription tier:
| Tier | Requests per Minute | Requests per Day |
|---|
| Free | 60 | 10,000 |
| Starter | 300 | 100,000 |
| Professional | 1,000 | 1,000,000 |
| Enterprise | Custom | Custom |
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1698765432
limit and offset parameters:
GET /api/v1/achievements?limit=50&offset=100
{
"success": true,
"data": [...],
"pagination": {
"total": 250,
"limit": 50,
"offset": 100,
"hasMore": true
}
}
Filtering & Sorting
Many endpoints support filtering and sorting:
# Filter by category
GET /api/v1/achievements?category=wallet_age
# Sort by score
GET /api/v1/scores/leaderboard?sort=totalScore&order=desc
# Multiple filters
GET /api/v1/attestations?status=active&chainId=998899
Webhooks
Subscribe to real-time events using webhooks. See the Webhooks Guide for setup instructions.
Available events:
identity.createdidentity.activatedscore.updatedachievement.earnedattestation.createdattestation.revoked
SDKs
We provide official SDKs for easy integration:
API Endpoints
Identity Management
Trust Scores
Achievements
Trading
Trust Layer
Status Codes
| Code | Description |
|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Rate Limit Exceeded |
| 500 | Internal Server Error |
| 503 | Service Unavailable |
Support
Need help? Contact us:
Quick Start
New to ZKScore? Start with our Quick Start guide
