Интеграция с Zealy (quest-платформа)

Интеграция с Zealy (quest-платформа)

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

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

Zealy предоставляет REST API с ключом авторизации из настроек community:

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 — вы пишете эндпоинт, который Zealy дёргает для верификации.

Настройка в Zealy: добавляете API quest, указываете URL вашего верификационного эндпоинта. 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 рабочий день.