Zealy quest platform integration

Zealy Integration (Quest Platform)

Zealy (formerly Crew3) is a quest platform for Web3 communities. The main integration scenario: your dApp or backend verifies completion of custom tasks via Zealy API, or reads user data and XP to implement on-chain rewards.

Zealy API: What's Available

Zealy provides REST API with authorization key from community settings:

Authorization: Basic <base64(apiKey:)>

Key endpoints:

• GET /communities/{subdomain}/users — list of members with XP
• GET /communities/{subdomain}/users/{userId} — specific user data
• GET /communities/{subdomain}/leaderboard — leaderboard
• POST /communities/{subdomain}/users/{userId}/complete-quest — programmatic quest completion

Reading User Data

const ZEALY_API = 'https://api.zealy.io/communities';

async function getUserByWallet(subdomain: string, walletAddress: string) {
  const response = await fetch(
    `${ZEALY_API}/${subdomain}/users?ethAddress=${walletAddress.toLowerCase()}`,
    {
      headers: {
        'Authorization': `Basic ${Buffer.from(process.env.ZEALY_API_KEY + ':').toString('base64')}`,
      }
    }
  );
  
  if (!response.ok) throw new Error(`Zealy API error: ${response.status}`);
  const data = await response.json();
  return data.data?.[0] ?? null;
}

Users link wallet in Zealy profile — search happens via ethAddress for on-chain integration.

Custom Quests with API Verification

The most useful case: quest "Do swap on our DEX" or "Call our contract". Zealy supports API-quests — you write an endpoint that Zealy calls for verification.

Setup in Zealy: add API quest, specify URL of your verification endpoint. Zealy sends POST request on quest completion attempt.

// Your verification endpoint
app.post('/zealy/verify/swap', async (req, reply) => {
  const { userId, reviewedAt } = req.body;
  
  // Get user wallet from Zealy
  const user = await getZealyUser(userId);
  if (!user?.ethAddress) {
    return reply.send({ success: false, message: 'Wallet not connected in Zealy' });
  }
  
  // Check on-chain: did address do swap in last 7 days
  const hasSwapped = await checkSwapOnChain(user.ethAddress, Date.now() - 7 * 24 * 3600 * 1000);
  
  return reply.send({
    success: hasSwapped,
    message: hasSwapped ? 'Swap verified' : 'No swap found for this wallet'
  });
});

Important: Zealy doesn't provide signature for incoming request verification (at the time of writing). Additionally protect the endpoint via secret token in header that you set when configuring the quest.

Programmatic XP Assignment

After on-chain event (mint, swap, staking) you can automatically complete the quest for the user:

async function completeQuestForUser(
  subdomain: string,
  userId: string,
  questId: string
) {
  const response = await fetch(
    `${ZEALY_API}/${subdomain}/users/${userId}/complete-quest`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${Buffer.from(process.env.ZEALY_API_KEY + ':').toString('base64')}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ questId }),
    }
  );
  
  return response.ok;
}

Typical flow: listen to on-chain events → find userId by wallet via Zealy API → call complete-quest.

Development Timeline

Reading leaderboard + XP for specific user — several hours. Full integration with custom verifiable quests and on-chain checks — 1 business day.