Skip to content

docs: align MetaMask Connect docs with current SDK package APIs #2959

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
shahbaz17 merged 6 commits into from
Jun 15, 2026
Merged

docs: align MetaMask Connect docs with current SDK package APIs #2959

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
905da0e
docs: update MetaMask Connect v2 guides & API
shahbaz17 Jun 10, 2026
5c7a605
Docs: update multichain peer-dep and Solana APIs
shahbaz17 Jun 15, 2026
3df800f
Merge branch 'main' into feat-mmc-v2-updates
shahbaz17 Jun 15, 2026
d3f7fe0
Standardize Wagmi capitalization in docs
shahbaz17 Jun 15, 2026
962328a
Clarify Solana network support notes
shahbaz17 Jun 15, 2026
4a0281d
Vale fixes
shahbaz17 Jun 15, 2026
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
1 change: 1 addition & 0 deletions .cursor/rules/terminology.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ listed on the right unless they appear in code, URLs, or direct quotations from
| sign-in / sign-out (noun or adjective) | log-in, log-out, login, logout (as nouns/adj) |
| onchain / offchain | on-chain, off-chain |
| Wallet Standard, Wallet Adapter | wallet-standard, wallet-adapter (except in URLs) |
| Wagmi | wagmi (except in code, package names, imports, URLs, and file paths) |
| MetaMask Agent Wallet | Agentic CLI, Agentic Wallet (except in code/URLs where `agentic` appears) |
| Agent Wallet (short form) | agent wallet (lowercase product name) |
| Guard Mode | guard mode (capitalize Mode) |
Expand Down
50 changes: 26 additions & 24 deletions metamask-connect/evm/guides/migrate-from-sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,8 @@ initialization in a single async step.

:::caution
`createEVMClient` is async, so always `await` it before accessing the client. The client is also a
singleton. Calling `createEVMClient` multiple times merges options into the same instance. Do not
recreate it on every render.
singleton. Calling `createEVMClient` multiple times merges new options into the same instance, but
the `dapp` object from the first call is never overwritten. Do not recreate it on every render.
:::

**Old:**
Expand Down Expand Up @@ -150,7 +150,7 @@ options that MetaMask Connect EVM no longer exposes.
| `openDeeplink` | `mobile.preferredOpenLink` | Same signature: `(deeplink: string) => void` |
| `useDeeplink` | `mobile.useDeeplink` | Same behavior |
| `timer` | Removed | No longer configurable |
| `enableAnalytics` | Removed | No longer available |
| `enableAnalytics` | `analytics.enabled` | Replaced by `analytics: { enabled: false }` to opt out |
| `communicationServerUrl` | Removed | Managed internally |
| `storage` | Removed | Managed internally |

Expand Down Expand Up @@ -229,8 +229,9 @@ so read `.result` from the returned object to get the RPC response value.

:::tip React Native polyfills
Browser-based setups (Vite, Webpack) work without polyfills. If you are migrating a React Native
app and encounter errors referencing `Buffer`, `crypto`, `stream`, or `Event is not defined`, see
[React Native Metro polyfill issues](../../troubleshooting/metro-polyfill-issues.md).
app and encounter errors referencing `Buffer`, `crypto`, or `stream`, see
[React Native Metro polyfill issues](../../troubleshooting/metro-polyfill-issues.md). The
`Event is not defined` error only occurs when you also use Wagmi, which dispatches DOM events.
:::

### 5. Update provider access
Expand Down Expand Up @@ -378,25 +379,26 @@ See the [multichain quickstart](../../multichain/quickstart/javascript.md) for a

<!-- vale off -->

| Old (`@metamask/sdk`) | New (`@metamask/connect-evm`) | Status |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `new MetaMaskSDK(opts)` | `await createEVMClient(opts)` | Renamed, async |
| `sdk.init` | Not needed | Init happens in `createEVMClient` |
| `sdk.connect` | `client.connect({ chainIds })` | Returns `{ accounts, chainId }` |
| `sdk.getProvider` | `client.getProvider` | Returns EIP-1193 provider |
| `sdk.disconnect` | `client.disconnect` | Same, plus partial disconnect support |
| `dappMetadata` | `dapp` | Renamed |
| `infuraAPIKey` | [`getInfuraRpcUrls({ infuraApiKey })`](../reference/methods.md#getinfurarpcurls) in `api.supportedNetworks` | Helper function |
| `readonlyRPCMap` | `api.supportedNetworks` | Merged with Infura URLs |
| `headless` | `ui.headless` | Moved to `ui` namespace |
| `extensionOnly` | `ui.preferExtension` | Renamed, slightly different semantics |
| `openDeeplink` | `mobile.preferredOpenLink` | Moved to `mobile` namespace |
| `useDeeplink` | `mobile.useDeeplink` | Moved to `mobile` namespace |
| `SDKProvider` | `EIP1193Provider` | Standard provider interface |
| `timer` | Removed | — |
| `enableAnalytics` | Removed | — |
| `communicationServerUrl` | Removed | — |
| `storage` | Removed | — |
| Old (`@metamask/sdk`) | New (`@metamask/connect-evm`) | Status |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `new MetaMaskSDK(opts)` | `await createEVMClient(opts)` | Renamed, async |
| `sdk.init` | Not needed | Init happens in `createEVMClient` |
| `sdk.connect` | `client.connect({ chainIds })` | Returns `{ accounts, chainId }` |
| `sdk.getProvider` | `client.getProvider` | Returns EIP-1193 provider |
| `sdk.disconnect` | `client.disconnect` | Same for EVM; `disconnect(scopes)` enables partial disconnect |
| `sdk.terminate` | `client.disconnect` | `terminate` removed; `disconnect()` with no arguments revokes all scopes and ends the session |
| `dappMetadata` | `dapp` | Renamed |
| `infuraAPIKey` | [`getInfuraRpcUrls({ infuraApiKey })`](../reference/methods.md#getinfurarpcurls) in `api.supportedNetworks` | Helper function |
| `readonlyRPCMap` | `api.supportedNetworks` | Merged with Infura URLs |
| `headless` | `ui.headless` | Moved to `ui` namespace |
| `extensionOnly` | `ui.preferExtension` | Renamed, slightly different semantics |
| `openDeeplink` | `mobile.preferredOpenLink` | Moved to `mobile` namespace |
| `useDeeplink` | `mobile.useDeeplink` | Moved to `mobile` namespace |
| `SDKProvider` | `EIP1193Provider` | Standard provider interface |
| `timer` | Removed | — |
| `enableAnalytics` | `analytics.enabled` | Replaced by `analytics: { enabled: false }` to opt out |
| `communicationServerUrl` | Removed | — |
| `storage` | Removed | — |

<!-- vale on -->

Expand Down
4 changes: 4 additions & 0 deletions metamask-connect/evm/quickstart/react-native.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,10 @@ if (typeof global.CustomEvent === 'undefined') {
}
```

:::note
The `Event` and `CustomEvent` polyfills above are only required if you also use Wagmi, which dispatches DOM events. The `@metamask/connect-*` packages use `eventemitter3` internally and don't need them.
:::

:::tip
For detailed troubleshooting of polyfill issues, see [React Native Metro polyfill issues](../../troubleshooting/metro-polyfill-issues.md).
:::
Expand Down
12 changes: 6 additions & 6 deletions metamask-connect/evm/quickstart/wagmi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
[Download the quickstart template](#set-up-using-a-template) or [manually set up MetaMask Connect EVM](#set-up-manually) in an existing dapp.

:::tip Migrating from `@metamask/sdk`?
If you are upgrading an existing wagmi project that used `@metamask/sdk`, see the
If you are upgrading an existing Wagmi project that used `@metamask/sdk`, see the
[Wagmi connector migration reference](#migrate-from-metamasksdk) at the bottom of this page
for a parameter mapping table.
:::
Expand Down Expand Up @@ -97,11 +97,11 @@
Install MetaMask Connect EVM along with its peer dependencies to an existing React project:

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

Check warning on line 100 in metamask-connect/evm/quickstart/wagmi.md

View workflow job for this annotation

GitHub Actions / Spelling (.mdx) 

[vale] reported by reviewdog 🐶
[Consensys.Spelling] Did you really mean 'subpath'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.

Raw Output:
{"message": "[Consensys.Spelling] Did you really mean 'subpath'? Ignore this alert if this is a false positive, or ask Cursor to add the term to the Vale dictionary.", "location": {"path": "metamask-connect/evm/quickstart/wagmi.md", "range": {"start": {"line": 100, "column": 107}}}, "severity": "WARNING"}
:::

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

### 2. Import required dependencies
Expand Down Expand Up @@ -320,12 +320,12 @@

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

2. Update hook usage for wagmi v3:
2. Update hook usage for Wagmi v3:

| Old (wagmi v2) | New (wagmi v3) | Notes |
| Old (Wagmi v2) | New (Wagmi v3) | Notes |
| --------------------------------- | -------------------------------------- | ------------------------------------------- |
| `useAccount` | `useConnection` | Returns `address`, `isConnected`, `chainId` |
| `useConnect` returns `connectors` | `useConnectors` hook | Connectors are a separate hook |
Expand Down
2 changes: 1 addition & 1 deletion metamask-connect/evm/reference/json-rpc-api/eth_coinbase.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import SimplifiedApiReference from '@site/src/components/SimplifiedApiReference'

<SimplifiedApiReference
method="eth_coinbase"
description="Returns the client coinbase address."
description="Returns the currently selected account address. Since @metamask/connect-evm 1.3.1, this returns a single address (not an array)."
parameters={[]}
returns={{
type: 'string',
Expand Down
9 changes: 6 additions & 3 deletions metamask-connect/evm/reference/json-rpc-api/wallet_requestPermissions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,11 @@ import SimplifiedApiReference from '@site/src/components/SimplifiedApiReference'
exampleResponse={`{
"id": 1,
"jsonrpc": "2.0",
"result": {
"eth_accounts": {}
}
"result": [
{
"parentCapability": "eth_accounts",
"caveats": []
}
]
}`}
/>
16 changes: 16 additions & 0 deletions metamask-connect/evm/reference/methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,11 @@ Creates a new EVM client instance.
| `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. |

### Returns

Expand Down Expand Up @@ -274,6 +278,13 @@ Switches the active chain on the EVM client.
If the chain is not already added to the user's MetaMask wallet, the optional `chainConfiguration`
parameter triggers a `wallet_addEthereumChain` request as a fallback.

:::note
Since `@metamask/connect-evm` 1.2.0, calling `switchChain` without `chainConfiguration` for an
unrecognized chain rejects with the wallet's raw `4902` error (not a "No chain configuration found."
message). Handle `4902` in a `catch` block by retrying with `chainConfiguration` or calling
`wallet_addEthereumChain`.
:::

### Parameters

| Name | Type | Required | Description |
Expand Down Expand Up @@ -363,6 +374,11 @@ The EVM client exposes the following read-only properties:
| `selectedChainId` | `Hex \| undefined` | Currently selected chain ID as a hex string. |
| `status` | `ConnectEvmStatus` | Connection status: `'loaded'`, `'pending'`, `'connecting'`, `'connected'`, or `'disconnected'`. |

:::note
On the EVM client, `status` is a `ConnectEvmStatus`. Since `@metamask/connect-evm` 0.11.0 it
reflects the EVM client's own status and no longer proxies `MultichainClient.status`.
:::

### Example

```javascript
Expand Down
15 changes: 15 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 @@ -36,6 +36,10 @@ Throughout this documentation, we refer to the selected provider using `provider
When using MetaMask Connect EVM, you get the same EIP-1193 provider via `client.getProvider`.
The provider returned by MetaMask Connect EVM is available immediately after `createEVMClient` resolves
and supports the same methods, properties, and events documented below.

Since `@metamask/connect-evm` 2.0.0, MetaMask Connect EVM announces its provider through EIP-6963 by
default when the native MetaMask extension hasn't already announced one. Pass `skipAutoAnnounce: true`
to `createEVMClient` to opt out, and call `client.announceProvider` to announce manually.
:::

## Properties
Expand Down Expand Up @@ -203,6 +207,7 @@ provider // Or window.ethereum if you don't support EIP-6963.
```

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).

### `connect`
Expand Down Expand Up @@ -329,6 +334,8 @@ You can use the error `code` property to determine why the request failed.
Common codes and their meaning include:

- `4001` - The request is rejected by the user.
- `-32002` - A request is already pending. Don't send another request; wait for the user to respond in MetaMask.
- `4902` - The chain isn't recognized by the wallet. Add it with `wallet_addEthereumChain`, or pass `chainConfiguration` to [`switchChain`](methods.md#switchchain).
- `-32602` - The parameters are invalid.
- `-32603` - Internal error.

Expand All @@ -340,6 +347,14 @@ The [`eth-rpc-errors`](https://npmjs.com/package/eth-rpc-errors) package impleme
returned by the MetaMask provider, and can help you identify their meaning.
:::

:::note Typed errors
When you use the multichain client, the core (`@metamask/connect-multichain`) exports typed error
classes for `instanceof` checks: `RPCInvokeMethodErr` (wraps wallet `invokeMethod` errors; read the
wallet's original code from `err.rpcCode`), `RPCHttpErr`, `RPCReadonlyResponseErr`, and
`RPCReadonlyRequestErr`. The EVM provider itself rejects with a standard EIP-1193 `ProviderRpcError`
(use `err.code`).
:::

## Next steps

- [JSON-RPC API reference](./json-rpc-api/index.md)
Expand Down
Loading
Loading