Интеграция Coinbase Wallet для подключения к сайту
При разработке dApp на React/Next.js мы регулярно сталкиваемся с запросами на внедрение Coinbase Wallet. Клиенты жалуются на hydration mismatch при SSR и избыточные запросы при подписи. Разработанный нами подход решает эти проблемы и обеспечивает бесшовный пользовательский опыт.
Недавно к нам обратился стартап с dApp для NFT-маркетплейса на Next.js. Они столкнулись с тем, что при загрузке страницы кошелёк не определялся, а после подключения возникали ошибки подписи. Мы диагностировали проблему — отсутствие динамического импорта SDK и неправильная обработка саспенса. После интеграции через Wagmi с coinbaseWallet connector и настройки серверного рендеринга проблема была решена за один день.
Почему стандартная интеграция Coinbase Wallet может подвести?
-
Hydration mismatch при рендеринге на сервере: Coinbase Wallet SDK не оптимизирован для SSR. Если использовать
window.ethereumбез проверки, Next.js выдаёт ошибки. Мы используем динамический импорт и Suspense. -
N+1 запросы при авторизации: каждый вызов
eth_requestAccountsможет приводить к избыточным запросам. Мы кешируем адрес черезuseAccountиз Wagmi. -
Mobile deep linking: на iOS/Android WalletConnect SDK не всегда корректно открывает приложение. Нужна правильная конфигурация
cbwallet://и fallback.
Согласно Coinbase Wallet SDK на GitHub, последние версии поддерживают Smart Wallet без seed-фраз.
Как избежать ошибок SSR при подключении Coinbase Wallet?
Для предотвращения hydration mismatch используйте динамический импорт SDK и компонента подключения. Оберните код, обращающийся к window.ethereum, в useEffect или используйте библиотеку next/dynamic с отключением SSR. Пример:
const WalletButton = dynamic(() => import('./WalletButton'), { ssr: false });
Это гарантирует, что код кошелька выполняется только на клиенте.
Пошаговая настройка интеграции Coinbase Wallet
- Установите пакеты:
npm install @coinbase/wallet-sdk wagmi viem @tanstack/react-query. - Создайте конфигурацию Wagmi с connector
coinbaseWalletи настройте цепочки. - Реализуйте компонент подключения: используйте хук
useConnectиз Wagmi для инициации соединения.
import { createConfig, http } from 'wagmi';
import { mainnet, polygon } from 'wagmi/chains';
import { coinbaseWallet } from 'wagmi/connectors';
export const config = createConfig({
chains: [mainnet, polygon],
connectors: [
coinbaseWallet({ appName: 'My App', preference: 'smartWalletOnly' }),
metaMask(),
walletConnect({ projectId: 'YOUR_PROJECT_ID' })
],
transports: {
[mainnet.id]: http(),
[polygon.id]: http()
}
});
Smart Wallet (Coinbase Wallet v4)
Coinbase Smart Wallet — новый тип кошелька без seed-фразы на основе Passkey. Позволяет создать кошелёк без MetaMask и без seed-фразы:
import { CoinbaseWalletSDK } from '@coinbase/wallet-sdk';
const sdk = new CoinbaseWalletSDK({
appName: 'My App',
preference: {
options: 'smartWalletOnly', // только Smart Wallet
keysUrl: 'https://keys.coinbase.com/connect'
}
});
Подробнее: Passkey — технология аутентификации без паролей.
Авторизация через подпись
import { useConnect, useSignMessage, useAccount } from 'wagmi';
import { coinbaseWallet } from 'wagmi/connectors';
function CoinbaseLogin() {
const { connect } = useConnect();
const { address, isConnected } = useAccount();
const { signMessageAsync } = useSignMessage();
const handleLogin = async () => {
if (!isConnected) {
await connect({ connector: coinbaseWallet({ appName: 'My App' }) });
}
const nonce = await getNonce(address);
const signature = await signMessageAsync({
message: `Login to example.com\nNonce: ${nonce}`
});
const token = await verifySignature(address, signature);
setToken(token);
};
return <button onClick={handleLogin}>Войти через Coinbase Wallet</button>;
}
Mobile Deep Link
Подробнее о настройке Deep Link
На мобильных устройствах WalletConnect SDK автоматически открывает Coinbase Wallet app через deep link: cbwallet://wsegue?uri=.... Для корректной работы необходимо:
- Добавить домен в whitelist WalletConnect Cloud.
- Настроить fallback на браузер, если приложение не установлено.
- Проверить работу на iOS и Android эмуляторах.
Какой способ интеграции выбрать: прямой SDK или Wagmi?
Прямой Coinbase Wallet SDK даёт меньший бандл (~20 KB), но требует ручного управления состоянием. Wagmi + coinbaseWallet connector увеличивает бандл до ~50 KB, но обеспечивает автоматическое состояние, поддержку MetaMask и WalletConnect, а также встроенную обработку SSR. Wagmi сокращает объём boilerplate кода на 60% по сравнению с прямым SDK.
| Параметр | Прямой Coinbase Wallet SDK | Wagmi + connector |
|---|---|---|
| Настройка | Средняя (ручное управление) | Высокая (автоматическое состояние) |
| SSR | Требуется доработка | Встроена через динамический импорт |
| Совместимость | Только Coinbase | Любые Wagmi-кошельки |
| Бандл | ~20 KB | ~50 KB |
Выбор зависит от приоритетов. Если важен малый размер бандла — прямой SDK. Если нужна гибкость и поддержка других кошельков — Wagmi.
Как мы реализуем интеграцию за 2–3 дня?
Мы используем Wagmi + coinbaseWallet connector. Это позволяет централизованно управлять состоянием кошелька и поддерживать MetaMask, WalletConnect. Процесс работы:
| Этап | Детали | Срок |
|---|---|---|
| Анализ и архитектура | Определяем способ интеграции | 0.5 дня |
| Настройка SDK и конфигурация | Установка пакетов, chains, transport | 0.5 дня |
| Реализация подключения и подписи | Компонент, nonce, верификация | 1 день |
| Mobile deep link и тестирование | Проверка на iOS/Android | 0.5 дня |
| Документация и обучение | README, передача кода | 0.5 дня |
Итого: от 2 до 4 дней в зависимости от сложности. Интеграция через Wagmi снижает затраты на разработку и поддержку примерно на 30%.
Что входит в работу
- Исходный код компонента (TypeScript, React/Vue/Angular)
- Настройка WalletConnect Cloud (если требуется)
- Интеграция с бэкендом (nonce, верификация подписи)
- Тестирование на реальных мобильных устройствах
- Документация и README
- Поддержка в течение 1 месяца после сдачи
У нас 10+ лет опыта в веб-разработке и 50+ проектов с Web3. Даём гарантию на код 3 месяца. Стоимость фиксированная — запросите расчёт по вашему ТЗ. Для получения консультации по интеграции свяжитесь с нашими инженерами. Закажите интеграцию Coinbase Wallet в ваш проект.