API Reference
Quest API Reference
Query quest information and check user eligibility for quest requirements
Overview
The Quest API provides access to quest information, user eligibility verification, and quest metadata.
Core Queries
Get Quest Details
List Space Quests
Variables:
Check User Eligibility
When all conditions.eligible
are true
, the user meets quest requirements.
Field Reference
Quest Status
Status | Description |
---|---|
Draft | Quest in development, not visible |
Active | Quest is live and accepting participants |
NotStarted | Quest scheduled but not started |
Expired | Quest period has ended |
CapReached | Maximum participants reached |
Deleted | Quest has been removed |
Quest Types
Type | Description |
---|---|
Drop | Standard quest with rewards |
MysteryBox | Random reward quest |
Airdrop | Token distribution quest |
Points | Loyalty points reward |
ExternalLink | External website integration |
Gas Types
Type | Description |
---|---|
Gas | User pays gas fees |
Gasless | Galxe covers gas fees |
Key Fields
Field | Type | Description |
---|---|---|
id | ID! | Quest’s unique hash ID |
name | String! | Quest display name |
status | QuestStatus! | Current quest status |
participantsCount | Int! | Number of participants |
loyaltyPoints | Int! | Points awarded for completion |
credentialGroups(address) | [CredentialGroup] | User-specific eligibility data |
Integration Patterns
Basic Quest Validation
Quest Status Validation
Check these conditions before allowing participation:
status
must be"Active"
participantsCount
must be less thancap
(if cap > 0)- Current time must be between
startTime
andendTime
User Eligibility Flow
- Call
credentialGroups(address: $userAddress)
- Check each group’s
conditions.eligible
values - If
conditionRelation
is"ALL"
, all conditions must betrue
- If
conditionRelation
is"ANY"
, at least one condition must betrue
Best Practices
- Status Validation: Always check quest status before showing participation UI
- Capacity Check: Verify
participantsCount < cap
for available spots - Time Validation: Ensure current time is within quest period
- Error Handling: Handle quest not found and permission errors
- Caching: Cache quest details for 1-5 minutes to reduce API calls
Common Errors
Error | Cause | Solution |
---|---|---|
Quest not found | Invalid quest ID | Verify quest ID exists |
Quest is private | No access permissions | Check quest permissions |
Rate limit exceeded | Too many requests | Implement retry logic |
Invalid status filter | Wrong enum value | Use valid status values |
Next Steps
- Quest Integration Guide - Complete implementation patterns
- Credential API Reference - User verification
- Authentication - Access token setup