Get Score
curl --request GET \
--url https://api-mainnet.onzks.com/v1/score/:identity \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-mainnet.onzks.com/v1/score/:identity"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-mainnet.onzks.com/v1/score/:identity', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-mainnet.onzks.com/v1/score/:identity",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-mainnet.onzks.com/v1/score/:identity"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-mainnet.onzks.com/v1/score/:identity")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-mainnet.onzks.com/v1/score/:identity")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"zksId": {},
"address": "<string>",
"score": {
"total": 123,
"rank": 123,
"tier": "<string>",
"percentile": 123,
"breakdown": {},
"lastUpdated": "<string>"
}
}Scores
Get Score
Get the ZKScore for a user by ZKS ID or wallet address
GET
/
v1
/
score
/
:identity
Get Score
curl --request GET \
--url https://api-mainnet.onzks.com/v1/score/:identity \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-mainnet.onzks.com/v1/score/:identity"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-mainnet.onzks.com/v1/score/:identity', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-mainnet.onzks.com/v1/score/:identity",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-mainnet.onzks.com/v1/score/:identity"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-mainnet.onzks.com/v1/score/:identity")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-mainnet.onzks.com/v1/score/:identity")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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
string
required
ZKS ID (e.g.,
alice.zks) or wallet address (e.g., 0x742d35Cc...)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
boolean
Indicates if the request was successful
string | null
The ZKS ID (without .zks suffix), or null if not set
string
The primary wallet address
object
Show properties
Show properties
number
Total ZKScore (0-10000)
number
Global rank position
string
Score tier:
bronze, silver, gold, platinum, diamond, legendarynumber
Percentile ranking (0-100)
object
Score breakdown by category (activity, volume, age, diversity, governance, social, risk, loyalty)
string
ISO 8601 timestamp of last score update
Examples
curl https://api.onzks.com/v1/score/alice.zks \
-H "Authorization: Bearer YOUR_API_KEY"
curl https://api.onzks.com/v1/score/0x742d35Cc6635C0532925a3b844D1FF4e1321 \
-H "Authorization: Bearer YOUR_API_KEY"
const response = await fetch('https://api.onzks.com/v1/score/alice.zks', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
console.log(`Score: ${data.score.total}, Rank: #${data.score.rank}`);
import requests
response = requests.get(
'https://api.onzks.com/v1/score/alice.zks',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
print(f"Score: {data['score']['total']}, Rank: #{data['score']['rank']}")
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 |
Related Endpoints
- Get Score Breakdown - Detailed score breakdown
- Get Score History - Historical score data
- Get Leaderboard - Top scores
⌘I