> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get User Achievements

> Get all achievements earned by a specific user

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

<Tip>
  Use this endpoint to display a user's achievement collection, show their progress, and highlight their accomplishments.
</Tip>

## Parameters

<ParamField path="identity" type="string" required>
  User identity (ZKS ID or wallet address)

  <Note>
    ZKS ID is recommended for better performance and user experience
  </Note>
</ParamField>

<ParamField query="category" type="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
</ParamField>

<ParamField query="status" type="string">
  Filter by achievement status

  * `earned` - Only earned achievements
  * `in_progress` - Only achievements in progress
  * `all` - Both earned and in progress (default)
</ParamField>

<ParamField query="rarity" type="string">
  Filter by rarity level

  * `common` - Easy to earn
  * `uncommon` - Moderate difficulty
  * `rare` - Challenging
  * `epic` - Very challenging
  * `legendary` - Extremely rare
</ParamField>

<ParamField query="limit" type="number">
  Number of results to return (default: 50, max: 100)
</ParamField>

<ParamField query="offset" type="number">
  Number of results to skip for pagination (default: 0)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="address" type="string">
  Resolved wallet address
</ResponseField>

<ResponseField name="zksId" type="string">
  ZKS ID if available, null otherwise
</ResponseField>

<ResponseField name="achievements" type="array">
  Array of user achievement objects

  <Expandable title="achievement properties">
    <ResponseField name="id" type="string">
      Achievement identifier
    </ResponseField>

    <ResponseField name="title" type="string">
      Achievement title
    </ResponseField>

    <ResponseField name="description" type="string">
      Achievement description
    </ResponseField>

    <ResponseField name="category" type="string">
      Achievement category
    </ResponseField>

    <ResponseField name="rarity" type="string">
      Rarity level
    </ResponseField>

    <ResponseField name="points" type="number">
      Points awarded
    </ResponseField>

    <ResponseField name="scoreBonus" type="number">
      ZKScore bonus
    </ResponseField>

    <ResponseField name="icon" type="string">
      URL to achievement icon
    </ResponseField>

    <ResponseField name="earned" type="boolean">
      Whether the user has earned this achievement
    </ResponseField>

    <ResponseField name="earnedAt" type="string">
      ISO 8601 timestamp when earned (null if not earned)
    </ResponseField>

    <ResponseField name="progress" type="object">
      Progress toward achievement (if not earned)

      <Expandable title="progress properties">
        <ResponseField name="current" type="number">
          Current progress value
        </ResponseField>

        <ResponseField name="required" type="number">
          Required value to earn
        </ResponseField>

        <ResponseField name="percentage" type="number">
          Completion percentage (0-100)
        </ResponseField>

        <ResponseField name="requirements" type="object">
          Detailed requirements breakdown
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="claimableAchievements" type="array">
  Array of achievements ready to be claimed
</ResponseField>

<ResponseField name="claimableCount" type="number">
  Number of achievements ready to be claimed
</ResponseField>

<ResponseField name="summary" type="object">
  Achievement summary statistics

  <Expandable title="summary properties">
    <ResponseField name="totalEarned" type="number">
      Total achievements earned
    </ResponseField>

    <ResponseField name="totalPoints" type="number">
      Total points from earned achievements
    </ResponseField>

    <ResponseField name="totalScoreBonus" type="number">
      Total ZKScore bonus from achievements
    </ResponseField>

    <ResponseField name="rarityBreakdown" type="object">
      Breakdown by rarity level
    </ResponseField>

    <ResponseField name="categoryBreakdown" type="object">
      Breakdown by category
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of the response
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL (All Achievements) theme={null}
  curl "https://api.onzks.com/v1/achievements/alice.zks" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (DeFi Achievements Only) theme={null}
  curl "https://api.onzks.com/v1/achievements/alice.zks?category=defi&status=earned" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (Wallet Address) theme={null}
  curl "https://api.onzks.com/v1/achievements/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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');
  ```

  ```python Python theme={null}
  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')
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
// 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:

```javascript theme={null}
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:

```javascript theme={null}
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);
});
```

## Related Endpoints

* [List Achievements](/api-reference/achievements/list-achievements) - All available achievements
* [Get Achievement Progress](/api-reference/achievements/get-progress) - Progress toward specific achievement
* [Claim Achievement](/api-reference/achievements/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.