Skip to main content

JavaScript SDK options

The JavaScript version of MetaMask SDK takes the following options.


checkInstallationImmediately: <boolean>

Enables or disables immediately checking if MetaMask is installed on the user's browser. If true, the SDK checks for installation upon page load and sends a connection request, prompting the user to install MetaMask if it's not already installed. If false, the SDK waits for the connect method to be called to check for installation.

The default is false.


checkInstallationOnAllCalls: <boolean>

Enables or disables checking if MetaMask is installed on the user's browser before each RPC request. The default is false.


communicationLayerPreference: <type>

The preferred communication layer to use. The default and only option is SOCKET for Socket.IO.


communicationServerUrl: <string>

The URL of the communication server to use. This option is mainly used for debugging and testing the SDK.


dappMetadata: {
name: <string>,
url: <string>,
base64Icon: <string>,

Metadata about the dapp using the SDK. The metadata options are:

  • name - Name of the dapp
  • url - URL of the dapp
  • base64Icon - A base64-encoded icon

Setting dappMetaData creates a clear and trustworthy user experience when connecting your dapp to MetaMask Mobile. MetaMask Mobile displays this metadata in the connection modal to help users identify and verify the connection request.


defaultReadOnlyChainId: <number or hexadecimal string>

Enables sending read-only RPC requests to this chain ID before the user connects to MetaMask. The value is automatically updated to the chain ID used in MetaMask once connected.


enableDebug: <boolean>

Enables or disables sending anonymous analytics to MetaMask to help improve the SDK. The default is true.


extensionOnly: <boolean>

Enables or disables automatically using the MetaMask browser extension if it's detected. The default is false.


infuraAPIKey: <string>

The Infura API key to use for RPC requests. Configure this option to make read-only RPC requests from your dapp.


Use Infura allowlists to protect against other people submitting requests to your API key. You can restrict interactions to specific addresses, origins, user agents, and request methods. We recommend using all allowlist options to maximize the security of your API key and dapp.


modals: <object>

An object that allows you to customize the logic and UI of the displayed modals. This is useful if your dapp requires a custom way to handle connection and reconnection scenarios.

openDeeplink: <function>

A function that is called to open a deeplink to the MetaMask Mobile app.


preferDesktop: <boolean>

Enables or disables preferring the MetaMask browser extension over MetaMask Mobile. The default is false.


readonlyRPCMap: <map>

A map of RPC URLs to use for read-only RPC requests.


shouldShimWeb3: <boolean>

Enables or disables shimming the window.web3 object with the Ethereum provider returned by the SDK (useful for compatibility with older browsers). The default is true.


timer: BackgroundTimer

Used by React Native dapps to keep the dapp alive while using react-native-background-timer.


transports: <array of strings>

Sets the preference on Socket.IO transports.


ui: {
installer: <function>,
confirm: <function>,

Options for customizing the SDK UI.

useDeeplink: <boolean>

Enables or disables using deeplinks to connect with MetaMask Mobile. If false, the SDK uses universal links instead. The default is false.


wakeLockType: <type>

The type of wake lock to use when the SDK is running in the background. Options are Disabled, Temporary, and UntilResponse.