Get Achievement Progress

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

{
  "success": true,
  "address": "<string>",
  "zksId": "<string>",
  "achievement": {
    "id": "<string>",
    "title": "<string>",
    "description": "<string>",
    "category": "<string>",
    "rarity": "<string>",
    "points": 123,
    "scoreBonus": 123,
    "icon": "<string>",
    "status": "<string>"
  },
  "progress": {
    "earned": true,
    "earnedAt": "<string>",
    "current": 123,
    "required": 123,
    "percentage": 123,
    "remaining": 123,
    "requirements": {},
    "milestones": [
      {
        "value": 123,
        "percentage": 123,
        "reached": true,
        "reachedAt": "<string>"
      }
    ]
  },
  "history": [
    {
      "timestamp": "<string>",
      "value": 123,
      "percentage": 123,
      "events": [
        {}
      ]
    }
  ],
  "suggestions": [
    {}
  ],
  "estimatedTime": {
    "days": 123,
    "confidence": "<string>",
    "basedOn": "<string>"
  },
  "timestamp": "<string>"
}

GET

achievements

:identity

progress

:achievementId

Get Achievement Progress

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

{
  "success": true,
  "address": "<string>",
  "zksId": "<string>",
  "achievement": {
    "id": "<string>",
    "title": "<string>",
    "description": "<string>",
    "category": "<string>",
    "rarity": "<string>",
    "points": 123,
    "scoreBonus": 123,
    "icon": "<string>",
    "status": "<string>"
  },
  "progress": {
    "earned": true,
    "earnedAt": "<string>",
    "current": 123,
    "required": 123,
    "percentage": 123,
    "remaining": 123,
    "requirements": {},
    "milestones": [
      {
        "value": 123,
        "percentage": 123,
        "reached": true,
        "reachedAt": "<string>"
      }
    ]
  },
  "history": [
    {
      "timestamp": "<string>",
      "value": 123,
      "percentage": 123,
      "events": [
        {}
      ]
    }
  ],
  "suggestions": [
    {}
  ],
  "estimatedTime": {
    "days": 123,
    "confidence": "<string>",
    "basedOn": "<string>"
  },
  "timestamp": "<string>"
}

Overview

Retrieve detailed progress information for a specific achievement. This endpoint shows current progress, requirements breakdown, and completion percentage, making it perfect for progress bars and achievement tracking interfaces.

Use this endpoint to show users exactly what they need to do to earn an achievement and track their progress in real-time.

Parameters

identity

string

required

User identity (ZKS ID or wallet address)

ZKS ID is recommended for better performance and user experience

achievementId

string

required

Unique identifier of the achievement

includeHistory

boolean

Include progress history over time (default: false)

timeframe

string

Timeframe for history (if includeHistory=true)

7d - Last 7 days
30d - Last 30 days
90d - Last 90 days
1y - Last year
all - All time (default)

Response

success

boolean

Indicates if the request was successful

address

string

Resolved wallet address

zksId

string

ZKS ID if available, null otherwise

achievement

object

Achievement details

Show achievement properties

string

Achievement identifier

title

string

Achievement title

description

string

Achievement description

Examples

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

Response Example

{
  "success": true,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "zksId": "alice.zks",
  "achievement": {
    "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",
    "status": "active"
  },
  "progress": {
    "earned": false,
    "earnedAt": null,
    "current": 42,
    "required": 50,
    "percentage": 84,
    "remaining": 8,
    "requirements": {
      "uniqueProtocols": 50,
      "minimumChains": 3,
      "minimumVolume": "100000",
      "currentProtocols": 42,
      "currentChains": 3,
      "currentVolume": "125000"
    },
    "milestones": [
      {
        "value": 10,
        "percentage": 20,
        "reached": true,
        "reachedAt": "2024-01-05T10:30:00Z"
      },
      {
        "value": 25,
        "percentage": 50,
        "reached": true,
        "reachedAt": "2024-01-10T14:20:00Z"
      },
      {
        "value": 40,
        "percentage": 80,
        "reached": true,
        "reachedAt": "2024-01-15T09:45:00Z"
      },
      {
        "value": 50,
        "percentage": 100,
        "reached": false,
        "reachedAt": null
      }
    ]
  },
  "history": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "value": 5,
      "percentage": 10,
      "events": ["Uniswap interaction", "Aave lending"]
    },
    {
      "timestamp": "2024-01-05T10:30:00Z",
      "value": 10,
      "percentage": 20,
      "events": ["Compound lending", "Curve trading"]
    },
    {
      "timestamp": "2024-01-10T14:20:00Z",
      "value": 25,
      "percentage": 50,
      "events": ["Yearn vault", "SushiSwap farming"]
    },
    {
      "timestamp": "2024-01-15T09:45:00Z",
      "value": 40,
      "percentage": 80,
      "events": ["Balancer pool", "1inch aggregation"]
    },
    {
      "timestamp": "2024-01-20T15:45:00Z",
      "value": 42,
      "percentage": 84,
      "events": ["PancakeSwap", "QuickSwap"]
    }
  ],
  "suggestions": [
    "Try interacting with Balancer pools",
    "Explore lending protocols like Venus or Cream",
    "Check out newer DeFi protocols on Layer 2",
    "Consider cross-chain DeFi protocols"
  ],
  "estimatedTime": {
    "days": 7,
    "confidence": "high",
    "basedOn": "Recent activity patterns and protocol discovery rate"
  },
  "timestamp": "2024-01-20T15:45:00Z"
}

Use Cases

1. Progress Bar Component

Create a visual progress bar:

function createProgressBar(progress) {
  const percentage = progress.percentage;
  const current = progress.current;
  const required = progress.required;
  
  return `
    <div class="progress-container">
      <div class="progress-header">
        <h3>${progress.achievement.title}</h3>
        <span class="percentage">${percentage}%</span>
      </div>
      <div class="progress-bar">
        <div class="progress-fill" style="width: ${percentage}%"></div>
      </div>
      <div class="progress-text">
        ${current}/${required} (${progress.remaining} remaining)
      </div>
    </div>
  `;
}

// Usage
const progress = await getAchievementProgress('alice.zks', 'defi-pioneer');
const progressBar = createProgressBar(progress);
document.getElementById('progress-container').innerHTML = progressBar;

2. Milestone Tracking

Show progress milestones:

function displayMilestones(progress) {
  console.log(`\n🎯 Milestones for ${progress.achievement.title}:`);
  
  progress.milestones.forEach((milestone, index) => {
    const status = milestone.reached ? '✅' : '⏳';
    const reachedText = milestone.reached ? 
      ` (reached ${new Date(milestone.reachedAt).toLocaleDateString()})` : '';
    
    console.log(`${status} Milestone ${index + 1}: ${milestone.value} protocols (${milestone.percentage}%)${reachedText}`);
  });
}

3. Progress History Chart

Visualize progress over time:

async function createProgressChart(identity, achievementId) {
  const data = await getAchievementProgress(identity, achievementId, {
    includeHistory: true,
    timeframe: '30d'
  });
  
  const chartData = data.history.map(point => ({
    x: new Date(point.timestamp),
    y: point.percentage
  }));
  
  // Use your preferred charting library
  const chart = new Chart('progress-chart', {
    type: 'line',
    data: {
      datasets: [{
        label: 'Progress %',
        data: chartData,
        borderColor: '#4F46E5',
        backgroundColor: 'rgba(79, 70, 229, 0.1)'
      }]
    },
    options: {
      scales: {
        x: { type: 'time' },
        y: { min: 0, max: 100 }
      }
    }
  });
}

4. Achievement Suggestions

Show helpful suggestions:

function displaySuggestions(progress) {
  if (progress.suggestions && progress.suggestions.length > 0) {
    console.log(`\n💡 Suggestions to earn ${progress.achievement.title}:`);
    progress.suggestions.forEach((suggestion, index) => {
      console.log(`${index + 1}. ${suggestion}`);
    });
  }
}

5. Time Estimation

Show estimated completion time:

function displayTimeEstimate(progress) {
  if (progress.estimatedTime) {
    const { days, confidence, basedOn } = progress.estimatedTime;
    
    console.log(`\n⏰ Estimated completion: ${days} days`);
    console.log(`Confidence: ${confidence}`);
    console.log(`Based on: ${basedOn}`);
    
    if (days <= 7) {
      console.log('🎉 You\'re close to earning this achievement!');
    } else if (days <= 30) {
      console.log('📈 Good progress! Keep it up!');
    } else {
      console.log('🏃‍♂️ This will take some time, but you\'re making progress!');
    }
  }
}

Best Practices

1. Cache Progress Data

Progress data changes frequently but can be cached briefly:

let progressCache = new Map();
const CACHE_TTL = 2 * 60 * 1000; // 2 minutes

async function getCachedProgress(identity, achievementId, options = {}) {
  const cacheKey = `${identity}-${achievementId}-${JSON.stringify(options)}`;
  const cached = progressCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await getAchievementProgress(identity, achievementId, options);
  progressCache.set(cacheKey, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

2. Real-time Updates

Subscribe to progress updates:

function subscribeToProgressUpdates(identity, achievementId, callback) {
  const ws = new WebSocket(`wss://api.onzks.com/v1/achievements/${identity}/progress/${achievementId}/subscribe`);
  
  ws.onmessage = (event) => {
    const update = JSON.parse(event.data);
    callback(update);
  };
  
  return () => ws.close();
}

// Usage
const unsubscribe = subscribeToProgressUpdates('alice.zks', 'defi-pioneer', (update) => {
  console.log(`Progress updated: ${update.percentage}%`);
  updateProgressBar(update);
});

3. Batch Progress Queries

Get progress for multiple achievements:

async function getMultipleProgress(identity, achievementIds) {
  const promises = achievementIds.map(id => 
    getAchievementProgress(identity, id)
  );
  
  const results = await Promise.all(promises);
  
  return results.reduce((acc, result) => {
    acc[result.achievement.id] = result;
    return acc;
  }, {});
}

// Usage
const progress = await getMultipleProgress('alice.zks', ['defi-pioneer', 'whale-trader', 'governance-guru']);

4. Progress Analytics

Analyze progress patterns:

function analyzeProgress(progress) {
  const { current, required, percentage } = progress.progress;
  
  const analysis = {
    completionRate: percentage,
    isOnTrack: percentage >= 50,
    isClose: percentage >= 80,
    isStalled: percentage < 10 && current > 0,
    needsBoost: percentage < 25 && current > 0
  };
  
  return analysis;
}

Get User Achievements - All user achievements
List Achievements - All available achievements
Claim Achievement - Claim an earned achievement

Troubleshooting

”Achievement not found”

Cause: Invalid achievement ID or achievement doesn’t exist. Solution:

Verify the achievement ID is correct
Check if the achievement is still active
Use the list achievements endpoint to see available achievements

”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

”No progress data”

Cause: User hasn’t started working toward this achievement. Solution:

This is normal for new achievements
Progress will appear once the user starts relevant activities

Rate Limits

Progress 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.

Get User Achievements Claim Achievement

​Overview

​Parameters

​Response

​Examples

​Response Example

​Use Cases

​1. Progress Bar Component

​2. Milestone Tracking

​3. Progress History Chart

​4. Achievement Suggestions

​5. Time Estimation

​Best Practices

​1. Cache Progress Data

​2. Real-time Updates

​3. Batch Progress Queries

​4. Progress Analytics

​Related Endpoints

​Troubleshooting

​”Achievement not found”

​”User not found”

​”No progress data”

​Rate Limits

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Progress Bar Component

2. Milestone Tracking

3. Progress History Chart

4. Achievement Suggestions

5. Time Estimation

Best Practices

1. Cache Progress Data

2. Real-time Updates

3. Batch Progress Queries

4. Progress Analytics

Related Endpoints

Troubleshooting

”Achievement not found”

”User not found”

”No progress data”

Rate Limits