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

# List Achievements

> Get all available achievements in the ZKScore ecosystem

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

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

## Parameters

<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="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="status" type="string">
  Filter by achievement status

  * `active` - Currently available
  * `upcoming` - Coming soon
  * `limited` - Limited time only
  * `retired` - No longer available
</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="achievements" type="array">
  Array of achievement objects

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

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

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

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

    <ResponseField name="rarity" type="string">
      Rarity level (common, uncommon, rare, epic, legendary)
    </ResponseField>

    <ResponseField name="points" type="number">
      Points awarded for earning this achievement
    </ResponseField>

    <ResponseField name="scoreBonus" type="number">
      ZKScore bonus for earning this achievement
    </ResponseField>

    <ResponseField name="requirements" type="object">
      Requirements to earn the achievement
    </ResponseField>

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

    <ResponseField name="status" type="string">
      Current status (active, upcoming, limited, retired)
    </ResponseField>

    <ResponseField name="earnedBy" type="number">
      Number of users who have earned this achievement
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when achievement was created
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="total" type="number">
      Total number of achievements matching filters
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of results returned
    </ResponseField>

    <ResponseField name="offset" type="number">
      Current offset
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether more results are available
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

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

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

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

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

## Response Example

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

### 1. Achievement Gallery

Display all available achievements:

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

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

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

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

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

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

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

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

## Related Endpoints

* [Get User Achievements](/api-reference/achievements/get-user-achievements) - User's earned achievements
* [Get Achievement Progress](/api-reference/achievements/get-progress) - Progress toward achievement
* [Claim Achievement](/api-reference/achievements/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.