Skip to main content
GET
https://api-mainnet.onzks.com
/
v1
/
score
/
:identity
Get Score
curl --request GET \
  --url https://api-mainnet.onzks.com/v1/score/:identity \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "zksId": {},
  "address": "<string>",
  "score": {
    "total": 123,
    "rank": 123,
    "tier": "<string>",
    "percentile": 123,
    "breakdown": {},
    "lastUpdated": "<string>"
  }
}

Overview

Retrieve the complete ZKScore for a user, including total score, rank, tier, and breakdown by category.

Parameters

identity
string
required
ZKS ID (e.g., alice.zks) or wallet address (e.g., 0x742d35Cc...)
chainId
number
Specific chain ID to get score for (optional, defaults to aggregated score)
ZKS ID Support: When using a ZKS ID, the API returns aggregated scores across all linked wallets for that identity.

Response

success
boolean
Indicates if the request was successful
zksId
string | null
The ZKS ID (without .zks suffix), or null if not set
address
string
The primary wallet address
score
object

Examples

curl https://api.onzks.com/v1/score/alice.zks \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "zksId": "alice",
  "address": "0x742d35cc6635c0532925a3b844d1ff4e1321",
  "score": {
    "total": 9847,
    "rank": 1,
    "tier": "legendary",
    "percentile": 99.9,
    "breakdown": {
      "activity": 1200,
      "volume": 1800,
      "age": 950,
      "diversity": 1400,
      "governance": 1100,
      "social": 897,
      "risk": 750,
      "loyalty": 1750
    },
    "lastUpdated": "2024-01-20T14:30:00Z"
  }
}

Score Tiers

TierScore RangeDescription
Bronze0-299New users
Silver300-499Active users
Gold500-699Experienced users
Platinum700-899Power users
Diamond900-1199Elite users
Legendary1200+Top users