Інтеграція WalletConnect для підключення криптогаманця до сайту

Інтеграція WalletConnect для підключення криптогаманця до сайту

Ви розробили dApp і зіткнулися з проблемою: користувачі не можуть залогінитися з мобільного гаманця. Браузерні розширення на кшталт MetaMask не працюють на телефонах, а вбудовувати кожен гаманець окремо — безкінечна головна біль. Ми вирішуємо це завдання через WalletConnect — відкритий протокол, який за пару днів дає підключення 400+ гаманців через QR-код або deep link. Нижче — як ми це робимо, з кодом і реальними конфігами. Якщо ви шукаєте готове рішення для Web3-аутентифікації — зв'яжіться з нами: ми реалізуємо інтеграцію з урахуванням ваших вимог.

Чому WalletConnect v2, а не v1?

WalletConnect v2 (через Reown AppKit) повністю замінив першу версію. Він швидший: встановлення з'єднання займає менше секунди проти кількох у v1. Підтримує мультичейн: можна підключитися одночасно до Ethereum, Polygon і Arbitrum (до 5 мереж). І головне — вбудована авторизація через підпис повідомлення (EIP-712). V1 більше не підтримується і не рекомендований для нових проєктів.

Як працює підключення гаманця?

Процес виглядає так:

1. Користувач натискає «Підключити гаманець».
2. Генерується сесія WalletConnect, відображається QR-код або deep link.
3. Гаманець користувача сканує QR, підписує запит на з'єднання.
4. dApp отримує адресу гаманця і може запитувати підписи транзакцій.

Для авторизації ми додатково запитуємо підпис повідомлення (Sign-in with Ethereum): користувач підписує nonce, сервер перевіряє підпис і видає JWT-токен. Жодних паролів.

Як забезпечується безпека авторизації?

WalletConnect Protocol використовує наскрізне шифрування і не зберігає приватні ключі на сервері.

Авторизація через підпис nonce захищає від повторних атак. Nonce генерується сервером, має короткий термін життя (зазвичай 5 хвилин) і анулюється після використання. Додатково можна налаштувати CORS-обмеження на стороні API.

Реалізація на React + Wagmi (AppKit)

Встановлюємо пакети:

npm install @reown/appkit @reown/appkit-adapter-wagmi wagmi [email protected] @tanstack/react-query 

Реєструємо проєкт на Reown Cloud (безкоштовний план — до 50 000 активних користувачів на місяць). Отримуємо projectId.

Код підключення:

import { createAppKit } from '@reown/appkit/react';
import { WagmiProvider } from 'wagmi';
import { mainnet, polygon, arbitrum } from '@reown/appkit/networks';
import { WagmiAdapter } from '@reown/appkit-adapter-wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();
const projectId = process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID;
const networks = [mainnet, polygon, arbitrum];
const wagmiAdapter = new WagmiAdapter({ networks, projectId });

createAppKit({
  adapters: [wagmiAdapter],
  networks,
  projectId,
  metadata: {
    name: 'My App',
    description: 'My Web3 Application',
    url: 'https://example.com',
    icons: ['https://example.com/icon.png']
  },
  features: {
    analytics: false,
    email: false,
    socials: false
  }
});

function App() {
  return (
    <WagmiProvider config={wagmiAdapter.wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <YourApp />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Кнопка підключення та авторизація

import { useAppKit, useAppKitAccount } from '@reown/appkit/react';
import { useSignMessage } from 'wagmi';

function ConnectButton() {
  const { open } = useAppKit();
  const { address, isConnected } = useAppKitAccount();
  const { signMessageAsync } = useSignMessage();

  const handleLogin = async () => {
    if (!isConnected) {
      await open();
      return;
    }

    // Авторизація через підпис
    const nonce = await fetch(`/api/auth/nonce?address=${address}`)
      .then(r => r.json())
      .then(d => d.nonce);

    const message = `Авторизація на example.com\nNonce: ${nonce}`;
    const signature = await signMessageAsync({ message });

    const { token } = await fetch('/api/auth/web3', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ address, signature, message })
    }).then(r => r.json());

    setAuthToken(token);
  };

  return (
    <button onClick={handleLogin}>
      {isConnected ? `Увійти як ${address?.slice(0, 6)}...` : 'Підключити гаманець'}
    </button>
  );
}

Налаштування deep link для мобільних гаманців

Deep link дозволяє відкривати гаманець безпосередньо з сайту на мобільному пристрої, минаючи QR-код. Налаштовуємо universal link для iOS та intent для Android. В Reown Cloud вмикаємо deep link у налаштуваннях проєкту та вказуємо підтримувані схеми (наприклад, wc:). Для коректної роботи на Android потрібна обробка intent через WalletConnectBridge.

Обробка помилок з'єднання

Важно обробляти помилки: відмова користувача, таймаут, непідтримувана мережа. Wagmi AppKit надає хуки useWalletInfo та useConnectionError. Ми додаємо fallback: якщо підключення не вдалося, пропонуємо вибір використати браузерне розширення. Також логуємо події для налагодження.

Project ID

WalletConnect v2 вимагає реєстрації проєкту на Reown Cloud для отримання projectId. Безкоштовний план: до 50 000 активних користувачів/місяць. Цього достатньо для більшості стартапів. Якщо потрібен великий обсяг, передбачені платні тарифи.

Підтримувані гаманці

WalletConnect працює з MetaMask Mobile, Trust Wallet, Rainbow, Coinbase Wallet, Ledger Live, Argent, Safe та сотнями інших. Для мобільних — QR-код або universal link.

Порівняння планів Reown Cloud

Що входить в роботу?

• Реєстрація проєкту та налаштування API-ключів.
• Розробка компонента підключення гаманця (кнопка, модалка, обробка станів).
• Реалізація авторизації через підпис повідомлення (Sign-in with Ethereum).
• Підтримка мультичейну (до 5 мереж).
• Документація з інтеграції та інструкція для користувача.
• Гарантія сумісності з основними гаманцями.

Строки

Базова інтеграція WalletConnect з авторизацією — 3–5 днів. Якщо потрібна кастомна модалка, підтримка deep link або реферальні посилання — до 2 тижнів. Оцінимо ваш проєкт — зв'яжіться, щоб обговорити деталі.

Отримайте консультацію з інтеграції WalletConnect — обговоримо ваш проєкт і запропонуємо оптимальний план. Замовте інтеграцію під ключ з гарантією сумісності: наші інженери з багаторічним досвідом у блокчейні реалізують все швидко та безпечно.