Skip to main content
POST
Claim Achievement

Overview

Claim an achievement that has been earned by a user. This endpoint verifies that the user has met all requirements, mints the achievement NFT (if applicable), and awards points and score bonuses.
Use this endpoint to allow users to claim their earned achievements and receive their rewards. Always verify the user has earned the achievement before calling this endpoint.

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 to claim

Request Body

object
Proof of achievement completion
string
Cryptographic signature proving ownership of the identity
object
Additional metadata for the claim

Response

boolean
Indicates if the claim was successful
string
Success message
string
Resolved wallet address
string
ZKS ID if available, null otherwise
object
Claimed achievement details
object
Rewards received from claiming
number
User’s total points after claiming
number
User’s total ZKScore after claiming
boolean
Whether the achievement was successfully claimed
boolean
Whether this is a special achievement worth celebrating
string
ISO 8601 timestamp of the claim

Examples

Response Example

Use Cases

1. Achievement Claiming Flow

Complete achievement claiming process:

2. Batch Achievement Claims

Claim multiple achievements at once:

3. Achievement Verification

Verify achievement before claiming:

4. Celebration System

Show achievement celebrations:

5. NFT Integration

Handle NFT minting for achievements:

Best Practices

1. Verify Before Claiming

Always verify the user has earned the achievement:

2. Handle Errors Gracefully

Implement proper error handling:

3. Batch Processing

Process multiple claims efficiently:

4. Progress Tracking

Track claim progress:

Troubleshooting

”Achievement not earned”

Cause: User hasn’t met the requirements for the achievement. Solution:
  • Check the achievement requirements
  • Verify the user’s progress
  • Wait for the user to complete the requirements

”Achievement already claimed”

Cause: User has already claimed this achievement. Solution:
  • Check if the achievement is already in the user’s collection
  • Don’t attempt to claim the same achievement twice

”Invalid signature”

Cause: The signature doesn’t match the user’s identity. Solution:
  • Verify the signature is from the correct wallet
  • Check that the message was signed correctly
  • Ensure the user is signing with the right account

”Proof verification failed”

Cause: The proof doesn’t meet the achievement requirements. Solution:
  • Verify all requirements are met
  • Check that the proof data is accurate
  • Ensure the timestamp is recent

Rate Limits

Achievement claim requests are subject to rate limits:
  • Free tier: 10 claims per minute
  • Starter tier: 50 claims per minute
  • Professional tier: 200 claims per minute
  • Enterprise tier: Custom limits
Implement queuing for batch claims to avoid rate limits.