Інтеграція з Zealy (quest-платформа)

Інтеграція з Zealy (quest-платформа)

Zealy (бувший Crew3) — quest-платформа для Web3 спільнот. Основний сценарій інтеграції: ваш dApp або бекенд верифікує виконання кастомних завдань через Zealy API, або читає дані про користувачів та їхній XP для реалізації on-chain наград.

Zealy API: що доступно

Zealy надає REST API з ключем авторизації з настроєк спільноти:

Authorization: Basic <base64(apiKey:)>

Ключові endpoints:

• GET /communities/{subdomain}/users — список учасників з XP
• GET /communities/{subdomain}/users/{userId} — дані конкретного користувача
• GET /communities/{subdomain}/leaderboard — лідерборд
• POST /communities/{subdomain}/users/{userId}/complete-quest — програмне завершення кастомного квеста

Чтение даних користувачів

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;
}

Користувачі привʼязуютъь гаманець у Zealy профілі — пошук відбувається через ethAddress для on-chain інтеграції.

Кастомні квести з API-верифікацією

Найкорисніший кейс: квест «Сделай swap на нашому DEX» або «Вызови наш контракт». Zealy підтримує API-quests — ви пишете endpoint, який Zealy дергає для верифікації.

Настройка в Zealy: добавляє API quest, вказує URL вашого верифікаційного endpoint'у. Zealy відправляє POST запит при спробі завершити квест.

// Ваш верифікаційний endpoint
app.post('/zealy/verify/swap', async (req, reply) => {
  const { userId, reviewedAt } = req.body;
  
  // Отримуємо гаманець користувача з Zealy
  const user = await getZealyUser(userId);
  if (!user?.ethAddress) {
    return reply.send({ success: false, message: 'Wallet not connected in Zealy' });
  }
  
  // Перевіряємо on-chain: робив ли адрес swap за останні 7 днів
  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'
  });
});

Важливо: Zealy не надає signature для верифікації вхідного запиту (на момент написання). Додатково захистіть endpoint через secret token у заголовку, який ви задаєте при настройці квеста.

Програмне начисдення XP

Після on-chain події (mint, swap, стейкинг) можна автоматично завершати квест для користувача:

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;
}

Типовий flow: слухаємо on-chain події → знаходимо userId по wallet через Zealy API → викликаємо complete-quest.

Графік розробки

Чтение лідерборда + XP для конкретного користувача — кілька годин. Полноцінна інтеграція з кастомними верифіцюємими квестами та on-chain перевірками — 1 робочий день.