MetaMask Connect SDK

When to use

• You want to set up a dApp's MetaMask integration — EVM, Solana, or both (multichain) — in vanilla browser JS/TS, React, or React Native
• You want a headless integration — a Node.js CLI, server, or bot that connects to MetaMask Mobile via a terminal QR code
• You want to connect/disconnect, manage the provider and session state, or switch chains
• You want to sign messages (personal_sign, eth_signTypedData_v4, Solana signMessage) — e.g. Sign-In With Ethereum or nonce auth
• You want to send transactions (eth_sendTransaction, Solana sendTransaction / signAndSendTransaction)
• You want to operate across chains through the multichain client's invokeMethod
• You want to use or migrate to the wagmi metaMask() connector
• You want to migrate an existing @metamask/sdk integration to the Connect SDK
• You need to diagnose connection failures, React Native polyfill errors, or QR/deeplink issues

Installation

Pick the client for your integration:

Always-on conventions

Before writing or reviewing any MetaMask Connect code, read references/conventions.md — the always-on core guardrails (import paths, required config, supportedNetworks, singleton behavior, error handling, connection state) plus a topic index into focused references. Then load the focused reference(s) for your task: evm.md (chain IDs / switchChain), events.md, multichain.md, solana.md, react-native.md (polyfills / Metro), csp.md, testing.md. Each topic has a single canonical home, so apply the relevant reference alongside every workflow below.

Set up (choose your stack)

Sign & send (single-chain clients)

Use these with a directly-created EVM or Solana client. If you set up the multichain client, sign/send via invokeMethod instead — see the multichain workflows below.

Multichain operations (invokeMethod across CAIP-2 scopes)

Use these after createMultichainClient to sign or send across CAIP-2 scopes.

Migrate

Troubleshooting

When a connection hangs/fails, a React Native app crashes on a missing polyfill, QR codes or deeplinks don't work, the Solana wallet adapter doesn't detect MetaMask, or a session is lost after reload — see references/troubleshooting.md for a symptom → cause → fix index and a diagnostic checklist.

Important notes

These are the highest-value guardrails; references/conventions.md has the full, source-verified set.

• EVM chain IDs are hex strings ('0x1', not 1 or '1'); CAIP-2 scopes use decimal (eip155:1).
• Every chain the dApp touches must be in api.supportedNetworks with a reachable RPC URL — the check runs in the provider's request() path, not in connect().
• The multichain core is a singleton — create clients once at startup, never inside a React render.
• Handle EIP-1193 code 4001 (user rejected) and -32002 (extension request pending) in catch blocks; multichain invokeMethod errors arrive wrapped in RPCInvokeMethodErr (original code on rpcCode).
• React Native needs polyfills (a window shim always; Event/CustomEvent only when also using wagmi; react-native-get-random-values as the first import) plus metro extraNodeModules shims (stream → readable-stream, the rest → empty stubs).

Resources

• NPM: @metamask/connect-evm, @metamask/connect-solana, @metamask/connect-multichain
• Source plugin: https://github.com/MetaMask/metamask-connect-cursor-plugin
• Provenance: generated from that plugin's skills/ and always-on rules/, source-verified against the published @metamask/connect-* packages.