Initial Multichain API docs

docs/whats-new.md

@@ -11,6 +11,9 @@ of the [MetaMask developer page](https://metamask.io/developer/).
 
 ## May 2025
 
+- Documented Multichain API [guide](/wallet/how-to/manage-networks/use-multichain),
+  [concept](/wallet/concepts/multichain-api), and [reference](/wallet/reference/multichain-api).
+  ([#1621](https://github.com/MetaMask/metamask-docs/pull/1621))
 - Documented [Solana](/wallet/how-to/use-non-evm-networks/solana) dapp support via the Wallet Standard and third-party libraries.
   ([#1940](https://github.com/MetaMask/metamask-docs/pull/1940))
 - Documented [MetaMask SDK + Web3Auth SDK integration](/sdk/quickstart/javascript-web3auth).

snaps/get-started/install-flask.md

@@ -5,10 +5,9 @@ sidebar_position: 1
 
 # Install MetaMask Flask
 
-To get started building your own Snaps, install the MetaMask Flask browser extension on
-[Google Chrome](https://chromewebstore.google.com/detail/metamask-flask-developmen/ljfoeinjpaedjfecbmggjgodbgkmjkjk)
-or
-[Mozilla Firefox](https://addons.mozilla.org/en-US/firefox/addon/metamask-flask/).
+To build your own Snaps or test upcoming MetaMask features, install the MetaMask Flask browser
+extension on [Google Chrome](https://chromewebstore.google.com/detail/metamask-flask-developmen/ljfoeinjpaedjfecbmggjgodbgkmjkjk)
+or [Mozilla Firefox](https://addons.mozilla.org/en-US/firefox/addon/metamask-flask/).
 
 Install Flask in a new browser profile, or disable any existing installed versions of MetaMask
 before installing Flask.
@@ -27,8 +26,10 @@ If you import accounts with funds into Flask, you do so at your own risk.
 ## About MetaMask Flask
 
 MetaMask Flask is an experimental playground that provides developers access to upcoming MetaMask features.
-While a small set of audited Snaps are allowlisted in the stable version of the MetaMask browser extension, MetaMask Flask is intended for developers building and testing Snaps locally or from npm.
-Also, new Snaps API features are enabled in Flask for testing and developer feedback before they're enabled in MetaMask stable.
+While a small set of audited Snaps are allowlisted in the stable version of the MetaMask browser
+extension, MetaMask Flask is intended for developers building and testing Snaps locally or from npm.
+Also, new MetaMask features are enabled in Flask for testing and developer feedback before they're
+enabled in MetaMask stable.
 These features appear in the documentation with the **Flask** or **FLASK ONLY** tag.
 You can also view Flask-specific features by looking for the **\[FLASK\]** label in the
 [MetaMask Extension changelog](https://github.com/MetaMask/metamask-extension/blob/develop/CHANGELOG.md).

wallet-sidebar.js

@@ -41,6 +41,11 @@ const sidebar = {
               type: "doc",
               label: "Add a network",
               id: "how-to/manage-networks/add-network"
+            },
+            {
+              type: "doc",
+              label: "Interact with multiple networks simultaneously",
+              id: "how-to/manage-networks/use-multichain"
             }
           ]
         },
@@ -191,6 +196,11 @@ const sidebar = {
           label: "About the Wallet API",
           id: "concepts/wallet-api"
         },
+        {
+          type: "doc",
+          label: "About the Multichain API",
+          id: "concepts/multichain-api"
+        },
         {
           type: "doc",
           label: "Convenience libraries",
@@ -267,6 +277,11 @@ const sidebar = {
           label: "Ethereum provider API",
           id: "reference/provider-api",
         },
+        {
+          type: "doc",
+          label: "Multichain API",
+          id: "reference/multichain-api",
+        },
         {
           type: "category",
           label: "JSON-RPC API",

wallet/concepts/multichain-api.md

@@ -0,0 +1,123 @@
+---
+description: Learn about the Multichain API.
+---
+
+# About the Multichain API
+
+:::tip Experimental
+The Multichain API is an experimental feature and currently only available on the extension (not on mobile).
+:::
+
+The Multichain API is a scalable, generalized web3 wallet API that supports simultaneous
+interactions across multiple blockchain networks and ecosystems.
+When integrated with [MetaMask Snaps](/snaps), it enables developers to interact with both popular
+and emerging networks.
+Key benefits include:
+
+- **Elimination of chain switching** - The Multichain API allows dapps to interact with multiple networks without having to request chain switches.
+  This feature reduces development overhead involved with ensuring the correct network is targeted for a given dapp-proposed transaction.
+
+- **Extensibility** - The Multichain API can be integrated with
+  [interoperability Snaps](https://snaps.metamask.io/explore/), providing a standards-based interface
+  to connect wallets with dapps on non-EVM networks.
+
+- **Seamless multichain UX** - The Multichain API offers improvements over EIP-1193 and [wallet-standard](https://github.com/wallet-standard/wallet-standard) interfaces.
+  It allows dapps to create unified cross-ecosystem multichain wallet connection flows, trigger transactions across different networks more seamlessly, and clearly interpret chain-specific addresses.
+
+[**Get started using the Multichain API.**](../how-to/manage-networks/use-multichain.md)
+
+## Technical overview
+
+The Multichain API follows the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md)
+standard for dapps to interface with multichain wallets.
+See [MIP-5](https://github.com/MetaMask/metamask-improvement-proposals/blob/main/MIPs/mip-5.md) and
+[MIP-6](https://github.com/MetaMask/metamask-improvement-proposals/blob/main/MIPs/mip-6.md) for
+detailed information about MetaMask's Multichain API implementation.
+
+The API includes methods for dapps to manage multichain connections:
+
+- [`wallet_createSession`](../reference/multichain-api.md#wallet_createsession) - Creates a multichain connection with a wallet, with specified properties and
+authorization scopes.
+Dapps can update the connection using the same method.
+- [`wallet_invokeMethod`](../reference/multichain-api.md#wallet_invokemethod) - Calls a subset of the [Wallet JSON-RPC API methods](../reference/json-rpc-methods/index.md) on
+a specified chain.
+- [`wallet_getSession`](../reference/multichain-api.md#wallet_getsession) - Gets
+the scopes and properties of the active connection.
+- [`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) - Revokes the active connection.
+
+The API also includes events that wallets can send to dapps:
+
+- [`wallet_notify`](../reference/multichain-api.md#wallet_notify) - Notifies dapps of onchain events or state changes they previously subscribed to.
+- [`wallet_sessionChanged`](../reference/multichain-api.md#wallet_sessionchanged) - Notifies dapps of changes to the multichain connection.
+
+See the [Multichain API reference](../reference/multichain-api.md) for full details.
+
+### Lifecycle diagram
+
+The following sequence diagram illustrates the multichain connection lifecycle.
+
+```mermaid
+%%{
+  init: {
+    'sequence': {
+      'actorMargin': 100,
+      'width': 275
+    }
+  }
+}%%
+
+sequenceDiagram
+  participant Dapp
+  participant Wallet
+  participant WalletDataStore as Wallet data store
+
+  opt Create connection
+  Dapp->>Wallet: wallet_createSession
+  Wallet->>WalletDataStore: Persist connection data
+  Wallet-->>Dapp: {"sessionScopes": {...}}
+  end
+
+  opt Update connection
+  Dapp->>Wallet: wallet_createSession (update auth)
+  Wallet->>WalletDataStore: Update connection data
+  Wallet-->>Dapp: {"sessionScopes": {updatedScopes...}}
+  end
+
+  opt Connection interrupted with wallet-side modification
+  Dapp-->>Wallet: Connection interrupted
+  Wallet->>WalletDataStore: User initiated connection change
+  Wallet-->>Dapp: wallet_sessionChanged (attempt fails)
+  Dapp-->>Wallet: Connection re-established
+  end
+
+  opt Get connection
+  Dapp->>Wallet: wallet_getSession
+  Wallet-->>Dapp: {"sessionScopes": {...}}
+  end
+
+  opt Revoke connection
+  Dapp->>Wallet: wallet_revokeSession
+  Wallet->>WalletDataStore: Update connection data
+  Wallet-->>Dapp: {"result": "true"}
+  end
+```
+
+## Backwards compatibility
+
+When using the Multichain API, your dapp can still interact with the existing
+[Ethereum provider API](wallet-api.md#ethereum-provider-api).
+However, the provider API is not optimized for multichain usage, and we recommend
+[starting directly with the Multichain API](../how-to/manage-networks/use-multichain.md).
+The Multichain API is backwards compatible mainly to support dapps that use third-party libraries
+with dependencies on the legacy provider.
+
+:::note
+A multichain connection will overwrite a connection with the legacy EIP-1193 provider, and vice versa.
+:::
+
+## Get started
+
+Get started with the Multichain API:
+
+- Learn how to [use the Multichain API](../how-to/manage-networks/use-multichain.md).
+- See the [Multichain API reference](../reference/multichain-api.md) for more details.

wallet/concepts/wallet-api.md

@@ -22,7 +22,7 @@ This API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), an
 request users' EVM accounts, read data from blockchains the user is connected to, suggest
 that the user sign messages and transactions, and more.
 
-:::info Note
+:::info EIP-6963: Wallet interoperability
 MetaMask supports [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963), which introduces an
 alternative wallet detection mechanism to the `window.ethereum` injected provider.
 This alternative mechanism enables dapps to support [wallet interoperability](wallet-interoperability.md)
@@ -46,6 +46,13 @@ The MetaMask Ethereum provider API contains the following:
 View the [provider API reference](../reference/provider-api.md) for all the provider properties,
 methods, and events.
 
+:::note Multichain API
+MetaMask supports the [Multichain API](multichain-api.md) for interacting with multiple blockchain networks and ecosystems simultaneously.
+While the Multichain API is backwards compatible with the provider API, the provider API is not optimized for multichain usage.
+If you intend to support multichain interactions, we recommend
+[starting directly with the Multichain API](../how-to/manage-networks/use-multichain.md).
+:::
+
 ## JSON-RPC API
 
 MetaMask uses the [`request()`](../reference/provider-api.md#request)