Get User Achievements

curl --request GET \
  --url https://api-mainnet.onzks.com/v1/achievements/:identity \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-mainnet.onzks.com/v1/achievements/: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/achievements/: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/achievements/: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))

}

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/achievements/: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,
  "address": "<string>",
  "zksId": "<string>",
  "achievements": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "category": "<string>",
      "rarity": "<string>",
      "points": 123,
      "scoreBonus": 123,
      "icon": "<string>",
      "earned": true,
      "earnedAt": "<string>",
      "progress": {
        "current": 123,
        "required": 123,
        "percentage": 123,
        "requirements": {}
      }
    }
  ],
  "claimableAchievements": [
    {}
  ],
  "claimableCount": 123,
  "summary": {
    "totalEarned": 123,
    "totalPoints": 123,
    "totalScoreBonus": 123,
    "rarityBreakdown": {},
    "categoryBreakdown": {}
  },
  "timestamp": "<string>"
}

GET

achievements

:identity

Get User Achievements

curl --request GET \
  --url https://api-mainnet.onzks.com/v1/achievements/:identity \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-mainnet.onzks.com/v1/achievements/: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/achievements/: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/achievements/: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))

}

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/achievements/: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,
  "address": "<string>",
  "zksId": "<string>",
  "achievements": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "category": "<string>",
      "rarity": "<string>",
      "points": 123,
      "scoreBonus": 123,
      "icon": "<string>",
      "earned": true,
      "earnedAt": "<string>",
      "progress": {
        "current": 123,
        "required": 123,
        "percentage": 123,
        "requirements": {}
      }
    }
  ],
  "claimableAchievements": [
    {}
  ],
  "claimableCount": 123,
  "summary": {
    "totalEarned": 123,
    "totalPoints": 123,
    "totalScoreBonus": 123,
    "rarityBreakdown": {},
    "categoryBreakdown": {}
  },
  "timestamp": "<string>"
}

Overview

Retrieve all achievements that have been earned by a specific user. This endpoint returns both earned achievements and progress toward unearned ones, making it perfect for building user profiles and achievement galleries.

Use this endpoint to display a user’s achievement collection, show their progress, and highlight their accomplishments.

Parameters

string

required

User identity (ZKS ID or wallet address)

ZKS ID is recommended for better performance and user experience

string

Filter by achievement category

wallet_age - Wallet longevity achievements
transaction_volume - Volume-based achievements
protocol_usage - Protocol interaction achievements
governance - DAO participation achievements
social - Social reputation achievements
defi - DeFi-specific achievements
nft - NFT-related achievements
trading - Trading achievements

string

Filter by achievement status

earned - Only earned achievements
in_progress - Only achievements in progress
all - Both earned and in progress (default)

string

Filter by rarity level

common - Easy to earn
uncommon - Moderate difficulty
rare - Challenging
epic - Very challenging
legendary - Extremely rare

number

Number of results to return (default: 50, max: 100)

number

Number of results to skip for pagination (default: 0)

Response

boolean

Indicates if the request was successful

string

Resolved wallet address

string

ZKS ID if available, null otherwise

array

Array of user achievement objects

Show achievement properties

string

Achievement identifier

string

Achievement title

string

Achievement description

string

Achievement category

string

Rarity level

number

Points awarded

number

ZKScore bonus

string

URL to achievement icon

boolean

Whether the user has earned this achievement

string

ISO 8601 timestamp when earned (null if not earned)

object

Progress toward achievement (if not earned)

Show progress properties

number

Current progress value

number

Required value to earn

number

Completion percentage (0-100)

object

Detailed requirements breakdown

array

Array of achievements ready to be claimed

number

Number of achievements ready to be claimed

object

Achievement summary statistics

Show summary properties

number

Total achievements earned

number

Total points from earned achievements

number

Total ZKScore bonus from achievements

object

Breakdown by rarity level

object

Breakdown by category

string

ISO 8601 timestamp of the response

Examples

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

curl "https://api.onzks.com/v1/achievements/alice.zks?category=defi&status=earned" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.onzks.com/v1/achievements/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
  -H "Authorization: Bearer YOUR_API_KEY"

async function getUserAchievements(identity, filters = {}) {
  const {
    category,
    status = 'all',
    rarity,
    limit = 50,
    offset = 0
  } = filters;

  const params = new URLSearchParams({
    status,
    limit: limit.toString(),
    offset: offset.toString()
  });

  if (category) params.append('category', category);
  if (rarity) params.append('rarity', rarity);

  const response = await fetch(
    `https://api.onzks.com/v1/achievements/${identity}?${params}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  console.log(`User ${data.zksId || data.address} has earned ${data.summary.totalEarned} achievements`);
  console.log(`Total points: ${data.summary.totalPoints}`);
  console.log(`Claimable achievements: ${data.claimableCount}`);

  return data;
}

// Usage examples
await getUserAchievements('alice.zks');
await getUserAchievements('alice.zks', { category: 'defi', status: 'earned' });
await getUserAchievements('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');

import requests

def get_user_achievements(identity, category=None, status='all', rarity=None, limit=50, offset=0):
    params = {
        'status': status,
        'limit': limit,
        'offset': offset
    }
    
    if category:
        params['category'] = category
    if rarity:
        params['rarity'] = rarity
    
    response = requests.get(
        f'https://api.onzks.com/v1/achievements/{identity}',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        params=params
    )
    
    data = response.json()
    
    print(f"User {data.get('zksId', data['address'])} has earned {data['summary']['totalEarned']} achievements")
    print(f"Total points: {data['summary']['totalPoints']}")
    print(f"Claimable achievements: {data['claimableCount']}")
    
    return data

# Usage examples
get_user_achievements('alice.zks')
get_user_achievements('alice.zks', category='defi', status='earned')
get_user_achievements('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb')

Response Example

{
  "success": true,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "zksId": "alice.zks",
  "achievements": [
    {
      "id": "defi-pioneer",
      "title": "DeFi Pioneer",
      "description": "Interact with 50+ different DeFi protocols across multiple chains",
      "category": "defi",
      "rarity": "legendary",
      "points": 5000,
      "scoreBonus": 500,
      "icon": "https://cdn.onzks.com/achievements/defi-pioneer.png",
      "earned": true,
      "earnedAt": "2024-01-15T10:30:00Z",
      "progress": null
    },
    {
      "id": "whale-trader",
      "title": "Whale Trader",
      "description": "Execute a single transaction worth over $1M",
      "category": "trading",
      "rarity": "epic",
      "points": 3000,
      "scoreBonus": 300,
      "icon": "https://cdn.onzks.com/achievements/whale-trader.png",
      "earned": false,
      "earnedAt": null,
      "progress": {
        "current": 750000,
        "required": 1000000,
        "percentage": 75,
        "requirements": {
          "singleTransactionValue": "1000000",
          "currentMax": "750000"
        }
      }
    },
    {
      "id": "governance-guru",
      "title": "Governance Guru",
      "description": "Vote on 100+ DAO proposals",
      "category": "governance",
      "rarity": "rare",
      "points": 2000,
      "scoreBonus": 200,
      "icon": "https://cdn.onzks.com/achievements/governance-guru.png",
      "earned": true,
      "earnedAt": "2024-01-10T14:20:00Z",
      "progress": null
    }
  ],
  "claimableAchievements": [
    {
      "id": "defi-pioneer",
      "title": "DeFi Pioneer",
      "points": 5000,
      "scoreBonus": 500
    }
  ],
  "claimableCount": 1,
  "summary": {
    "totalEarned": 2,
    "totalPoints": 7000,
    "totalScoreBonus": 700,
    "rarityBreakdown": {
      "legendary": 1,
      "epic": 0,
      "rare": 1,
      "uncommon": 0,
      "common": 0
    },
    "categoryBreakdown": {
      "defi": 1,
      "governance": 1,
      "trading": 0,
      "social": 0,
      "nft": 0,
      "wallet_age": 0,
      "transaction_volume": 0,
      "protocol_usage": 0
    }
  },
  "timestamp": "2024-01-20T15:45:00Z"
}

Use Cases

1. User Profile Achievement Gallery

Display a user’s achievement collection:

async function displayUserAchievements(identity) {
  const data = await getUserAchievements(identity);

  console.log(`\n🏆 ${data.zksId || data.address}'s Achievements`);
  console.log(`Total: ${data.summary.totalEarned} earned, ${data.claimableCount} claimable`);
  console.log(`Points: ${data.summary.totalPoints}, Score Bonus: ${data.summary.totalScoreBonus}\n`);

  // Group by category
  const byCategory = data.achievements.reduce((acc, achievement) => {
    if (!acc[achievement.category]) {
      acc[achievement.category] = { earned: [], inProgress: [] };
    }
    
    if (achievement.earned) {
      acc[achievement.category].earned.push(achievement);
    } else {
      acc[achievement.category].inProgress.push(achievement);
    }
    
    return acc;
  }, {});

  // Display by category
  Object.entries(byCategory).forEach(([category, achievements]) => {
    console.log(`\n📂 ${category.toUpperCase()}:`);
    
    if (achievements.earned.length > 0) {
      console.log('  ✅ Earned:');
      achievements.earned.forEach(achievement => {
        console.log(`    ${achievement.title} (${achievement.rarity}) - ${achievement.points} points`);
      });
    }
    
    if (achievements.inProgress.length > 0) {
      console.log('  🔄 In Progress:');
      achievements.inProgress.forEach(achievement => {
        console.log(`    ${achievement.title} - ${achievement.progress.percentage}% complete`);
      });
    }
  });
}

2. Achievement Progress Tracking

Track progress toward specific achievements:

async function trackAchievementProgress(identity, achievementId) {
  const data = await getUserAchievements(identity);
  
  const achievement = data.achievements.find(a => a.id === achievementId);
  
  if (!achievement) {
    console.log('Achievement not found');
    return;
  }
  
  if (achievement.earned) {
    console.log(`✅ ${achievement.title} - Earned on ${new Date(achievement.earnedAt).toLocaleDateString()}`);
  } else {
    console.log(`🔄 ${achievement.title}`);
    console.log(`Progress: ${achievement.progress.current}/${achievement.progress.required} (${achievement.progress.percentage}%)`);
    
    if (achievement.progress.requirements) {
      console.log('Requirements:');
      Object.entries(achievement.progress.requirements).forEach(([key, value]) => {
        console.log(`  ${key}: ${value}`);
      });
    }
  }
}

3. Claimable Achievements Notification

Show achievements ready to be claimed:

async function getClaimableAchievements(identity) {
  const data = await getUserAchievements(identity);
  
  if (data.claimableCount === 0) {
    console.log('No achievements ready to claim');
    return;
  }
  
  console.log(`🎉 ${data.claimableCount} achievements ready to claim!`);
  
  data.claimableAchievements.forEach(achievement => {
    console.log(`- ${achievement.title}: ${achievement.points} points, ${achievement.scoreBonus} score bonus`);
  });
  
  return data.claimableAchievements;
}

4. Achievement Statistics

Show detailed achievement statistics:

async function getAchievementStats(identity) {
  const data = await getUserAchievements(identity);
  const summary = data.summary;
  
  console.log(`\n📊 Achievement Statistics for ${data.zksId || data.address}`);
  console.log(`Total Earned: ${summary.totalEarned}`);
  console.log(`Total Points: ${summary.totalPoints.toLocaleString()}`);
  console.log(`Score Bonus: ${summary.totalScoreBonus}`);
  console.log(`Claimable: ${data.claimableCount}\n`);
  
  console.log('Rarity Breakdown:');
  Object.entries(summary.rarityBreakdown).forEach(([rarity, count]) => {
    if (count > 0) {
      console.log(`  ${rarity}: ${count}`);
    }
  });
  
  console.log('\nCategory Breakdown:');
  Object.entries(summary.categoryBreakdown).forEach(([category, count]) => {
    if (count > 0) {
      console.log(`  ${category}: ${count}`);
    }
  });
}

Best Practices

1. Cache User Achievements

User achievements don’t change frequently:

let userAchievementCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedUserAchievements(identity, filters = {}) {
  const cacheKey = `${identity}-${JSON.stringify(filters)}`;
  const cached = userAchievementCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await getUserAchievements(identity, filters);
  userAchievementCache.set(cacheKey, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

2. Filter by Status

Optimize queries by filtering status:

// Get only earned achievements
const earnedAchievements = await getUserAchievements(identity, { status: 'earned' });

// Get only achievements in progress
const inProgressAchievements = await getUserAchievements(identity, { status: 'in_progress' });

3. Paginate Large Results

Handle users with many achievements:

async function getAllUserAchievements(identity, filters = {}) {
  const allAchievements = [];
  let offset = 0;
  const limit = 50;
  
  while (true) {
    const data = await getUserAchievements(identity, {
      ...filters,
      limit,
      offset
    });
    
    allAchievements.push(...data.achievements);
    
    if (data.achievements.length < limit) {
      break;
    }
    
    offset += limit;
  }
  
  return allAchievements;
}

4. Real-time Updates

Subscribe to achievement updates:

function subscribeToAchievementUpdates(identity, callback) {
  // WebSocket connection for real-time updates
  const ws = new WebSocket(`wss://api.onzks.com/v1/achievements/${identity}/subscribe`);
  
  ws.onmessage = (event) => {
    const update = JSON.parse(event.data);
    callback(update);
  };
  
  return () => ws.close();
}

// Usage
const unsubscribe = subscribeToAchievementUpdates('alice.zks', (update) => {
  console.log('New achievement earned:', update.achievement.title);
});

List Achievements - All available achievements
Get Achievement Progress - Progress toward specific achievement
Claim Achievement - Claim an earned achievement

Troubleshooting

”User not found”

Cause: Invalid identity or user doesn’t exist. Solution:

Verify the identity format (ZKS ID or wallet address)
Check if the user has any activity on the platform
Try with a different identity

”No achievements found”

Cause: User has no achievements or filters are too restrictive. Solution:

Remove filters to see all achievements
Check if user has any platform activity
Verify achievement categories exist

”Invalid status filter”

Cause: Unsupported status value. Solution:

Use supported statuses: earned, in_progress, all
Check for typos in filter values

Rate Limits

User achievement requests are subject to rate limits:

Free tier: 60 requests per minute
Starter tier: 300 requests per minute
Professional tier: 1,000 requests per minute
Enterprise tier: Custom limits

Implement caching to reduce API calls.

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

Get User Achievements

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. User Profile Achievement Gallery

2. Achievement Progress Tracking

3. Claimable Achievements Notification

4. Achievement Statistics

Best Practices

1. Cache User Achievements

2. Filter by Status

3. Paginate Large Results

4. Real-time Updates

Troubleshooting

”User not found”

”No achievements found”

”Invalid status filter”

Rate Limits

​Overview

​Parameters

​Response

​Examples

​Response Example

​Use Cases

​1. User Profile Achievement Gallery

​2. Achievement Progress Tracking

​3. Claimable Achievements Notification

​4. Achievement Statistics

​Best Practices

​1. Cache User Achievements

​2. Filter by Status

​3. Paginate Large Results

​4. Real-time Updates

​Related Endpoints

​Troubleshooting

​”User not found”

​”No achievements found”

​”Invalid status filter”

​Rate Limits

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. User Profile Achievement Gallery

2. Achievement Progress Tracking

3. Claimable Achievements Notification

4. Achievement Statistics

Best Practices

1. Cache User Achievements

2. Filter by Status

3. Paginate Large Results

4. Real-time Updates

Related Endpoints

Troubleshooting

”User not found”

”No achievements found”

”Invalid status filter”

Rate Limits