Multichain quickstart

Get started with MetaMask Connect Multichain in your JavaScript (Vite) dapp.

Prerequisites

• Node.js version 19 or later installed.
• Vite installed and configured.
• A package manager installed, such as npm, Yarn, pnpm, or Bun.
• MetaMask installed in your browser or on mobile.
• An Infura API key from the Infura dashboard.

note

This quickstart uses Vite as the build tool for convenience, but MetaMask Connect Multichain works with vanilla JavaScript or any build tool of your choice.

Steps

1. Install MetaMask Connect Multichain

Install the multichain client in an existing JavaScript (Vite) project:

npm

npm install @metamask/connect-multichain

Yarn

yarn add @metamask/connect-multichain

pnpm

pnpm add @metamask/connect-multichain

Bun

bun add @metamask/connect-multichain

2. Initialize MetaMask Connect Multichain

Initialize the multichain client using createMultichainClient. The following is an example of initializing the client in a JavaScript (Vite) project:

import { createMultichainClient } from '@metamask/connect-multichain'

const client = await createMultichainClient({
  dapp: {
    name: 'My Multichain Dapp',
    url: window.location.href,
    iconUrl: 'https://mydapp.com/icon.png', // Or use base64Icon for embedded icons (e.g., React Native)
  },
  api: {
    supportedNetworks: {
      'eip155:1': 'https://mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
      'eip155:137': 'https://polygon-mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
      'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp':
        'https://solana-mainnet.infura.io/v3/YOUR_INFURA_API_KEY',
    },
  },
})

This example configures MetaMask Connect Multichain with the following options:

• dapp - Ensures trust by showing your dapp's name, url, and iconUrl during connection.
• api.supportedNetworks - A map of CAIP-2 chain IDs to RPC URLs for all networks supported by the dapp.

3. Connect and use the Multichain client

Connect to MetaMask, get accounts from the session, and invoke RPC methods on a chain of your choice:

await client.connect(['eip155:1', 'eip155:137', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'], [])

const session = await client.provider.getSession()
const ethAccounts = session.sessionScopes['eip155:1']?.accounts || []
const solAccounts = session.sessionScopes['solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp']?.accounts || []
console.log('ETH accounts:', ethAccounts)
console.log('SOL accounts:', solAccounts)

if (ethAccounts.length > 0) {
  const ethAddress = ethAccounts[0].split(':')[2]
  const ethBalance = await client.invokeMethod({
    scope: 'eip155:1', // Ethereum Mainnet
    request: {
      method: 'eth_getBalance',
      params: [ethAddress, 'latest'],
    },
  })
  console.log('ETH balance:', ethBalance)
}

The user sees a single approval prompt for all requested chains. Use invokeMethod to call RPC methods on any chain in the session by specifying a scope.

Restore sessions

Register a wallet_sessionChanged listener before calling connect, and skip connect when getSession already returns a session (for example, after a page reload). See sessions.

Multichain client methods at a glance

Method	Description
connect(scopes, caipAccountIds)	Connects to MetaMask with multichain scopes
getSession	Returns the current session with approved accounts
invokeMethod({ scope, request })	Calls an RPC method on a specific chain using a scope
disconnect	Disconnects all scopes and ends the session
disconnect(scopes)	Disconnects specific scopes without ending the session
on(event, handler)	Registers an event handler
off(event, handler)	Removes an event handler
getInfuraRpcUrls({ infuraApiKey })	Generates Infura RPC URLs keyed by CAIP-2 chain ID

Next steps

• Understand scopes, accounts, and sessions for CAIP-2 chain identifiers, CAIP-10 account IDs, and CAIP-25 sessions.
• Send transactions on EVM and Solana from a single multichain session.
• Sign messages on EVM and Solana using invokeMethod.
• See Create a multichain dapp for a full step-by-step tutorial with React.