Get Score - ZKScore Documentation

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

GET

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

Show properties

total

number

Total ZKScore (0-10000)

rank

number

Global rank position

tier

string

Score tier: bronze, silver, gold, platinum, diamond, legendary

percentile

number

Percentile ranking (0-100)

breakdown

object

Score breakdown by category (activity, volume, age, diversity, governance, social, risk, loyalty)

lastUpdated

string

ISO 8601 timestamp of last score update

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

Tier	Score Range	Description
Bronze	0-299	New users
Silver	300-499	Active users
Gold	500-699	Experienced users
Platinum	700-899	Power users
Diamond	900-1199	Elite users
Legendary	1200+	Top users

Get Score Breakdown - Detailed score breakdown
Get Score History - Historical score data
Get Leaderboard - Top scores

Get Identity Get Score Breakdown

​Overview

​Parameters

​Response

​Examples

​Response Example

​Score Tiers

​Related Endpoints

Overview

Parameters

Response

Examples

Response Example

Score Tiers

Related Endpoints