Skip to main content

MetaMask Connect Multichain methods

MetaMask Connect Multichain (@metamask/connect-multichain) exposes four primary methods:

It also provides event handlers for session changes. When building with MetaMask Connect Multichain, use these high-level methods to create and manage sessions.

note

These high-level methods wrap the standard Multichain API methods. Use those standard methods if you're building your own client or need lower-level control.

connect​

Connects to MetaMask with specified CAIP-2 chain scopes. The user sees a single approval prompt for all requested chains.

Parameters​

NameTypeRequiredDescription
scopesScope[]YesArray of CAIP-2 chain identifiers to request permission for.
caipAccountIdsCaipAccountId[]YesArray of CAIP-10 account identifiers to request. Pass [] for any.
sessionPropertiesSessionPropertiesNoAdditional session properties.
forceRequestbooleanNoForce a new connection request even if already connected.

Returns​

A promise that resolves when the connection is established.

Example​

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

getSession​

Returns the current multichain session, including the approved scopes and accounts. Call this after connect to retrieve the accounts the user authorized.

Returns​

A promise that resolves to the current Session object containing sessionScopes — a map of CAIP-2 scope IDs to their approved accounts.

Example​

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

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

invokeMethod​

Calls the underlying wallet_invokeMethod Multichain API method to send an RPC request to a specific chain in the active session. Use this to interact with any chain the user has approved, without switching connections.

Parameters​

NameTypeRequiredDescription
options.scopeScopeYesThe CAIP-2 chain identifier to invoke the method on.
options.request.methodstringYesThe RPC method name.
options.request.paramsunknown[]NoThe method parameters.

Returns​

A promise that resolves to the result of the RPC method call.

Example​

const balance = await client.invokeMethod({
  scope: 'eip155:1',
  request: {
    method: 'eth_getBalance',
    params: ['0xYourAddress', 'latest'],
  },
})
console.log('ETH balance:', balance)

disconnect​

Disconnects from MetaMask. The behavior depends on whether scopes are provided:

  • No arguments — revokes all scopes and fully tears down the session.
  • With scopes — revokes only the specified scopes. If other scopes remain, the session stays alive.

Parameters​

NameTypeRequiredDescription
scopesScope[]NoArray of CAIP-2 chain identifiers to revoke. Omit to revoke all.

Returns​

A promise that resolves when the disconnect is complete.

Example​

// Fully disconnect — revokes all scopes and ends the session
await client.disconnect()

// Selective disconnect — revokes only Solana, keeps EVM scopes active
await client.disconnect(['solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'])

on​

Registers an event handler. See Events for available event names.

Parameters​

NameTypeRequiredDescription
eventstringYesThe event name to listen for.
handlerFunctionYesThe callback function to invoke when the event is emitted.

Example​

client.on('wallet_sessionChanged', session => {
  console.log('Session updated:', session)
})

off​

Removes a previously registered event handler.

Parameters​

NameTypeRequiredDescription
eventstringYesThe event name to stop listening for.
handlerFunctionYesThe callback function to remove.

Example​

const handler = session => {
  console.log('Session updated:', session)
}

client.on('wallet_sessionChanged', handler)

// Later, remove the handler
client.off('wallet_sessionChanged', handler)

getInfuraRpcUrls​

Generates a map of Infura RPC URLs keyed by CAIP-2 chain ID. When called without caipChainIds, the returned map includes all supported chains. Use this utility to populate api.supportedNetworks when calling createMultichainClient.

Single-ecosystem dapps

If your dapp targets only EVM, use the getInfuraRpcUrls helper in @metamask/connect-evm instead. It returns hex-chain-ID-keyed URLs that can be passed directly to createEVMClient.

If your dapp targets only Solana, use the getInfuraRpcUrls helper in @metamask/connect-solana instead. It returns network-name-keyed URLs (mainnet, devnet) that can be passed directly to createSolanaClient.

Parameters​

NameTypeRequiredDescription
infuraApiKeystringYesYour Infura API key.
caipChainIdsstring[]NoArray of CAIP-2 chain IDs to include. If omitted, all supported chains are included.

Returns​

A Record<string, string> mapping CAIP-2 chain IDs to Infura RPC URLs. When caipChainIds is provided, only matching chains are included.

Supported chains​

The following chains are included by default when caipChainIds is omitted.

EcosystemNetworkCAIP-2 chain ID
EthereumMainneteip155:1
EthereumSepoliaeip155:11155111
EthereumHoodieip155:560048
LineaMainneteip155:59144
LineaSepoliaeip155:59141
PolygonMainneteip155:137
PolygonAmoyeip155:80002
OptimismMainneteip155:10
OptimismSepoliaeip155:11155420
ArbitrumMainneteip155:42161
ArbitrumSepoliaeip155:421614
BaseMainneteip155:8453
BaseSepoliaeip155:84532
BlastMainneteip155:81457
BlastSepoliaeip155:168587773
ZKsyncMainneteip155:324
ZKsyncSepoliaeip155:300
BSCMainneteip155:56
BSCTestneteip155:97
opBNBMainneteip155:204
opBNBTestneteip155:5611
ScrollMainneteip155:534352
ScrollSepoliaeip155:534351
MantleMainneteip155:5000
MantleSepoliaeip155:5003
SeiMainneteip155:1329
SeiTestneteip155:713715
SwellchainMainneteip155:1923
SwellchainTestneteip155:1924
UnichainMainneteip155:130
UnichainSepoliaeip155:1301
HemiMainneteip155:43111
HemiTestneteip155:743111
MegaETHMainneteip155:6342
MegaETHTestneteip155:6342001
MonadMainneteip155:143
MonadTestneteip155:10143
PalmMainneteip155:11297108109
AvalancheMainneteip155:43114
AvalancheFujieip155:43113
CeloMainneteip155:42220
CeloSepoliaeip155:44787
SolanaMainnetsolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
SolanaDevnetsolana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
note

Each chain must be activated in your Infura dashboard before getInfuraRpcUrls can generate working URLs for it.

Example​

Include all supported chains:

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

const client = await createMultichainClient({
  dapp: { name: 'My DApp', url: 'https://mydapp.com' },
  api: {
    supportedNetworks: {
      ...getInfuraRpcUrls({ infuraApiKey: 'YOUR_INFURA_API_KEY' }),
    },
  },
})

Include only specific chains using caipChainIds:

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

const client = await createMultichainClient({
  dapp: { name: 'My DApp', url: 'https://mydapp.com' },
  api: {
    supportedNetworks: {
      // Each chain must be active in your Infura dashboard
      ...getInfuraRpcUrls({
        infuraApiKey: 'YOUR_INFURA_API_KEY',
        caipChainIds: ['eip155:1', 'eip155:137', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
      }),
    },
  },
})

Properties​

PropertyTypeDescription
statusConnectionStatusConnection status: 'loaded', 'pending', 'connecting', 'connected', or 'disconnected'.
providerMultichainApiClientThe underlying Multichain API client.
transportExtendedTransportThe active transport layer.

Events​

Register event handlers using on and remove them with off.

EventPayloadDescription
wallet_sessionChangedSessionFired when session scopes or accounts change.
display_uristringFired with a URI for custom QR code implementations (headless mode).
stateChangedConnectionStatusFired when the connection status changes.

Example​

client.on('wallet_sessionChanged', session => {
  console.log('Session updated:', session)
})

client.on('display_uri', uri => {
  // Display a custom QR code with this URI
  displayMyCustomQRCode(uri)
})

client.on('stateChanged', status => {
  console.log('Connection status:', status)
})

Next steps​

On this page