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