Overview

The Quest API provides access to quest information, user eligibility verification, and quest metadata.

Core Queries

Get Quest Details

query GetQuest($id: ID!) {
  quest(id: $id) {
    id
    name
    type
    status
    description
    startTime
    endTime
    cap
    participantsCount
    loyaltyPoints
    gasType
    space {
      id
      name
    }
    chain
  }
}

List Space Quests

query GetSpaceQuests($input: ListQuestInput!) {
  quests(input: $input) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    list {
      id
      name
      type
      status
      participantsCount
      loyaltyPoints
      startTime
      endTime
    }
  }
}

Variables:

{
  "input": {
    "spaceId": "40",
    "statuses": ["Active", "NotStarted"],
    "types": ["Drop", "Points"],
    "first": 20
  }
}

Check User Eligibility

query CheckQuestEligibility($questId: ID!, $address: String!) {
  quest(id: $questId) {
    id
    name
    status
    credentialGroups(address: $address) {
      id
      name
      conditionRelation
      conditions {
        expression
        eligible
      }
      rewards {
        expression
        eligible
        rewardType
        rewardCount
      }
    }
  }
}

When all conditions.eligible are true, the user meets quest requirements.

Field Reference

Quest Status

StatusDescription
DraftQuest in development, not visible
ActiveQuest is live and accepting participants
NotStartedQuest scheduled but not started
ExpiredQuest period has ended
CapReachedMaximum participants reached
DeletedQuest has been removed

Quest Types

TypeDescription
DropStandard quest with rewards
MysteryBoxRandom reward quest
AirdropToken distribution quest
PointsLoyalty points reward
ExternalLinkExternal website integration

Gas Types

TypeDescription
GasUser pays gas fees
GaslessGalxe covers gas fees

Key Fields

FieldTypeDescription
idID!Quest’s unique hash ID
nameString!Quest display name
statusQuestStatus!Current quest status
participantsCountInt!Number of participants
loyaltyPointsInt!Points awarded for completion
credentialGroups(address)[CredentialGroup]User-specific eligibility data

Integration Patterns

Basic Quest Validation

curl -X POST https://graphigo-business.prd.galaxy.eco/query \
  -H "Content-Type: application/json" \
  -H "access-token: YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "query GetQuest($id: ID!) { quest(id: $id) { name status participantsCount cap loyaltyPoints } }",
    "variables": { "id": "GChdWUjXX3" }
  }'

Quest Status Validation

Check these conditions before allowing participation:

  1. status must be "Active"
  2. participantsCount must be less than cap (if cap > 0)
  3. Current time must be between startTime and endTime

User Eligibility Flow

  1. Call credentialGroups(address: $userAddress)
  2. Check each group’s conditions.eligible values
  3. If conditionRelation is "ALL", all conditions must be true
  4. If conditionRelation is "ANY", at least one condition must be true

Best Practices

  1. Status Validation: Always check quest status before showing participation UI
  2. Capacity Check: Verify participantsCount < cap for available spots
  3. Time Validation: Ensure current time is within quest period
  4. Error Handling: Handle quest not found and permission errors
  5. Caching: Cache quest details for 1-5 minutes to reduce API calls

Common Errors

ErrorCauseSolution
Quest not foundInvalid quest IDVerify quest ID exists
Quest is privateNo access permissionsCheck quest permissions
Rate limit exceededToo many requestsImplement retry logic
Invalid status filterWrong enum valueUse valid status values

Next Steps