setup-wagmi-metamask-connector

Set Up Wagmi with MetaMask Connect EVM Connector

When to use

• Building a new wagmi-based dApp that needs MetaMask wallet connectivity
• Adding the MetaMask connector to an existing wagmi config
• Need a working wagmi + MetaMask setup with connection, chain switching, signing, and transactions
• Integrating MetaMask via the new @metamask/connect-evm SDK in a wagmi project

Workflow

Step 1: Install Dependencies

npm install wagmi viem @tanstack/react-query

# Check which @metamask/connect-evm range wagmi's connector was built against:
npm info @wagmi/connectors peerDependencies
# ... then install a version inside that range (currently ^1.3.0):
npm install @metamask/connect-evm@"^1.3.0"

The connect-evm-backed metaMask() connector ships in wagmi >= 3.6 / @wagmi/connectors >= 8, which declares @metamask/connect-evm as an optional peer dependency. Install a version that satisfies wagmi's declared peer range — do not install @metamask/connect-evm@latest blindly: the current 2.x line does not satisfy ^1.3.0, and pairing the connector with a major it wasn't built against produces peer warnings and undefined behavior. @metamask/connect-multichain is installed transitively by connect-evm; you do not need to add it.

Step 2: Create Wagmi Config

import { createConfig, http } from 'wagmi'
import { mainnet, sepolia, optimism, polygon } from 'wagmi/chains'
import { metaMask } from 'wagmi/connectors'

export const config = createConfig({
  chains: [mainnet, sepolia, optimism, polygon],
  connectors: [
    metaMask({
      dapp: {
        name: 'My Dapp',
        url: window.location.href,
        iconUrl: 'https://mydapp.com/icon.png',
      },
      debug: false,
    }),
  ],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
    [optimism.id]: http(),
    [polygon.id]: http(),
  },
})

declare module 'wagmi' {
  interface Register {
    config: typeof config
  }
}

The connector automatically builds supportedNetworks from the configured chains and their default RPC URLs. You do not need to pass RPC URLs manually.