Skip to main content

MetaMask Connect Multichain methods

MetaMask Connect Multichain (@metamask/connect-multichain) exposes four primary methods: connect() to create a CAIP-25 session across multiple chains, getSession() to retrieve authorized scopes and accounts, invokeMethod() to send RPC requests to any chain in the session, and disconnect() to end the session. It also provides event handlers for session changes.

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.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