API Reference - ZKScore Documentation

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

Get your API key from the Developer Portal.

Never expose your API key in client-side code. Always make API calls from your backend server.

Request Format

All requests should include the following headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Response Format

All API responses follow this structure:

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

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1698765432

Pagination

List endpoints support pagination using limit and offset parameters:

GET /api/v1/achievements?limit=50&offset=100

Paginated responses include metadata:

{
  "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.created
identity.activated
score.updated
achievement.earned
attestation.created
attestation.revoked

SDKs

We provide official SDKs for easy integration:

JavaScript/TypeScript

npm install @zkscore/sdk

React

npm install @zkscore/sdk-react

API Endpoints

Identity Management

Get Identity - Retrieve identity information
Mint Identity - Create a new identity
Activate Identity - Activate an identity
Check Availability - Check name availability

Trust Scores

Get Score - Get user’s trust score
Get Breakdown - Detailed score breakdown
Get History - Historical score data
Get Leaderboard - Global leaderboard

Achievements

List Achievements - All available achievements
Get User Achievements - User’s achievements
Claim Achievement - Claim an achievement
Get Progress - Achievement progress

Trading

Get Trading Stats - User’s trading statistics
Get Trading History - Trade history
Get Trading Leaderboard - Trading leaderboard

Trust Layer

Get Attestations - User’s attestations
Create Attestation - Create attestation
Revoke Attestation - Revoke attestation
Get Modules - Available modules
Evaluate Policy - Evaluate trust policy

Developer Tools

Create API Key - Generate new API key
List API Keys - List your API keys
Revoke API Key - Revoke an API key
Get Usage - API usage statistics

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:

Email: support@onzks.com
Discord: Join our community
GitHub: Report issues

Quick Start

New to ZKScore? Start with our Quick Start guide

​Base URL

​Authentication

​Request Format

​Response Format

​Error Responses

​Rate Limits

​Pagination

​Filtering & Sorting

​Webhooks

​SDKs

JavaScript/TypeScript

React

​API Endpoints

​Identity Management

​Trust Scores

​Achievements

​Trading

​Trust Layer

​Developer Tools

​Status Codes

​Support

Quick Start

Base URL

Authentication

Request Format

Response Format

Error Responses

Rate Limits

Pagination

Filtering & Sorting

Webhooks

SDKs

API Endpoints

Identity Management

Trust Scores

Achievements

Trading

Trust Layer

Developer Tools

Status Codes

Support