|
| 1 | +--- |
| 2 | +description: Learn about the Multichain API. |
| 3 | +--- |
| 4 | + |
| 5 | +# About the Multichain API |
| 6 | + |
| 7 | +:::tip Experimental |
| 8 | +The Multichain API is an experimental feature and currently only available on the extension (not on mobile). |
| 9 | +::: |
| 10 | + |
| 11 | +The Multichain API is a scalable, generalized web3 wallet API that supports simultaneous |
| 12 | +interactions across multiple blockchain networks and ecosystems. |
| 13 | +When integrated with [MetaMask Snaps](/snaps), it enables developers to interact with both popular |
| 14 | +and emerging networks. |
| 15 | +Key benefits include: |
| 16 | + |
| 17 | +- **Elimination of chain switching** - The Multichain API allows dapps to interact with multiple networks without having to request chain switches. |
| 18 | + This feature reduces development overhead involved with ensuring the correct network is targeted for a given dapp-proposed transaction. |
| 19 | + |
| 20 | +- **Extensibility** - The Multichain API can be integrated with |
| 21 | + [interoperability Snaps](https://snaps.metamask.io/explore/), providing a standards-based interface |
| 22 | + to connect wallets with dapps on non-EVM networks. |
| 23 | + |
| 24 | +- **Seamless multichain UX** - The Multichain API offers improvements over EIP-1193 and [wallet-standard](https://github.com/wallet-standard/wallet-standard) interfaces. |
| 25 | + 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. |
| 26 | + |
| 27 | +[**Get started using the Multichain API.**](../how-to/manage-networks/use-multichain.md) |
| 28 | + |
| 29 | +## Technical overview |
| 30 | + |
| 31 | +The Multichain API follows the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) |
| 32 | +standard for dapps to interface with multichain wallets. |
| 33 | +See [MIP-5](https://github.com/MetaMask/metamask-improvement-proposals/blob/main/MIPs/mip-5.md) and |
| 34 | +[MIP-6](https://github.com/MetaMask/metamask-improvement-proposals/blob/main/MIPs/mip-6.md) for |
| 35 | +detailed information about MetaMask's Multichain API implementation. |
| 36 | + |
| 37 | +The API includes methods for dapps to manage multichain connections: |
| 38 | + |
| 39 | +- [`wallet_createSession`](../reference/multichain-api.md#wallet_createsession) - Creates a multichain connection with a wallet, with specified properties and |
| 40 | +authorization scopes. |
| 41 | +Dapps can update the connection using the same method. |
| 42 | +- [`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 |
| 43 | +a specified chain. |
| 44 | +- [`wallet_getSession`](../reference/multichain-api.md#wallet_getsession) - Gets |
| 45 | +the scopes and properties of the active connection. |
| 46 | +- [`wallet_revokeSession`](../reference/multichain-api.md#wallet_revokesession) - Revokes the active connection. |
| 47 | + |
| 48 | +The API also includes events that wallets can send to dapps: |
| 49 | + |
| 50 | +- [`wallet_notify`](../reference/multichain-api.md#wallet_notify) - Notifies dapps of onchain events or state changes they previously subscribed to. |
| 51 | +- [`wallet_sessionChanged`](../reference/multichain-api.md#wallet_sessionchanged) - Notifies dapps of changes to the multichain connection. |
| 52 | + |
| 53 | +See the [Multichain API reference](../reference/multichain-api.md) for full details. |
| 54 | + |
| 55 | +### Lifecycle diagram |
| 56 | + |
| 57 | +The following sequence diagram illustrates the multichain connection lifecycle. |
| 58 | + |
| 59 | +```mermaid |
| 60 | +%%{ |
| 61 | + init: { |
| 62 | + 'sequence': { |
| 63 | + 'actorMargin': 100, |
| 64 | + 'width': 275 |
| 65 | + } |
| 66 | + } |
| 67 | +}%% |
| 68 | +
|
| 69 | +sequenceDiagram |
| 70 | + participant Dapp |
| 71 | + participant Wallet |
| 72 | + participant WalletDataStore as Wallet data store |
| 73 | + |
| 74 | + opt Create connection |
| 75 | + Dapp->>Wallet: wallet_createSession |
| 76 | + Wallet->>WalletDataStore: Persist connection data |
| 77 | + Wallet-->>Dapp: {"sessionScopes": {...}} |
| 78 | + end |
| 79 | + |
| 80 | + opt Update connection |
| 81 | + Dapp->>Wallet: wallet_createSession (update auth) |
| 82 | + Wallet->>WalletDataStore: Update connection data |
| 83 | + Wallet-->>Dapp: {"sessionScopes": {updatedScopes...}} |
| 84 | + end |
| 85 | + |
| 86 | + opt Connection interrupted with wallet-side modification |
| 87 | + Dapp-->>Wallet: Connection interrupted |
| 88 | + Wallet->>WalletDataStore: User initiated connection change |
| 89 | + Wallet-->>Dapp: wallet_sessionChanged (attempt fails) |
| 90 | + Dapp-->>Wallet: Connection re-established |
| 91 | + end |
| 92 | + |
| 93 | + opt Get connection |
| 94 | + Dapp->>Wallet: wallet_getSession |
| 95 | + Wallet-->>Dapp: {"sessionScopes": {...}} |
| 96 | + end |
| 97 | +
|
| 98 | + opt Revoke connection |
| 99 | + Dapp->>Wallet: wallet_revokeSession |
| 100 | + Wallet->>WalletDataStore: Update connection data |
| 101 | + Wallet-->>Dapp: {"result": "true"} |
| 102 | + end |
| 103 | +``` |
| 104 | + |
| 105 | +## Backwards compatibility |
| 106 | + |
| 107 | +When using the Multichain API, your dapp can still interact with the existing |
| 108 | +[Ethereum provider API](wallet-api.md#ethereum-provider-api). |
| 109 | +However, the provider API is not optimized for multichain usage, and we recommend |
| 110 | +[starting directly with the Multichain API](../how-to/manage-networks/use-multichain.md). |
| 111 | +The Multichain API is backwards compatible mainly to support dapps that use third-party libraries |
| 112 | +with dependencies on the legacy provider. |
| 113 | + |
| 114 | +:::note |
| 115 | +A multichain connection will overwrite a connection with the legacy EIP-1193 provider, and vice versa. |
| 116 | +::: |
| 117 | + |
| 118 | +## Get started |
| 119 | + |
| 120 | +Get started with the Multichain API: |
| 121 | + |
| 122 | +- Learn how to [use the Multichain API](../how-to/manage-networks/use-multichain.md). |
| 123 | +- See the [Multichain API reference](../reference/multichain-api.md) for more details. |
0 commit comments