Skip to content

Update MetaMask Connect docs and bump version to 2.1.1 #2984

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yashovardhan merged 1 commit into from
Jul 13, 2026
Merged

Update MetaMask Connect docs and bump version to 2.1.1 #2984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions metamask-connect/evm/guides/manage-user-accounts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,30 @@ This one-step flow is unique to MetaMask Connect EVM's `connectWith` method.
It's not part of Wagmi or other wallet libraries.
:::

## Switch or re-select accounts

Persisted sessions reconnect silently with the previously used account, so users don't get a chance
to pick a different one after reconnecting. To re-prompt for account selection, call
[`connect`](../reference/methods.md#connect) with `forceRequest: true`:

```javascript
const { accounts } = await evmClient.connect({
chainIds: ['0x1'],
forceRequest: true,
})
// The user is prompted to select an account, even if a session already exists.
```

:::note `wallet_requestPermissions` and `wallet_revokePermissions`
The SDK provider intercepts these EIP-2255 methods and maps them to client methods:

- `wallet_requestPermissions` maps to `connect({ forceRequest: true })`. If you call it right after
connecting to show the account picker (a common injected-wallet pattern), the user sees a second
connection prompt. Skip this call when the provider is the SDK's.
- `wallet_revokePermissions` maps to `disconnect`.

:::

## Best practices

Follow these best practices when authenticating users.
Expand Down Expand Up @@ -351,6 +375,13 @@ The following table lists common authentication errors and their codes:
| `-32002` | Request already pending | Disable the connect button while the request is pending. |
| `-32603` | Internal JSON-RPC error | Check if MetaMask is properly installed. |

:::note
Cancellations from `connect`, `connectAndSign`, and `connectWith` don't always surface as a
top-level `code: 4001`. A cancellation can arrive wrapped with an outer `code: 53` and the wallet's
real code on `err.rpcCode`. Normalize the error before branching on it. See
[Normalize cancellations from `connect`](../../troubleshooting/index.md#normalize-cancellations-from-connect).
:::

## Next steps

See the following guides to add more functionality to your dapp:
Expand Down
9 changes: 9 additions & 0 deletions metamask-connect/evm/guides/sign-data/siwe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,15 @@ The following HTML displays the SIWE button:
<p class="alert">Result:<span id="siweResult"></span></p>
```

:::caution Sign-only dapps and network configuration
After `connect` resolves, the provider's active chain follows the wallet's selected network.
If that network isn't in `api.supportedNetworks`, the `personal_sign` request throws
`Chain eip155:<id> is not configured in supportedNetworks`.
Because SIWE users can be on any network, list every network they're likely to be on in
`supportedNetworks`, or pin the provider to a supported chain after connecting.
See [Chain not configured in `supportedNetworks`](../../../troubleshooting/index.md#chain-not-configured-in-supportednetworks).
:::

See the [live example](https://metamask.github.io/test-dapp/#siwe) and
[test dapp source code](https://github.com/MetaMask/test-dapp) for more information.

Expand Down
6 changes: 3 additions & 3 deletions metamask-connect/evm/quickstart/wagmi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,11 +97,11 @@ TOD0: Update with new screenshot and link
Install MetaMask Connect EVM along with its peer dependencies to an existing React project:

:::note Version requirements
This quickstart requires `wagmi@^3.6.0`. The `metaMask` connector is imported from the `wagmi/connectors` path (part of the `wagmi` package) and requires `@metamask/connect-evm@^2.1.0`.
This quickstart requires `wagmi@^3.6.0`. The `metaMask` connector is imported from the `wagmi/connectors` path (part of the `wagmi` package) and requires `@metamask/connect-evm@^2.1.1`.
:::

```bash npm2yarn
npm install @metamask/connect-evm@^2.1.0 wagmi@^3.6.0 viem@2.x @tanstack/react-query
npm install @metamask/connect-evm@^2.1.1 wagmi@^3.6.0 viem@2.x @tanstack/react-query
```

### 2. Import required dependencies
Expand Down Expand Up @@ -320,7 +320,7 @@ If you previously used `@metamask/sdk` with Wagmi, the MetaMask connector now us

```bash npm2yarn
npm uninstall @metamask/sdk
npm install @metamask/connect-evm@^2.1.0 wagmi@^3.6.0
npm install @metamask/connect-evm@^2.1.1 wagmi@^3.6.0
```

2. Update hook usage for Wagmi v3:
Expand Down
32 changes: 16 additions & 16 deletions metamask-connect/evm/reference/methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,22 +36,22 @@ Creates a new EVM client instance.

### Parameters

| Name | Type | Required | Description |
| -------------------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dapp.name` | `string` | Yes | Name of your dapp. |
| `dapp.url` | `string` | No | URL of your dapp. In browsers this is often set automatically; required in Node.js and React Native. |
| `dapp.iconUrl` | `string` | No | URL of your dapp icon. |
| `dapp.base64Icon` | `string` | No | Base64-encoded icon when a hosted URL is unavailable (for example, some React Native setups). Use instead of `iconUrl` when needed. |
| `api.supportedNetworks` | `Record<string, string>` | No | Map of hex chain IDs to RPC URLs for read-only requests and transport. Use [`getInfuraRpcUrls`](#getinfurarpcurls) to generate Infura URLs, then merge custom endpoints. |
| `ui.headless` | `boolean` | No | Enables or disables [headless mode](../guides/headless-mode.md). The default is `false`. |
| `ui.preferExtension` | `boolean` | No | Directly connects through the MetaMask extension when it's installed. The default is `true`. |
| `mobile.preferredOpenLink` | `(deeplink: string) => void` | No | A function that's called to open a deeplink to the MetaMask Mobile App. Required in React Native. |
| `mobile.useDeeplink` | `boolean` | No | Controls use of deeplinks for mobile connection flows. |
| `ui.showInstallModal` | `boolean` | No | Shows the MetaMask install modal when the extension isn't detected. |
| `eventHandlers` | `object` | No | Optional callbacks for connection lifecycle and [provider events](provider-api.md#events). |
| `debug` | `boolean` | No | Enables verbose SDK logging. The default is `false`. |
| `skipAutoAnnounce` | `boolean` | No | Opts out of automatic EIP-6963 provider announcement (default since `@metamask/connect-evm` 2.0.0). Call `client.announceProvider()` to announce manually. |
| `analytics.enabled` | `boolean` | No | Set to `false` to opt out of analytics. |
| Name | Type | Required | Description |
| -------------------------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dapp.name` | `string` | Yes | Name of your dapp. |
| `dapp.url` | `string` | No | URL of your dapp. In browsers this is often set automatically; required in Node.js and React Native. |
| `dapp.iconUrl` | `string` | No | URL of your dapp icon. |
| `dapp.base64Icon` | `string` | No | Base64-encoded icon when a hosted URL is unavailable (for example, some React Native setups). Use instead of `iconUrl` when needed. |
| `api.supportedNetworks` | `Record<string, string>` | No | Map of hex chain IDs to RPC URLs for read-only requests and transport. Use [`getInfuraRpcUrls`](#getinfurarpcurls) to generate Infura URLs, then merge custom endpoints. |
| `ui.headless` | `boolean` | No | Enables or disables [headless mode](../guides/headless-mode.md). The default is `false`. |
| `ui.preferExtension` | `boolean` | No | Directly connects through the MetaMask extension when it's installed. The default is `true`. |
| `mobile.preferredOpenLink` | `(deeplink: string) => void` | No | A function that's called to open a deeplink to the MetaMask Mobile App. Required in React Native. |
| `mobile.useDeeplink` | `boolean` | No | Controls use of deeplinks for mobile connection flows. |
| `ui.showInstallModal` | `boolean` | No | Shows the MetaMask install modal when the extension isn't detected. On mobile web, setting this to `true` also forces the QR/install modal and suppresses the MetaMask app deeplink. Leave at the default `false` for mobile deeplinking. |
| `eventHandlers` | `object` | No | Optional callbacks for connection lifecycle and [provider events](provider-api.md#events). |
| `debug` | `boolean` | No | Enables verbose SDK logging. The default is `false`. |
| `skipAutoAnnounce` | `boolean` | No | Opts out of automatic EIP-6963 provider announcement (default since `@metamask/connect-evm` 2.0.0). Call `client.announceProvider()` to announce manually. |
| `analytics.enabled` | `boolean` | No | Set to `false` to opt out of analytics. |

### Returns

Expand Down
16 changes: 16 additions & 0 deletions metamask-connect/evm/reference/provider-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,15 @@ the same permissions.
This means that the provider emits `accountsChanged` when the user's exposed account address changes.
Listen to this event to [handle accounts](../guides/manage-user-accounts.md).

:::note Account ordering in SDK sessions
The "most recently used account first" ordering is the injected-provider convention. When you use
MetaMask Connect, the account order comes from the session's permitted accounts, which isn't a
selection-first guarantee. Sessions also merge across reconnections, accumulating previously used
accounts, so a stale account can appear first. Don't assume `accounts[0]` is the active account, and
don't treat every `accountsChanged` emission as a user-initiated account switch. See
[Unexpected account switch after reconnect](../../troubleshooting/index.md#unexpected-account-switch-after-reconnect).
:::

### `chainChanged`

```typescript
Expand All @@ -210,6 +219,13 @@ The provider emits this event when the currently connected chain changes.
The `chainId` is a hex string (for example, `0x1`), not a decimal number.
Listen to this event to [detect a user's network](../guides/manage-networks.md).

:::note
Unlike the injected provider, which emits `chainChanged` only on an actual network switch, MetaMask
Connect also emits `chainChanged` as part of the connect handshake. If you attach a handler that
reacts to network changes (for example, reloading the page), it can fire mid-connection. Guard such
handlers so they don't run during the initial connect.
:::

### `connect`

```typescript
Expand Down
Loading
Loading