Skip to main content

MetaMask API

Detecting that MetaMask is installed and adding additional networks and custom tokens easily make a great dApp user experience, specially those who are not technically skilled. It is important to streamline the onboarding process as much as you can to make it easier for consumers to operate your application. This guide explains how to build a simple button for your front-end application that will automatically add Gnosis to MetaMask.

Summary of actions

  1. Detect MetaMask or propose its installation
  2. Detect ChainId, and propose to add Gnosis if needed
  3. Detect Account, and propose to connect if needed

Detect MetaMask

if (typeof window.ethereum !== 'undefined') {
console.log('MetaMask is installed!');
//TODO: propose users to install MetaMask

Detect Gnosis

The following code includes all the parameters needed by MetaMask to add Gnosis to its networks programmatically

chainId: "0x64",
chainName: "Gnosis",
nativeCurrency: {
name: "xDai",
symbol: "XDAI",
decimals: 18,
rpcUrls: [""],
blockExplorerUrls: [""],

var addGnosisToMetaMask = function() {
method: "wallet_addEthereumChain",
.catch((error) => {

Detect account

Our dApps need access to the user's account, follow this code example to get it:

var getAccount = async function(){
const accounts = await window.ethereum.request({ method: 'eth_requestAccounts' });
// MetaMask provide a single account

Add Custom Token to MetaMask

In addition to directing the user to manually import tokens using the MetaMask UI, you can add code to your dApp's front end to prompt the user to add it to their MetaMask wallet automatically. This can be done using the wallet_watchAsset method. To do so, add the following code to your dApp's front end:

const tokenAddress = 'custom-token-address-on-gnosis';
const tokenSymbol = 'your-token-symbol';
const tokenDecimals = 18; //or how ever many decimals
const tokenImage = 'your-token-image-url';

try {
// wasAdded is a boolean. Like any RPC method, an error may be thrown.
const wasAdded = window.ethereum.request({
method: 'wallet_watchAsset',
params: {
type: 'ERC20', // Initially only supports ERC20, but eventually more!
options: {
address: tokenAddress, // The address that the token is at.
symbol: tokenSymbol, // A ticker symbol or shorthand, up to 5 chars.
decimals: tokenDecimals, // The number of decimals in the token
image: tokenImage, // A string url of the token logo

if (wasAdded) {
console.log('Token Added');
} else {
console.log('Failed to add');
} catch (error) {

Live example

This documentation site is built in ReactJS, check this sample page to see the above code in action.

More info