Base Account Connection Guide

Use the JavaScript SDK to support Base Account through one of these routes:

A popup or QR code at keys.coinbase.com on web, surfacing both Coinbase Smart Wallet (passkey-backed ERC-4337) and Coinbase Wallet (EOA).
A Mobile Wallet Protocol deep link into the Coinbase Wallet app on React Native, surfacing Coinbase Smart Wallet.

The Coinbase Wallet browser extension is handled separately by the standard EIP-6963 and window-injected extensions. See Base Account extension for the full extension options.

Prerequisites

Create and initialize a Dynamic client.
Enable EVM in the Dynamic developer console.
Install @dynamic-labs-sdk/evm.
On React Native, complete React Native setup first.

Add the extension

import { addEvmExtension } from '@dynamic-labs-sdk/evm';
import { addBaseAccountEvmExtension } from '@dynamic-labs-sdk/evm/base-account';

addEvmExtension();
addBaseAccountEvmExtension();

Keep addEvmExtension so the Coinbase Wallet browser extension is still discovered through EIP-6963. Pass preference.options to control which Base Account flavors appear in the web popup ('all' by default). On React Native the preference is ignored: Mobile Wallet Protocol always targets Coinbase Smart Wallet.

Connect a wallet

Base Account registers as a wallet SDK provider, so connect through the generic wallet provider lifecycle: find its provider key with getAvailableWalletProvidersData, then call connectAndVerifyWithWalletProvider.

import {
  connectAndVerifyWithWalletProvider,
  getAvailableWalletProvidersData,
} from '@dynamic-labs-sdk/client';

const baseAccountProvider = getAvailableWalletProvidersData(
  dynamicClient,
).find((provider) => provider.metadata.displayName === 'Base Account');

if (baseAccountProvider) {
  const walletAccount = await connectAndVerifyWithWalletProvider({
    walletProviderKey: baseAccountProvider.key,
  });

  console.log(walletAccount.address);
}

On web this opens the keys.coinbase.com popup or a QR code. On React Native it deep-links the user into the Coinbase Wallet app and returns to your app through your deep link scheme.

React Native

The native build of @dynamic-labs-sdk/evm/base-account talks to the Coinbase Wallet app through @mobile-wallet-protocol/client. Two things are required that web does not need: the Mobile Wallet Protocol packages installed, and metadata.nativeLink on the client. This section assumes the app from the React Native quickstart.

Install the peer dependencies

@mobile-wallet-protocol/client is an optional peer of @dynamic-labs-sdk/evm, so install it (and its own Expo peers) in your app:

npm install @mobile-wallet-protocol/client expo expo-web-browser @react-native-async-storage/async-storage

If it is missing when the extension connects, the SDK throws BaseAccountMissingMobileWalletProtocolError.

@mobile-wallet-protocol/client depends on Expo modules (expo, expo-web-browser). On bare React Native you must install Expo modules before using Base Account. See Setup on Bare React Native.

Configure the native link

The Coinbase Wallet app returns the user to your app through your app’s custom URL scheme after it approves a request. Set metadata.nativeLink on the client to the same scheme you registered in app.json, Info.plist, and AndroidManifest.xml:

import { createDynamicClient } from '@dynamic-labs-sdk/client';

const dynamicClient = createDynamicClient({
  environmentId: 'YOUR_ENVIRONMENT_ID',
  metadata: {
    name: 'Your App',
    nativeLink: 'myapp://',
  },
});

Without nativeLink, addBaseAccountEvmExtension throws BaseAccountMissingNativeLinkError at registration time.

Handle the deep link return with expo-router

On Expo Router apps, the Mobile Wallet Protocol callback URL (myapp://mobile-wallet-protocol) arrives as a deep link. Expo Router resolves unknown URLs against your route table, so intercept it in +native-intent.ts before it reaches the unmatched-route screen:

+native-intent.ts

const MOBILE_WALLET_PROTOCOL_PATH = 'mobile-wallet-protocol';

export function redirectSystemPath({ path }: { path: string }): string {
  if (path.startsWith(`/${MOBILE_WALLET_PROTOCOL_PATH}`)) {
    return '';
  }
  try {
    const url = new URL(path);
    const isProtocolHost = url.hostname === MOBILE_WALLET_PROTOCOL_PATH;
    const isProtocolPath =
      url.pathname.replace(/^\/+/, '') === MOBILE_WALLET_PROTOCOL_PATH;
    if (isProtocolHost || isProtocolPath) {
      return '';
    }
  } catch {
    // Not an absolute URL, so this is a normal in-app route.
  }
  return path;
}

Returning '' tells Expo Router to stay on the current screen. The hostname check covers the iOS callback form where the scheme yields a double slash (myapp:////mobile-wallet-protocol), which parses the path into the hostname.

Common pitfalls

Connection opens but never returns to the app

The scheme in metadata.nativeLink must match the scheme registered in app.json ("scheme": "myapp") or in the native Info.plist / AndroidManifest.xml. A mismatch leaves the user in the Coinbase Wallet app after approval.

The unmatched-route screen appears after approving in Coinbase Wallet

On Expo Router, add the redirectSystemPath guard shown above. Without it, the mobile-wallet-protocol callback URL is treated as an app route.

The app bundle cannot resolve the Mobile Wallet Protocol peer

The optional peer is not installed in the app (or Metro’s bundle predates the install). Install @mobile-wallet-protocol/client and rebuild the bundle.

Learn

Implement

Base Account Connection Guide

Prerequisites

Add the extension

Connect a wallet

React Native

Install the peer dependencies

Configure the native link

Handle the deep link return with expo-router

Common pitfalls

Connection opens but never returns to the app

The unmatched-route screen appears after approving in Coinbase Wallet

The app bundle cannot resolve the Mobile Wallet Protocol peer

​Prerequisites

​Add the extension

​Connect a wallet

​React Native

​Install the peer dependencies

​Configure the native link

​Handle the deep link return with expo-router

​Common pitfalls

​Connection opens but never returns to the app

​The unmatched-route screen appears after approving in Coinbase Wallet

​The app bundle cannot resolve the Mobile Wallet Protocol peer

Prerequisites

Add the extension

Connect a wallet

React Native

Install the peer dependencies

Configure the native link

Handle the deep link return with expo-router

Common pitfalls

Connection opens but never returns to the app

The unmatched-route screen appears after approving in Coinbase Wallet

The app bundle cannot resolve the Mobile Wallet Protocol peer