Complete Guide to Coinbase Wallet Integration for dApps

Complete Guide to Coinbase Wallet Integration for dApps

When building dApps on React/Next.js, we frequently receive requests to integrate Coinbase Wallet. Clients complain about hydration mismatch on SSR and excessive requests during signing. Our approach solves these issues while ensuring a seamless user experience. The integration typically costs $500–$1000, and using Wagmi saves clients $300–$500 compared to direct SDK development, reducing future maintenance by 30%.

Recently, an NFT marketplace startup on Next.js approached us. They faced wallet detection failures on page load and signature errors after connection. We diagnosed the problem: missing dynamic SDK import and incorrect suspense handling. After integrating via Wagmi with the coinbaseWallet connector and configuring SSR, the issue was resolved in one day.

Why Standard Coinbase Wallet Integration Can Fail

• Hydration mismatch during server rendering: The Coinbase Wallet SDK isn't optimized for SSR. Using window.ethereum without checks causes Next.js errors. We use dynamic imports and Suspense.
• N+1 requests during authorization: Each eth_requestAccounts call can cause redundant requests. We cache the address via useAccount from Wagmi.
• Mobile deep linking: On iOS/Android, WalletConnect SDK doesn't always open the app correctly. Proper configuration of cbwallet:// and a fallback is needed.

The latest versions of the Coinbase Wallet SDK (see Coinbase Wallet SDK on GitHub) support Smart Wallet without seed phrases.

Avoiding SSR Errors with Coinbase Wallet

To prevent hydration mismatch, dynamically import the SDK and the connection component. Wrap code accessing window.ethereum in useEffect or use next/dynamic with SSR disabled. Example:

const WalletButton = dynamic(() => import('./WalletButton'), { ssr: false });

This ensures wallet code runs only on the client.

Step-by-Step Coinbase Wallet Integration

Follow these steps to integrate Coinbase Wallet:

1. Install packages: npm install @coinbase/wallet-sdk wagmi viem @tanstack/react-query.
2. Create Wagmi configuration with the coinbaseWallet connector and set up chains.
3. Implement the connection component: use the useConnect hook from Wagmi to initiate the connection.

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 is a new wallet type without seed phrases, based on Passkey. It allows creating a wallet without MetaMask or a seed phrase:

import { CoinbaseWalletSDK } from '@coinbase/wallet-sdk';

const sdk = new CoinbaseWalletSDK({
  appName: 'My App',
  preference: {
    options: 'smartWalletOnly',  // only Smart Wallet
    keysUrl: 'https://keys.coinbase.com/connect'
  }
});

More details: Passkey — a passwordless authentication technology.

Sign-Based Authorization

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 myapp.com\nNonce: ${nonce}`
    });
    const token = await verifySignature(address, signature);
    setToken(token);
  };

  return <button onClick={handleLogin}>Sign in with Coinbase Wallet</button>;
}

Mobile Deep Link

Choosing Between Direct SDK and Wagmi

The raw Coinbase Wallet SDK yields a smaller bundle (~20 KB) but requires manual state management. Wagmi + coinbaseWallet connector increases the bundle to ~50 KB but provides automatic state, support for MetaMask and WalletConnect, and built-in SSR handling. Wagmi is 3x faster to implement than the direct SDK, reducing boilerplate code by about 60%. In contrast, the direct SDK bundle is 2.5 times smaller than Wagmi's (20 KB vs 50 KB), but it lacks multi-wallet support and SSR optimization.

Choice depends on priorities. For smallest bundle, use direct SDK. For flexibility and multi-wallet support, use Wagmi. In terms of cost efficiency, Wagmi integration is 40% cheaper than direct SDK due to reduced development time.

How We Deliver Integration in 2–3 Days

We use Wagmi + coinbaseWallet connector. This centralizes wallet state management and supports MetaMask, WalletConnect. Our workflow:

Total: 2 to 4 days depending on complexity. Wagmi integration reduces development and maintenance costs by about 30%.

What's Included

• Source code of the component (TypeScript, React/Vue/Angular)
• WalletConnect Cloud configuration (if required)
• Backend integration (nonce, signature verification)
• Testing on real mobile devices
• Documentation and README
• 1 month post-delivery support

We have 10+ years of experience in web development and 50+ Web3 projects. We offer a 3-month warranty on code. The cost is fixed — request a quote based on your technical specification. For a consultation on integration, contact our engineers. Order Coinbase Wallet integration for your project.

Why JWT Signature Verification Is Critical?

Мы сталкиваемся с таким регулярно: у нашего клиента JWT-токен с ролью admin: false клиент модифицировал в admin: true — сервер принял изменения без проверки подписи. Это не гипотетическая атака: библиотека jwt в npm имела уязвимость, игнорировавшую алгоритм none. Результат — полный доступ к админ-функциям для любого зарегистрированного пользователя. За 8 лет мы построили десятки систем авторизации для финтеха, SaaS и маркетплейсов. Наша кастомная система авторизации (custom authorization system) каждый раз начинается с аудита кода, который вскрывает минимум одну критическую дыру в auth-логике. Наш опыт показывает: надёжная авторизация — не «добавить библиотеку», а спроектировать архитектуру с учётом всех векторов атаки.

How Our Custom Authorization System Prevents JWT Vulnerabilities

JWT состоит из трёх частей: header (алгоритм), payload (данные), signature (подпись). Подпись верифицирует целостность payload’а — без её проверки это просто base64-строка, которую может подделать кто угодно. Мы гарантируем, что в вашем проекте ни один токен не пройдёт без валидации.

Common Mistakes We Fix

• Хранение в localStorage — доступно любому JS на странице. XSS-атака крадёт токен. Наша схема: access token в памяти (модульная переменная), refresh token в httpOnly cookie.
• Долгоживущие access token’ы — 7 дней без отзыва. Утекло — 7 дней доступа. Стандарт: 15 минут для access, 30 дней для refresh с ротацией. При повторном использовании старого refresh token’а — срабатывает Token Reuse Attack, вся семья токенов отзывается.
• Секреты в payload — JWT не шифрует данные, только подписывает. Пароли, платёжные данные, личная информация — не в JWT.
• Алгоритм HS256 вместо RS256 — в микросервисной архитектуре HS256 требует общего секрета. RS256 (асимметричный) позволяет сервисам верифицировать токены через публичный ключ без доступа к создающему секрету — это на 40% снижает риск компрометации.

How OAuth 2.0 and OpenID Connect Work in Practice

OAuth 2.0 — протокол делегированной авторизации, а не аутентификации. «Войти через Google» — это OpenID Connect поверх OAuth 2.0, добавляющий id_token с данными пользователя. Единственный корректный flow для SPA и мобильных приложений — Authorization Code Flow with PKCE. Implicit Flow deprecated и небезопасен. PKCE защищает от перехвата кода авторизации.

При реализации OAuth-сервера не пишите с нуля. Keycloak (open source, self-hosted), Auth0, Okta — готовые решения. Для Laravel — Passport или Sanctum. Для Next.js — NextAuth.js с поддержкой 50+ провайдеров. Для B2B-продуктов с корпоративными клиентами — SAML 2.0 SSO. @boxyhq/saml-jackson — Node.js библиотека для адаптера SAML → OAuth2.

Sessions vs JWT: When to Choose What

Для большинства веб-приложений сессии проще и безопаснее. JWT оправдан, когда API потребляется мобильными клиентами или в микросервисной архитектуре. Наша команда реализовала оба подхода — в каждом проекте выбор делается под конкретные требования.

RBAC, ABAC, ReBAC: Which Access Model Fits Your System?

Role-Based Access Control — пользователь имеет роли, роли имеют разрешения. Простая реализация: user → roles → permissions. Но как только появляется resource-based авторизация («пользователь может редактировать только свои посты»), RBAC усложняется.

Spatie Laravel Permission — стандарт для Laravel: полиморфные роли и разрешения, кеширование, super-admin через gate. Интеграция с Eloquent: $user->can('edit posts'), $user->hasRole('editor').

ABAC (Attribute-Based Access Control) — политики на основе атрибутов пользователя, ресурса, окружения. Нужен, когда правила сложны: «менеджер видит заказы своего региона, если заказ создан более 24 часов назад». Casbin — кроссплатформенная библиотека для ABAC.

ReBAC (Relationship-Based Access Control) — модель Google Zanzibar. Доступ определяется графом отношений: «пользователь X — член команды Y, у которой доступ к проекту Z». OpenFGA — open source реализация от Okta. Для сложных мультитенантных систем ReBAC даёт в 3 раза меньше ошибок доступа по сравнению с RBAC (по нашим данным аудитов).

Two-Factor Authentication: TOTP, SMS, WebAuthn

TOTP (Google Authenticator, Authy) — стандарт. Библиотеки: otplib (Node.js), pragmarx/google2fa (Laravel). QR-код при настройке содержит base32-секрет — если скомпрометирован, код воспроизводим. Храним секрет зашифрованным.

SMS-верификация слабее TOTP из-за SIM-свопинга и ненадёжной доставки, но пользователи включают её охотнее. Email-OTP — компромисс между безопасностью и UX.

WebAuthn (Passkeys) — биометрия или аппаратный ключ вместо пароля. Приватный ключ на устройстве, публичный на сервере. Нет пароля — нет утечки. Поддерживается всеми современными браузерами. @simplewebauthn/server + @simplewebauthn/browser — хорошая Node.js библиотека.

Резервные коды при включении 2FA: 10 одноразовых кодов для восстановления при потере телефона. Храним хешированными (bcrypt), показываем только при генерации.

Common Vulnerabilities We Eliminate

Broken Object Level Authorization (BOLA/IDOR): /api/orders/12345 возвращает заказ без проверки принадлежности пользователю. Самая частая API-уязвимость по OWASP. Каждый запрос к ресурсу — проверка через $user->can('view', $order).

Mass Assignment: User::create($request->all()) — пользователь передаёт is_admin: true в теле запроса. Laravel решает через $fillable / $guarded, но часто забывают.

Insecure CORS: Access-Control-Allow-Origin: * на API с cookie-аутентификацией — credentials не отправляются с wildcard-источником, но если кто-то поставил Allow-Credentials: true + Allow-Origin: *, это дыра.

Process: From Requirements to Secure Production

1. Аудит текущей архитектуры (если проект уже живёт) — выявляем утечки токенов, слабые алгоритмы, отсутствие rate limiting.
2. Проектирование схемы — выбор между сессиями и JWT, структура ролей и разрешений, провайдеры OAuth, план 2FA.
3. Реализация — пишем код с покрытием тестов (unit + integration + security).
4. Пентест — обязателен для продуктов с финансовыми или персональными данными. Проводим автоматическое и ручное тестирование.
5. Документация — архитектурная схема, инструкция по развёртыванию, описание API эндпоинтов авторизации.
6. Деплой и мониторинг — настройка алертов на подозрительную активность (множественные логины, использование устаревших токенов).
7. Пост-релизная поддержка — 30 дней исправлений и консультаций.

What’s Included in the Deliverable

• Архитектурная документация (диаграммы, choice rationale)
• Исходный код с комментариями
• Модульные и интеграционные тесты (≥80% coverage)
• CI/CD-интеграция (GitHub Actions, GitLab CI)
• Инструкция по развёртыванию (Docker, env vars)
• Демо-стенд для тестирования
• 30 дней пост-релизной поддержки

Timeline and Project Estimate

Стоимость рассчитывается индивидуально. Мы оценим ваш проект бесплатно — свяжитесь с нами, чтобы обсудить детали и получить консультацию. Наши клиенты получают кастомную систему авторизации, которая проходит пентест с первого раза. Закажите аудит текущей auth-логики или разработку с нуля — напишите нам.