Connect to multichain using MetaMask Connect Multichain

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

Download the quickstart template or manually set up MetaMask Connect Multichain in an existing 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 MetaMask Developer 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.

Set up using a template

1. Download the MetaMask Connect JavaScript(Vite) template:

   npx degit MetaMask/metamask-connect-examples/multichain/quickstart/javascript metamask-multichain-quickstart

2. Navigate into the repository:

   cd metamask-multichain-quickstart

   Degit vs. Git clone

   degit is a tool that enables cloning only the directory structure from a GitHub repository, without retrieving the entire repository.

   Alternatively, use git clone to download the entire repository. Clone the MetaMask Connect examples repository and navigate into the multichain/quickstart/javascript directory:

   git clone https://github.com/MetaMask/metamask-connect-examples
   cd metamask-connect-examples/multichain/quickstart/javascript

3. Install dependencies:

   pnpm install

4. Create a .env.local file:

   touch .env.local

5. In .env.local, add a VITE_INFURA_API_KEY environment variable, replacing <YOUR-API-KEY> with your Infura API key:

   .env.local

   VITE_INFURA_API_KEY=<YOUR-API-KEY>

6. Run the project:

   pnpm dev

You've successfully set up MetaMask Connect Multichain SDK.

Set up manually

1. Install MetaMask Connect Multichain

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

• npm
• Yarn
• pnpm
• Bun

npm install @metamask/connect-multichain

yarn add @metamask/connect-multichain

pnpm add @metamask/connect-multichain

bun add @metamask/connect-multichain

2. Initialize MetaMask Connect Multichain

The following is an example of using MetaMask Connect Multichain for a multichain dapp 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',
  },
  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 chain of your choice:

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

const session = await client.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 CAIP-2 scope.

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
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(apiKey)	Generates Infura RPC URLs keyed by CAIP-2 chain ID

Understanding scopes

Scopes are CAIP-2 chain identifiers that specify which blockchain you're targeting.

Ecosystem	Format	Example
EVM	eip155:<chainId>	eip155:1 (Ethereum), eip155:42161 (Arbitrum One), eip155:137 (Polygon)
Solana	solana:<genesisHash>	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (Mainnet), solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 (Devnet)