Skip to main content
GET
https://api-mainnet.onzks.com
/
v1
/
achievements
List Achievements
curl --request GET \
  --url https://api-mainnet.onzks.com/v1/achievements \
  --header 'Authorization: Bearer <token>'
{
  "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

category
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
rarity
string
Filter by rarity level
  • common - Easy to earn
  • uncommon - Moderate difficulty
  • rare - Challenging
  • epic - Very challenging
  • legendary - Extremely rare
status
string
Filter by achievement status
  • active - Currently available
  • upcoming - Coming soon
  • limited - Limited time only
  • retired - No longer available
limit
number
Number of results to return (default: 50, max: 100)
offset
number
Number of results to skip for pagination (default: 0)

Response

success
boolean
Indicates if the request was successful
achievements
array
Array of achievement objects
pagination
object

Examples

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

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

Social

  • 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

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'
  }));
}

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.