Get Achievement Progress

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

import requests

url = "https://api-mainnet.onzks.com/v1/achievements/:identity/progress/:achievementId"

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/achievements/:identity/progress/:achievementId', 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/progress/:achievementId",
  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/progress/:achievementId"

	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/progress/:achievementId")

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>",
  "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>'

import requests

url = "https://api-mainnet.onzks.com/v1/achievements/:identity/progress/:achievementId"

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/achievements/:identity/progress/:achievementId', 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/progress/:achievementId",
  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/progress/:achievementId"

	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/progress/:achievementId")

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

string

required

User identity (ZKS ID or wallet address)

ZKS ID is recommended for better performance and user experience

string

required

Unique identifier of the achievement

boolean

Include progress history over time (default: false)

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

boolean

Indicates if the request was successful

string

Resolved wallet address

string

ZKS ID if available, null otherwise

object

Achievement details

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

string

Achievement status (active, upcoming, limited, retired)

object

Current progress information

Show progress properties

boolean

Whether the achievement has been earned

string

ISO 8601 timestamp when earned (null if not earned)

number

Current progress value

number

Required value to earn achievement

number

Completion percentage (0-100)

number

Remaining value needed

object

Detailed requirements breakdown

array

Progress milestones

Show milestone properties

number

Milestone value

number

Milestone percentage

boolean

Whether milestone has been reached

string

When milestone was reached

array

Progress history over time (if includeHistory=true)

Show history properties

string

ISO 8601 timestamp

number

Progress value at this time

number

Completion percentage at this time

array

Events that contributed to progress

array

Suggestions for earning the achievement

object

Estimated time to completion

Show estimatedTime properties

number

Estimated days to completion

string

Confidence level (low, medium, high)

string

What the estimate is based on

string

ISO 8601 timestamp of the response

Examples

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

curl "https://api.onzks.com/v1/achievements/alice.zks/progress/defi-pioneer?includeHistory=true&timeframe=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

async function getAchievementProgress(identity, achievementId, options = {}) {
  const {
    includeHistory = false,
    timeframe = 'all'
  } = options;

  const params = new URLSearchParams();
  if (includeHistory) {
    params.append('includeHistory', 'true');
    params.append('timeframe', timeframe);
  }

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

  const data = await response.json();

  console.log(`Progress for ${data.achievement.title}:`);
  console.log(`${data.progress.percentage}% complete (${data.progress.current}/${data.progress.required})`);
  
  if (data.progress.earned) {
    console.log(`✅ Earned on ${new Date(data.progress.earnedAt).toLocaleDateString()}`);
  } else {
    console.log(`🔄 ${data.progress.remaining} remaining`);
    if (data.estimatedTime) {
      console.log(`Estimated completion: ${data.estimatedTime.days} days`);
    }
  }

  return data;
}

// Usage examples
await getAchievementProgress('alice.zks', 'defi-pioneer');
await getAchievementProgress('alice.zks', 'defi-pioneer', { includeHistory: true, timeframe: '30d' });

import requests

def get_achievement_progress(identity, achievement_id, include_history=False, timeframe='all'):
    params = {}
    if include_history:
        params['includeHistory'] = 'true'
        params['timeframe'] = timeframe
    
    response = requests.get(
        f'https://api.onzks.com/v1/achievements/{identity}/progress/{achievement_id}',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        params=params
    )
    
    data = response.json()
    
    print(f"Progress for {data['achievement']['title']}:")
    print(f"{data['progress']['percentage']}% complete ({data['progress']['current']}/{data['progress']['required']})")
    
    if data['progress']['earned']:
        print(f"✅ Earned on {data['progress']['earnedAt']}")
    else:
        print(f"🔄 {data['progress']['remaining']} remaining")
        if 'estimatedTime' in data:
            print(f"Estimated completion: {data['estimatedTime']['days']} days")
    
    return data

# Usage examples
get_achievement_progress('alice.zks', 'defi-pioneer')
get_achievement_progress('alice.zks', 'defi-pioneer', include_history=True, timeframe='30d')

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.

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

Get Achievement Progress

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

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

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