List Achievements

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

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

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

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

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,
  "achievements": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "category": "<string>",
      "rarity": "<string>",
      "points": 123,
      "scoreBonus": 123,
      "requirements": {},
      "icon": "<string>",
      "status": "<string>",
      "earnedBy": 123,
      "createdAt": "<string>"
    }
  ],
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "hasMore": true
  }
}

GET

achievements

List Achievements

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

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

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

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

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,
  "achievements": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "category": "<string>",
      "rarity": "<string>",
      "points": 123,
      "scoreBonus": 123,
      "requirements": {},
      "icon": "<string>",
      "status": "<string>",
      "earnedBy": 123,
      "createdAt": "<string>"
    }
  ],
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "hasMore": true
  }
}

Overview

Retrieve a complete list of all available achievements in the ZKScore platform. This endpoint supports filtering by category, rarity, and status, making it easy to discover achievements and build achievement galleries.

Use this endpoint to display available achievements, show requirements, and help users discover what they can earn.

Parameters

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 rarity level

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

string

Filter by achievement status

active - Currently available
upcoming - Coming soon
limited - Limited time only
retired - No longer available

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

array

Array of achievement objects

Show achievement properties

string

Unique achievement identifier

string

Achievement title

string

Detailed description

string

Achievement category

string

Rarity level (common, uncommon, rare, epic, legendary)

number

Points awarded for earning this achievement

number

ZKScore bonus for earning this achievement

object

Requirements to earn the achievement

string

URL to achievement icon/image

string

Current status (active, upcoming, limited, retired)

number

Number of users who have earned this achievement

string

ISO 8601 timestamp of when achievement was created

object

Show properties

number

Total number of achievements matching filters

number

Number of results returned

number

Current offset

boolean

Whether more results are available

Examples

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

curl "https://api.onzks.com/v1/achievements?category=defi&rarity=rare" \
  -H "Authorization: Bearer YOUR_API_KEY"

async function listAchievements(filters = {}) {
  const {
    category,
    rarity,
    status = 'active',
    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?${params}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  console.log(`Found ${data.achievements.length} achievements`);
  data.achievements.forEach(achievement => {
    console.log(`- ${achievement.title} (${achievement.rarity})`);
  });

  return data;
}

// Usage
await listAchievements({ category: 'defi', rarity: 'legendary' });

import requests

def list_achievements(category=None, rarity=None, status='active', limit=50, offset=0):
    params = {
        'status': status,
        'limit': limit,
        'offset': offset
    }
    
    if category:
        params['category'] = category
    if rarity:
        params['rarity'] = rarity
    
    response = requests.get(
        'https://api.onzks.com/v1/achievements',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        params=params
    )
    
    data = response.json()
    
    print(f"Found {len(data['achievements'])} achievements")
    for achievement in data['achievements']:
        print(f"- {achievement['title']} ({achievement['rarity']})")
    
    return data

# Usage
list_achievements(category='defi', rarity='legendary')

Response Example

{
  "success": true,
  "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,
      "requirements": {
        "uniqueProtocols": 50,
        "minimumChains": 3,
        "minimumVolume": "100000"
      },
      "icon": "https://cdn.onzks.com/achievements/defi-pioneer.png",
      "status": "active",
      "earnedBy": 47,
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "whale-trader",
      "title": "Whale Trader",
      "description": "Execute a single transaction worth over $1M",
      "category": "trading",
      "rarity": "epic",
      "points": 3000,
      "scoreBonus": 300,
      "requirements": {
        "singleTransactionValue": "1000000"
      },
      "icon": "https://cdn.onzks.com/achievements/whale-trader.png",
      "status": "active",
      "earnedBy": 123,
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "governance-guru",
      "title": "Governance Guru",
      "description": "Vote on 100+ DAO proposals",
      "category": "governance",
      "rarity": "rare",
      "points": 2000,
      "scoreBonus": 200,
      "requirements": {
        "proposalsVoted": 100,
        "minimumDaos": 5
      },
      "icon": "https://cdn.onzks.com/achievements/governance-guru.png",
      "status": "active",
      "earnedBy": 456,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 127,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Achievement Categories

Wallet Age

Early Adopter - Wallet created before 2020
Veteran - Wallet active for 3+ years
OG - Wallet from 2017 or earlier

Transaction Volume

Volume Trader - $100K+ total volume
Whale - $1M+ total volume
Mega Whale - $10M+ total volume

Protocol Usage

Protocol Explorer - Used 10+ protocols
Multi-Chain Master - Active on 5+ chains
DeFi Pioneer - Used 50+ DeFi protocols

Governance

Active Voter - Voted on 10+ proposals
DAO Participant - Active in 5+ DAOs
Governance Guru - Voted on 100+ proposals

Well Connected - 50+ trusted connections
Community Leader - 100+ attestations received
Influencer - 500+ social connections

DeFi

Yield Farmer - Provided liquidity to 10+ pools
Lending Pro - Lent assets on 5+ platforms
DeFi Native - Active DeFi user for 2+ years

NFT

NFT Collector - Own 50+ NFTs
Blue Chip Holder - Own NFTs from top collections
NFT Trader - Traded 100+ NFTs

Trading

Day Trader - 1000+ trades
Profitable Trader - 80%+ win rate
Market Maker - Provided liquidity consistently

Use Cases

1. Achievement Gallery

Display all available achievements:

async function displayAchievementGallery() {
  const { achievements } = await listAchievements({ status: 'active' });

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

  // Render gallery
  Object.entries(byCategory).forEach(([category, items]) => {
    console.log(`\n${category.toUpperCase()}:`);
    items.forEach(achievement => {
      console.log(`  ${achievement.title} - ${achievement.points} points`);
    });
  });
}

2. Filter by Rarity

Show achievements by rarity:

async function getAchievementsByRarity(rarity) {
  const { achievements } = await listAchievements({ rarity });

  console.log(`${rarity.toUpperCase()} Achievements:`);
  achievements.forEach(achievement => {
    const percentage = (achievement.earnedBy / 125847 * 100).toFixed(2);
    console.log(`${achievement.title} - Earned by ${percentage}% of users`);
  });

  return achievements;
}

// Get legendary achievements
await getAchievementsByRarity('legendary');

3. Discover New Achievements

Show recently added achievements:

async function getNewAchievements() {
  const { achievements } = await listAchievements({ status: 'active' });

  // Sort by creation date
  const recent = achievements
    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
    .slice(0, 10);

  console.log('Recently Added Achievements:');
  recent.forEach(achievement => {
    console.log(`${achievement.title} - Added ${new Date(achievement.createdAt).toLocaleDateString()}`);
  });

  return recent;
}

4. Paginated Achievement List

Implement pagination:

async function getPaginatedAchievements(page = 1, pageSize = 20) {
  const offset = (page - 1) * pageSize;

  const data = await listAchievements({
    limit: pageSize,
    offset
  });

  return {
    achievements: data.achievements,
    currentPage: page,
    totalPages: Math.ceil(data.pagination.total / pageSize),
    hasNext: data.pagination.hasMore,
    hasPrevious: page > 1
  };
}

// Load first page
const page1 = await getPaginatedAchievements(1, 20);

Best Practices

1. Cache Achievement List

Achievements don’t change frequently:

let achievementCache = null;
let cacheTimestamp = null;
const CACHE_TTL = 60 * 60 * 1000; // 1 hour

async function getCachedAchievements(filters = {}) {
  const cacheKey = JSON.stringify(filters);

  if (achievementCache && cacheTimestamp) {
    if (Date.now() - cacheTimestamp < CACHE_TTL) {
      return achievementCache;
    }
  }

  const data = await listAchievements(filters);
  achievementCache = data;
  cacheTimestamp = Date.now();

  return data;
}

2. Group by Category

Organize achievements for better UX:

function groupAchievementsByCategory(achievements) {
  return achievements.reduce((groups, achievement) => {
    const category = achievement.category;
    if (!groups[category]) {
      groups[category] = {
        name: category,
        achievements: [],
        totalPoints: 0
      };
    }
    groups[category].achievements.push(achievement);
    groups[category].totalPoints += achievement.points;
    return groups;
  }, {});
}

3. Sort by Difficulty

Show achievements by difficulty:

const rarityOrder = {
  'common': 1,
  'uncommon': 2,
  'rare': 3,
  'epic': 4,
  'legendary': 5
};

function sortByDifficulty(achievements) {
  return achievements.sort((a, b) => {
    return rarityOrder[a.rarity] - rarityOrder[b.rarity];
  });
}

4. Calculate Completion Rate

Show how rare each achievement is:

function calculateCompletionRates(achievements, totalUsers = 125847) {
  return achievements.map(achievement => ({
    ...achievement,
    completionRate: (achievement.earnedBy / totalUsers * 100).toFixed(2),
    rarity: achievement.earnedBy < 100 ? 'ultra-rare' :
            achievement.earnedBy < 1000 ? 'very-rare' :
            achievement.earnedBy < 10000 ? 'rare' : 'common'
  }));
}

Get User Achievements - User’s earned achievements
Get Achievement Progress - Progress toward achievement
Claim Achievement - Claim an earned achievement

Troubleshooting

”No achievements found”

Cause: Filters are too restrictive or no achievements match criteria. Solution:

Remove some filters
Check filter values are correct
Try without filters to see all achievements

”Invalid category”

Cause: Unsupported category value. Solution:

Use supported categories: wallet_age, transaction_volume, protocol_usage, governance, social, defi, nft, trading
Check for typos

Rate Limits

Achievement list 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

List Achievements

Overview

Parameters

Response

Examples

Response Example

Achievement Categories

Wallet Age

Transaction Volume

Protocol Usage

Governance

DeFi

NFT

Trading

Use Cases

1. Achievement Gallery

2. Filter by Rarity

3. Discover New Achievements

4. Paginated Achievement List

Best Practices

1. Cache Achievement List

2. Group by Category

3. Sort by Difficulty

4. Calculate Completion Rate

Troubleshooting

”No achievements found”

”Invalid category”

Rate Limits

​Overview

​Parameters

​Response

​Examples

​Response Example

​Achievement Categories

​Wallet Age

​Transaction Volume

​Protocol Usage

​Governance

​Social

​DeFi

​NFT

​Trading

​Use Cases

​1. Achievement Gallery

​2. Filter by Rarity

​3. Discover New Achievements

​4. Paginated Achievement List

​Best Practices

​1. Cache Achievement List

​2. Group by Category

​3. Sort by Difficulty

​4. Calculate Completion Rate

​Related Endpoints

​Troubleshooting

​”No achievements found”

​”Invalid category”

​Rate Limits

Overview

Parameters

Response

Examples

Response Example

Achievement Categories

Wallet Age

Transaction Volume

Protocol Usage

Governance

Social

DeFi

NFT

Trading

Use Cases

1. Achievement Gallery

2. Filter by Rarity

3. Discover New Achievements

4. Paginated Achievement List

Best Practices

1. Cache Achievement List

2. Group by Category

3. Sort by Difficulty

4. Calculate Completion Rate

Related Endpoints

Troubleshooting

”No achievements found”

”Invalid category”

Rate Limits