Initial Multichain API docs

docs/whats-new.md

@@ -11,6 +11,9 @@ of the [MetaMask developer page](https://metamask.io/developer/).
 
 ## April 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 [Ethereum Hoodi testnet](/services/get-started/endpoints/#ethereum) support. ([#1977](https://github.com/MetaMask/metamask-docs/pull/1977))
 - Documented [how to use deeplinks](/sdk/guides/use-deeplinks).
   ([#1928](https://github.com/MetaMask/metamask-docs/pull/1928))

docusaurus.config.js

@@ -140,6 +140,20 @@ const config = {
         editUrl: 'https://github.com/MetaMask/metamask-docs/edit/main/',
         sidebarPath: require.resolve('./wallet-sidebar.js'),
         breadcrumbs: false,
+        admonitions: {
+          keywords: [
+            "info",
+            "success",
+            "danger",
+            "note",
+            "tip",
+            "warning",
+            "important",
+            "caution",
+            "security",
+            "flaskOnly",
+          ],
+        },
         sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, ...args }) {
           const sidebarItems = await defaultSidebarItemsGenerator(args)
           const dynamicItems = await fetchAndGenerateDynamicSidebarItems(

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",
+              id: "how-to/manage-networks/use-multichain"
             }
           ]
         },
@@ -177,6 +182,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",
@@ -253,6 +263,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,120 @@
+---
+description: Learn about the Multichain API.
+sidebar_custom_props:
+  flask_only: true
+---
+
+# About the Multichain API
+
+:::flaskOnly
+:::
+
+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 EVM networks without having to request chain switches.
+  This feature significantly reduces development overhead involved with error handling.
+
+- **Extensibility** - The Multichain API can be integrated with
+  [interoperability Snaps](https://snaps.metamask.io/explore/), providing a standards-based interface
+  to non-EVM networks that can be broadly adopted across ecosystems.
+
+- **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 multichain wallet connection flows, trigger transactions across disparate networks, 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 a method [`wallet_createSession`](../reference/multichain-api.md#wallet_createsession)
+that dapps can call to create a multichain connection with a wallet, with specified properties and
+authorization scopes.
+Dapps can update the connection using the same method `wallet_createSession`.
+
+Dapps can use [`wallet_invokeMethod`](../reference/multichain-api.md#wallet_invokemethod) to
+call a subset of the [Wallet JSON-RPC API methods](../reference/json-rpc-methods/index.md) on
+a specified chain.
+Dapps can use [`wallet_getSession`](../reference/multichain-api.md#wallet_getsession) to get
+the scopes and properties of the active connection, and use
+[`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) to revoke the connection.
+The API also supports the following events:
+
+- [`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 Ethereum Provider API is not optimized for multichain usage, and we recommend
+[starting directly with the Multichain API](../how-to/manage-networks/use-multichain.md) if possible.
+The Multichain API is backwards compatible mainly to support dapps that use third-party libraries
+with dependencies on the legacy provider.
+
+## 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.