Skip to main content

MetaMask

Prompt users to connect to your app with their MetaMask wallet.

Usage​

import { MetaMaskWallet } from "@thirdweb-dev/wallets";

const wallet = new MetaMaskWallet();

wallet.connect();

Configuration​

Optionally, provide a configuration object when instantiating the MetaMaskWallet class.

chains

Provide an array of chains you want to support.

Must be an array of Chain objects, from the @thirdweb-dev/chains package.

Defaults to our default chains.

import { MetaMaskWallet } from "@thirdweb-dev/wallets";
import { Ethereum, Polygon } from "@thirdweb-dev/chains";

const walletWithOptions = new MetaMaskWallet(
  {
    chains: [Ethereum, Polygon],
  },
);
dappMetadata

Information about your app that the wallet will display when your app tries to connect to it.

Must be an object containing name, url, and optionally description and logoUrl properties.

import { MetaMaskWallet } from "@thirdweb-dev/wallets";

const walletWithOptions = new MetaMaskWallet({
  dappMetadata: {
    name: "thirdweb powered dApp",
    url: "https://thirdweb.com",
    description: "thirdweb powered dApp",
    logoUrl: "https://thirdweb.com/favicon.ico",
  },
});
qrcode

Whether to display the Wallet Connect QR code Modal for connecting to MetaMask on mobile if MetaMask is not injected.

Must be a boolean. Defaults to true.

import { MetaMaskWallet } from "@thirdweb-dev/wallets";

const walletWithOptions = new MetaMaskWallet(
  {
    qrcode: false,
  },
);
walletStorage

Some wallets need to store data in persistent storage. This is the storage that will be used for that.

Must be an object conforming to the AsyncStorage interface:

export interface AsyncStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example:

import { MetaMaskWallet } from "@thirdweb-dev/wallets";

const walletWithOptions = new MetaMaskWallet(
  {
    walletStorage: {
      getItem: (key) => {
        // Implement your own storage logic here
      },
      removeItem: (key) => {
        // Implement your own storage logic here
      },
      setItem: (key, value) => {
        // Implement your own storage logic here
      },
    },
  },
);

Methods​

Once instantiated, utilize the following methods to interact with the MetaMask Wallet.

addListener​

Add a listener for a specific event, and run a callback whenever that event is emitted.

wallet.addListener("connect", (data) => console.log(data));
Configuration

eventName​

The name of the event to listen for. Each event returns a different data object, or no data object at all.

Possible options:

change​

User changes the wallet they are connected with, or the chain they are connected to.

Data available:

{
  address?: string; // available if the address is changed
  chainId?: number; // available if the network is changed
}
connect​

User connects their wallet to your app.

Data available:

{
  address: string;
  chainId: number;
}
disconnect​

User disconnects their wallet from your app.

No data is available.

error​

An error occurs in the wallet.

Data available:

{
  cause: unknown;
  message: string;
  name: string;
  stack: string | undefined;
}
message​

Wallet receives some message that the consumer should be notified of. The kind of message is identified by the type field.

Data available:

{
  type: string;
  data: unknown;
}
open_wallet​

User opens the wallet app.

data is a string | undefined.

request​

Wallet receives some request that the consumer should be notified of. The kind of request is identified by the type field.

No data is available.

callback​

The function to run when the event is emitted.

autoConnect​

Attempts to connect to the wallet without asking the user’ explicitly; possible if the user has already connected to the wallet to your app before.

const address = await wallet.autoConnect();
Configuration

Return Value​

Returns a string containing the wallet address, or undefined if the connection failed.

string | undefined;

connect​

Prompt the user to connect their wallet to your app.

const address = await wallet.connect();
Configuration

Return Value​

Returns a string containing the wallet address, or throws an error if the connection failed.

string;

connectWithQrCode​

Connect to the wallet using a QR code if the user does not have the Metamask extension installed.

await wallet.connectWithQrCode({
  onQrCodeUri(qrCodeUri) {
    // render the QR code with `qrCodeUri`
  },
  onConnected(accountAddress) {
    // update UI to show connected state
  },
  chainId: 1, // optional
});
Configuration

onQrCodeUri​

A callback to show the QR code to the user.

onConnected​

A callback to run when the user has connected their wallet to your app.

chainId​

The chain ID to switch to after connecting. Optional.

string | undefined;

disconnect​

Disconnect the currently connected wallet from your app.

await wallet.disconnect();

emit​

Emit an event, with some optional data.

wallet.emit("EVENT_NAME", data);
Configuration

eventName​

The name of the event to emit.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

data​

Optional data to send with the event. Must be an object with information relevant to the event.

See addListener configuration for more information on the different events.

eventNames​

Get an array of the events for which the emitter has registered listeners.

const eventNames = wallet.eventNames();
Configuration

Return Value​

Returns an array of strings containing the event names.

(`change` | `connect` | `disconnect` | `error` | `message` | `open_wallet` | `request`)[];

getAddress​

Get the address of the currently connected wallet.

const address = await wallet.getAddress();
Configuration

Return Value​

Returns a string containing the wallet address or throws an error if not connected to a wallet.

string;

getChainId​

Get the chain ID of the network the wallet is currently connected to.

const chainId = await wallet.getChainId();
Configuration

Return Value​

Returns a number containing the chain ID, or throws an error if not connected to a wallet.

number;

getMeta​

Get metadata about the wallet, such as the name and iconURL.

const metadata = wallet.getMeta();
Configuration

Return Value​

{
  name: string;
  iconURL: string;
}

getSigner​

Get the signer for the currently connected wallet.

const signer = await wallet.getSigner();
Configuration

Return Value​

Returns a Signer.

Signer;

listenerCount​

Get the number of listeners for a given event.

const listenerCount = wallet.listenerCount("connect");
Configuration

eventName​

The name of the event to get the listener count for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

Return Value​

Returns a number containing the number of listeners for the event.

number;

listeners​

Get an array of the listeners for a given event.

const listeners = wallet.listeners("connect");
Configuration

eventName​

The name of the event to get the listeners for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

Return Value​

Returns an array of functions containing the listeners for the event.

((data: WalletData) => void)[]

removeAllListeners​

Remove all event listeners for either all events, or a specific event.

wallet.removeAllListeners();
Configuration

eventName​

Optionally, provide the name of the event to remove all listeners for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

wallet.removeAllListeners("connect");

removeListener​

Remove a specific event listener for a given event.

Provide the event name and the listener function to remove.

wallet.removeListener("connect", (data) => console.log(data));
Configuration

eventName​

The name of the event to remove the listener for.

Must be one of: change, connect, disconnect, error, message, open_wallet, request.

listener​

The listener function to remove. i.e. provide the same function that was used to add the listener.

signMessage​

Sign a message with the currently connected wallet.

const signature = await wallet.signMessage("Hello world!");
Configuration

message​

The message to sign.

Must be a string.

Return Value​

Returns a string containing the signature.

string;

switchChain​

Switch the currently connected wallet to a different chain.

await wallet.switchChain(1);
Configuration

chainId​

The chain ID to switch to.

Must be a number.

verifySignature​

Verify a signature is valid.

const isValid = await wallet.verifySignature(
  "Message",
  "Signature",
  "wallet_address",
);
Configuration

message​

The message that was signed.

Must be a string.

signature​

The signature to verify.

Must be a string.

address​

The address of the wallet that signed the message.

Must be a string.

chainId​

The chain ID to check the signature on.

Optional, must be a number.