Skip to main content

Ethereum provider API

This page is a reference for the Ethereum provider API of MetaMask's Wallet API. MetaMask injects the provider API into websites visited by its users using the window.ethereum provider object. You can use the provider properties, methods, and events in your dapp.

Note

MetaMask supports EIP-6963, which introduces an alternative wallet detection mechanism to the window.ethereum injected provider. This alternative mechanism enables dapps to support wallet interoperability by discovering multiple injected wallet providers in a user's browser. We recommend using this mechanism to connect to MetaMask.

You can access the provider API using the selected EIP-6963 provider object. Throughout this documentation, we refer to the selected provider using provider.

Properties​

isMetaMask​

This property is true if the user has MetaMask installed, and false otherwise.

note

This property is non-standard. Non-MetaMask providers may also set this property to true.

Example​

provider.isMetaMask // Or window.ethereum.isMetaMask if you don't support EIP-6963.

Methods​

isConnected()​

Indicates whether the provider is connected to the current chain. If the provider isn't connected, the page must be reloaded to re-establish the connection. See the connect and disconnect events for more information.

note

This method is unrelated to accessing a user's accounts. In the provider interface, "connected" and "disconnected" refer to whether the provider can make RPC requests to the current chain.

Parameters​

None.

Returns​

true if the provider is connected to the current chain, false otherwise.

Example​

provider.isConnected() // Or window.ethereum.isConnected() if you don't support EIP-6963.

request()​

This method is used to submit JSON-RPC API requests to Ethereum using MetaMask.

Parameters​

An object containing:

  • method: string - The JSON-RPC API method name.
  • params: array or object - (Optional) Parameters of the RPC method. In practice, if a method has parameters, they're almost always of type array.

Returns​

A promise that resolves to the result of the RPC method call. If the request fails, the promise rejects with an error.

Example​

The following is an example of using request() to call eth_sendTransaction:

provider // Or window.ethereum if you don't support EIP-6963.
  .request({
    method: "eth_sendTransaction",
    params: [
      {
        from: "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
        to: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
        gas: "0x76c0", // 30400
        gasPrice: "0x9184e72a000", // 10000000000000
        value: "0x9184e72a", // 2441406250
        data: "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
      },
    ],
  })
  .then((result) => {
    // The result varies by RPC method.
    // For example, this method returns a transaction hash hexadecimal string upon success.
  })
  .catch((error) => {
    // If the request fails, the Promise rejects with an error.
  })

_metamask.isUnlocked()​

caution

This method is experimental. Use it at your own risk.

Indicates if MetaMask is unlocked by the user. MetaMask must be unlocked to perform any operation involving user accounts. Note that this method doesn't indicate if the user has exposed any accounts to the caller.

Parameters​

None.

Returns​

A promise that resolves to true if MetaMask is unlocked by the user, and false otherwise.

Example​

provider._metamask.isUnlocked() // Or window.ethereum._metamask.isUnlocked() if you don't support EIP-6963.

Events​

The MetaMask provider emits events using the Node.js EventEmitter API. The following is an example of listening to the accountsChanged event.

You should remove listeners after you're done listening to an event (for example, on component unmount in React).

function handleAccountsChanged(accounts) {
  // Handle new accounts, or lack thereof.
}

provider // Or window.ethereum if you don't support EIP-6963.
  .on("accountsChanged", handleAccountsChanged)

// Later

provider // Or window.ethereum if you don't support EIP-6963.
  .removeListener("accountsChanged", handleAccountsChanged)

accountsChanged​

provider // Or window.ethereum if you don't support EIP-6963.
  .on("accountsChanged", handler: (accounts: Array<string>) => void);

The provider emits this event when the return value of the eth_accounts RPC method changes. eth_accounts returns either an empty array, or an array that contains the addresses of the accounts the caller is permitted to access with the most recently used account first. Callers are identified by their URL origin, which means that all sites with the same origin share the same permissions.

This means that the provider emits accountsChanged when the user's exposed account address changes. Listen to this event to handle accounts.

chainChanged​

provider // Or window.ethereum if you don't support EIP-6963.
  .on("chainChanged", handler: (chainId: string) => void);

The provider emits this event when the currently connected chain changes. Listen to this event to detect a user's network.

Important

We strongly recommend reloading the page upon chain changes, unless you have a good reason not to:

provider // Or window.ethereum if you don't support EIP-6963.
  .on("chainChanged", (chainId) => window.location.reload())

connect​

interface ConnectInfo {
  chainId: string;
}

provider // Or window.ethereum if you don't support EIP-6963.
  .on("connect", handler: (connectInfo: ConnectInfo) => void);

The provider emits this event when it's first able to submit RPC requests to a chain. We recommend listening to this event and using the isConnected() provider method to determine when the provider is connected.

disconnect​

provider // Or window.ethereum if you don't support EIP-6963.
  .on("disconnect", handler: (error: ProviderRpcError) => void);

The provider emits this event if it becomes unable to submit RPC requests to a chain. In general, this only happens due to network connectivity issues or some unforeseen error.

When the provider emits this event, it doesn't accept new requests until the connection to the chain is re-established, which requires reloading the page. You can also use the isConnected() provider method to determine if the provider is disconnected.

message​

interface ProviderMessage {
  type: string;
  data: unknown;
}

provider // Or window.ethereum if you don't support EIP-6963.
  .on("message", handler: (message: ProviderMessage) => void);

The provider emits this event when it receives a message that the user should be notified of. The type property identifies the kind of message.

RPC subscription updates are a common use case for this event. For example, if you create a subscription using eth_subscribe, each subscription update is emitted as a message event with a type of eth_subscription.

Remove event listeners​

removeListener​

Use the removeListener method to remove specific event listeners from an EventEmitter object. In the following example removeListener is used to remove the connect and accountsChanged events:

// Use window.ethereum instead of provider if EIP-6963 is not supported.

// Add listeners
provider.on("_initialized", updateWalletAndAccounts)
provider.on("connect", updateWalletAndAccounts)
provider.on("accountsChanged", updateWallet)
provider.on("chainChanged", updateWalletAndAccounts)
provider.on("disconnect", disconnectWallet)

// Remove individual listeners
provider.removeListener("connect", updateWalletAndAccounts)
provider.removeListener("accountsChanged", updateWallet)

The first argument of removeListener is the event name, and the second argument is a reference to the function passed to on for the event.

removeAllListeners​

You can use removeAllListeners to remove all listeners from the event emitter at once. This method is helpful when you need to clean up all listeners simultaneously.

caution

Use removeAllListeners with caution. This method clears all event listeners associated with the emitter, not only the listeners set up by the application code. Using this method can unexpectedly clear important event handlers, interfere with scripts, and make debugging more complex. You can use the removeListener method to safely remove specific listeners.

// Use window.ethereum instead of provider if EIP-6963 is not supported.

// Add listeners
provider.on("_initialized", updateWalletAndAccounts)
provider.on("connect", updateWalletAndAccounts)
provider.on("accountsChanged", updateWallet)
provider.on("chainChanged", updateWalletAndAccounts)
provider.on("disconnect", disconnectWallet)

// Remove all listeners
provider.removeAllListeners()

In the provided code example, removeAllListeners is called to remove all event listeners attached to the provider object. This cleanup function deletes any event listeners that are no longer needed.

Errors​

All errors returned by the MetaMask provider follow this interface:

interface ProviderRpcError extends Error {
  message: string
  code: number
  data?: unknown
}

The request() provider method throws errors eagerly. You can use the error code property to determine why the request failed. Common codes and their meaning include:

  • 4001 - The request is rejected by the user.
  • -32602 - The parameters are invalid.
  • -32603 - Internal error.

For the complete list of errors, see EIP-1193 and EIP-1474.

tip

The eth-rpc-errors package implements all RPC errors returned by the MetaMask provider, and can help you identify their meaning.