Ethereum Provider API

Sender injects a global JavaScript API into websites visited by its users using the window.sender.ethereum provider object. This API allows websites to request users' Ethereum accounts, read data from blockchains the user is connected to, and suggest that the user sign messages and transactions.

Properties

window.sender.ethereum.isSender

This property is true if the user has Sender installed.

Methods

eth_requestAccounts

Requests that the user provide an Ethereum address to be identified by. Use this method to access a user's accounts. This method is specified by EIP-1102.

Example:

// eth_requestAccounts code snippet
document.getElementById('connectButton', connect);

function connect() {
  sender.ethereum
    .request({ method: 'eth_requestAccounts' })
    .then(handleAccountsChanged)
    .catch((error) => {
      if (error.code === 4001) {
        // EIP-1193 userRejectedRequest error
        console.log('Please connect to MetaMask.');
      } else {
        console.error(error);
      }
    });
}

wallet_getPermissions

Gets the caller's current permissions. This method returns an array of the caller's permission objects. If the caller has no permissions, the array is empty.

wallet_requestPermissions

Requests permissions from the user. The request causes a Sender popup to appear. You should only request permissions in response to a direct user action, such as a button click.

Example:

// wallet_requestPermissions code snippet

document.getElementById('requestPermissionsButton', requestPermissions);

function requestPermissions() {
  sender.ethereum
    .request({
      method: 'wallet_requestPermissions',
      params: [{ eth_accounts: {} }],
    })
    .then((permissions) => {
      const accountsPermission = permissions.find(
        (permission) => permission.parentCapability === 'eth_accounts'
      );
      if (accountsPermission) {
        console.log('eth_accounts permission successfully requested!');
      }
    })
    .catch((error) => {
      if (error.code === 4001) {
        // EIP-1193 userRejectedRequest error
        console.log('Permissions needed to continue.');
      } else {
        console.error(error);
      }
    });
}

window.sender.ethereum.request(args)

// RequestArguments interface
interface RequestArguments {
  method: string;
  params?: unknown[] | object;
}

window.sender.ethereum.request(args: RequestArguments): Promise<unknown>;

Use this method to submit RPC API requests to Ethereum using Sender It returns a promise that resolves to the result of the RPC method call.

The following is an example of using window.sender.ethereum.request(args) to call eth_sendTransaction:

// Using window.sender.ethereum.request(args) to call eth_sendTransaction example
params: [
  {
    from: '0xb60e8dd61c5d32be8058bb8eb970870f07233155',
    to: '0xd46e8dd67c5d32be8058bb8eb970870f07244567',
    gas: '0x76c0', // 30400
    gasPrice: '0x9184e72a000', // 10000000000000
    value: '0x9184e72a', // 2441406250
    data:
      '0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675',
  },
];

sender.ethereum
  .request({ method: 'eth_sendTransaction', params })
  .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.
  });

Events

The Sender provider emits events using the Node.js EventEmitter API. The following is an example of listening to the accountsChanged event. You should remove listeners once you're done listening to an event (for example, on component unmount in React).

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

window.sender.ethereum.on('accountsChanged', handleAccountsChanged);

// Later
window.sender.ethereum.removeListener('accountsChanged', handleAccountsChanged);

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

accountsChanged

window.sender.ethereum.on('accountsChanged', handler: (accounts: Array<string>) => void);

The Sender 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 address of the most recently used account the caller is permitted to access. 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

window.sender.ethereum.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.

connect

interface ConnectInfo {
  chainId: string;
}

window.sender.ethereum.on('connect', handler: (connectInfo: ConnectInfo) => void);

The provider emits this event when it's first able to submit RPC requests to a chain.

disconnect

window.sender.ethereum.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.

message

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

window.sender.ethereum.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.