Edit MM Connect EVM guides and styles (#2880)

* Edit MM Connect EVM guides and styles

* fix ilnk

* add evm headless mode

* additions and edits

Author: alexandratran

embedded-wallets/build-with-ai.mdx

@@ -94,7 +94,7 @@ For self-hosted instances, add it to your `openclaw.json`:
 For any LLM tool with a system prompt or custom instructions field, paste the skill content below directly.
 
 <details>
-<summary><strong>View `SKILL.md` file</strong></summary>
+<summary>View `SKILL.md` file</summary>
 
 <SkillContent />
 

metamask-connect/evm/guides/best-practices/display.md

@@ -18,6 +18,8 @@ keywords:
 
 # Display in MetaMask
 
+Follow these best practices when displaying icons or method names in MetaMask.
+
 ## Display icons
 
 When your dapp makes a sign-in request to a MetaMask user, MetaMask may render a modal that displays

metamask-connect/evm/guides/headless-mode.md

@@ -0,0 +1,126 @@
+---
+title: 'Use Headless Mode - MetaMask Connect EVM'
+sidebar_label: Use headless mode
+description: Render a custom QR code or connection UI by using headless mode with MetaMask Connect EVM.
+keywords:
+  [headless, QR code, custom UI, display_uri, evm, MetaMask, Connect, connection, modal, deeplink]
+---
+
+# Use headless mode
+
+By default, MetaMask Connect renders its own QR code modal when connecting to MetaMask Mobile
+via MetaMask Wallet Protocol (MWP).
+Headless mode suppresses this built-in modal so you can render your own connection UI.
+
+Use headless mode when you want to:
+
+- Display a custom-styled QR code that matches your dapp's design.
+- Show the connection URI in a different format (for example, a deeplink button instead of a QR code).
+- Integrate the connection flow into an existing modal or onboarding wizard.
+
+## Prerequisites
+
+Follow Step 1 of the [quickstart](../quickstart/javascript.md) to install the EVM client.
+
+## Steps
+
+### 1. Initialize the client with headless mode
+
+Initialize an EVM client using [`createEVMClient`](../reference/methods.md#createevmclient), and set `ui.headless` to `true`:
+
+```javascript
+import { createEVMClient, getInfuraRpcUrls } from '@metamask/connect-evm'
+
+const evmClient = await createEVMClient({
+  dapp: {
+    name: 'My Dapp',
+    url: window.location.href,
+  },
+  api: {
+    supportedNetworks: {
+      ...getInfuraRpcUrls({ infuraApiKey: '<YOUR_INFURA_API_KEY>' }),
+    },
+  },
+  ui: { headless: true },
+})
+```
+
+### 2. Register a `display_uri` listener before connecting
+
+The `display_uri` event fires on the EIP-1193 [provider](../reference/provider-api.md) during the connecting phase with a one-time-use pairing URI.
+You **must** register the listener before calling `connect`, or you may miss the event:
+
+```javascript
+const provider = evmClient.getProvider()
+
+provider.on('display_uri', uri => {
+  showCustomQrModal(uri)
+})
+```
+
+As an alternative to `provider.on`, you can pass a `displayUri` callback when initializing the client via [`eventHandlers`](../reference/methods.md#createevmclient) (see the [migration guide](migrate-from-sdk.md#6-update-event-handling)).
+
+### 3. Connect and handle the result
+
+Call [`connect`](../reference/methods.md#connect) to connect to MetaMask, and handle the result:
+
+```javascript
+try {
+  await evmClient.connect({ chainIds: ['0x1'] })
+  hideCustomQrModal()
+} catch (err) {
+  hideCustomQrModal()
+  if (err.code === 4001) {
+    // User rejected — show retry UI
+  } else {
+    console.error('Connection failed:', err)
+  }
+}
+```
+
+## Important considerations
+
+### URI is one-time-use
+
+The pairing URI delivered by `display_uri` is a one-time-use token.
+Once used or expired, it cannot be reused.
+If the connection fails, call `connect` again to generate a fresh URI.
+
+### `display_uri` only fires during connecting
+
+The event fires only while the client status is `'connecting'`.
+After the connection resolves (success or error), `display_uri` stops firing.
+
+### Extension connections skip QR
+
+When the MetaMask browser extension is installed and `ui.preferExtension` is `true` (the default),
+the SDK connects directly through the extension.
+No `display_uri` event fires because no QR code is needed.
+
+To display the QR connection option even when the extension is available, set `ui.preferExtension` to `false`:
+
+```javascript
+const evmClient = await createEVMClient({
+  dapp: { name: 'My Dapp', url: window.location.href },
+  api: {
+    supportedNetworks: {
+      ...getInfuraRpcUrls({ infuraApiKey: '<YOUR_INFURA_API_KEY>' }),
+    },
+  },
+  ui: {
+    headless: true,
+    preferExtension: false,
+  },
+})
+```
+
+### Monitor connection status
+
+The EVM client exposes a [`status`](../reference/methods.md#properties) property
+(`'loaded' | 'pending' | 'connecting' | 'connected' | 'disconnected'`) you can read when updating UI.
+
+## Next steps
+
+- [Send transactions](send-transactions/index.md) in your JavaScript or Wagmi dapp.
+- [Sign data](sign-data/index.md) with the connected session.
+- See the [EVM methods reference](../reference/methods.md) for the full API.

metamask-connect/evm/guides/interact-with-contracts.md

@@ -43,25 +43,35 @@ With MetaMask Connect EVM:
 
 The following examples demonstrate how to use MetaMask Connect EVM with viem, web3.js, ethers.js, Ethereum APIs, or Wagmi to interact with Solidity smart contracts.
 
-This simple Hello World contract allows anyone to read and write a message to it.
+## Prerequisites
 
-```tsx
-// SPDX-License-Identifier: GPL-3.0
-pragma solidity >=0.7.0 <0.9.0;
+- Follow the [JavaScript quickstart](../quickstart/javascript.md) or [Wagmi quickstart](../quickstart/wagmi.md) to install, initialize, and connect the EVM client.
+- Create and deploy a simple smart contract. For example, the following contract allows anyone to read and write a message to it.
 
-contract HelloWorld {
+  <details>
+  <summary>Hello World contract</summary>
+  <div>
 
-  string public message;
+  ```tsx
+  // SPDX-License-Identifier: GPL-3.0
+  pragma solidity >=0.7.0 <0.9.0;
 
-  constructor(string memory initMessage) {
-    message = initMessage;
-  }
+  contract HelloWorld {
+
+    string public message;
+
+    constructor(string memory initMessage) {
+      message = initMessage;
+    }
 
-  function update(string memory newMessage) public {
-    message = newMessage;
+    function update(string memory newMessage) public {
+      message = newMessage;
+    }
   }
-}
-```
+  ```
+
+  </div>
+  </details>
 
 ## Read from contracts
 

metamask-connect/evm/guides/manage-networks.md

@@ -28,7 +28,7 @@ import TabItem from '@theme/TabItem';
 
 # Manage networks
 
-Use MetaMask Connect EVM to detect, switch, and add EVM networks in your dapp. MetaMask Connect EVM supports `wallet_switchEthereumChain` for switching between networks, `wallet_addEthereumChain` for adding custom networks, and the `chainChanged` event for monitoring network changes in real time.
+Use MetaMask Connect EVM to detect, switch, and add EVM networks in your dapp. MetaMask Connect EVM provides `getChainId` for detecting the current network, `switchChain` for switching between networks, and the `chainChanged` event for monitoring network changes in real time.
 
 With MetaMask Connect EVM:
 
@@ -43,11 +43,15 @@ With MetaMask Connect EVM:
   </a>
 </p>
 
+## Prerequisites
+
+Follow the [JavaScript quickstart](../quickstart/javascript.md) or [Wagmi quickstart](../quickstart/wagmi.md) to install, initialize, and connect the EVM client.
+
 ## Detect and switch networks
 
-With Vanilla JavaScript, implement network management directly using the
-[`eth_chainId`](../reference/json-rpc-api/eth_chainId.mdx) RPC method and
-[`chainChanged`](../reference/provider-api.md#chainchanged) provider event.
+With Vanilla JavaScript, implement network management using
+[`getChainId`](../reference/methods.md#getchainid) to get the current chain ID, and
+[`chainChanged`](../reference/provider-api.md#chainchanged) on the provider to track network switches.
 
 With Wagmi, use the provided hooks for several network-related operations.
 
@@ -72,82 +76,49 @@ const evmClient = await createEVMClient({
     },
   },
 })
-const provider = evmClient.getProvider()
 
-// Get current chain ID
-async function getCurrentChain() {
-  try {
-    const chainId = await provider.request({
-      method: 'eth_chainId',
-    })
-    console.log('Current chain ID:', chainId)
-    return chainId
-  } catch (err) {
-    console.error('Error getting chain:', err)
-  }
+// Get the current chain ID
+function getCurrentChain() {
+  const chainId = evmClient.getChainId()
+  console.log('Current chain ID:', chainId)
+  return chainId
 }
 
 // Listen for network changes
+const provider = evmClient.getProvider()
 provider.on('chainChanged', chainId => {
   console.log('Network changed to:', chainId)
   // We recommend reloading the page
   window.location.reload()
 })
 ```
 
-Switch networks using the
-[`wallet_switchEthereumChain`](../reference/json-rpc-api/wallet_switchEthereumChain.mdx)
-and [`wallet_addEthereumChain`](../reference/json-rpc-api/wallet_addEthereumChain.mdx)
-RPC methods:
+Switch networks using [`switchChain`](../reference/methods.md#switchchain). Pass the optional
+`chainConfiguration` so unknown chains are added to MetaMask in the same step:
 
 ```javascript
 // Network configurations
 const networks = {
   mainnet: {
     chainId: '0x1',
-    name: 'Ethereum Mainnet',
   },
   optimism: {
     chainId: '0xA',
-    name: 'Optimism',
-    rpcUrls: ['https://mainnet.optimism.io'],
-    nativeCurrency: {
-      name: 'Ethereum',
-      symbol: 'ETH',
-      decimals: 18,
+    chainConfiguration: {
+      chainName: 'Optimism',
+      nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+      rpcUrls: ['https://mainnet.optimism.io'],
+      blockExplorerUrls: ['https://optimistic.etherscan.io'],
     },
-    blockExplorerUrls: ['https://optimistic.etherscan.io'],
   },
 }
 
 async function switchNetwork(networkKey) {
-  const network = networks[networkKey]
-
   try {
-    // Try to switch to the network
-    await provider.request({
-      method: 'wallet_switchEthereumChain',
-      params: [{ chainId: network.chainId }],
-    })
+    await evmClient.switchChain(networks[networkKey])
   } catch (err) {
-    // If the error code is 4902, the network needs to be added
-    if (err.code === 4902) {
-      try {
-        await provider.request({
-          method: 'wallet_addEthereumChain',
-          params: [
-            {
-              chainId: network.chainId,
-              chainName: network.name,
-              rpcUrls: network.rpcUrls,
-              nativeCurrency: network.nativeCurrency,
-              blockExplorerUrls: network.blockExplorerUrls,
-            },
-          ],
-        })
-      } catch (addError) {
-        console.error('Error adding network:', addError)
-      }
+    if (err.code === 4001) {
+      console.log('User rejected network switch')
     } else {
       console.error('Error switching network:', err)
     }