Wallet Services Plugin for SFA Web SDK

@web3auth/wallet-services-plugin

Wallet Services Plugin Enable allows your application to use templated wallet UI screens. Take control of and personalize the wallet interface, and optionally, activate an embedded wallet for your users.

Note

Access to Wallet Services is gated and available on the Scale plan and above. You can use this feature in the development environment for free.

Wallet Services is currently available for all EVM chains.

Installation

npm install --save @web3auth/wallet-services-plugin

Initialization

Import the WalletServicesPlugin class from @web3auth/wallet-services-plugin.

import { WalletServicesPlugin } from "@web3auth/wallet-services-plugin";

Assign the WalletServicesPlugin class to a variable

After creating your Web3Auth instance, you need to initialize the Wallet Services Plugin and add it to a class for further usage.

const walletServicesPlugin = new WalletServicesPlugin(options);

This constructor takes an object with wsEmbedOpts & walletInitOptions as input.

Arguments

Table

Parameter	Description
wsEmbedOpts?	Configuration options for Wallet Services. It accepts Partial<CtorArgs> as a value.
walletInitOptions?	Parameters to customize your Wallet Services UI within the application. It accepts Partial<WsEmbedParams> as a value.

Interface

constructor(options?: {
  wsEmbedOpts?: Partial<CtorArgs>;
  walletInitOptions?: Partial<WsEmbedParams>;
});

wsEmbedOpts

wsEmbedOpts is an optional parameter that allows you to pass in the configuration options for Wallet Services. It takes the CtorArgs object as input which contains the following parameters:

Table

CtorArgs

Parameter	Description
modalZIndex?	Z-index of the modal and iframe. Default value is 99999.
web3AuthClientId	Web3Auth Client ID in string. You can obtain this from the Web3Auth dashboard.
web3AuthNetwork	Web3Auth network to use. Accepts OPENLOGIN_NETWORK_TYPE.

Interface

export interface CtorArgs {
  /**
   * Z-index of the modal and iframe
   * @defaultValue 99999
   */
  modalZIndex?: number;
  /**
   * You can get your clientId/projectId by registering your
   * dapp on {@link "https://dashboard.web3auth.io"| developer dashboard}
   */
  web3AuthClientId: string;
  /**
   * network specifies the web3auth network to be used.
   */
  web3AuthNetwork: OPENLOGIN_NETWORK_TYPE;
}

walletInitOptions

The walletInitOptions from Wallet Services is an optional parameter that allows you to customize your Wallet Services UI within the application. It takes the object WsEmbedParams as input which contains multiple parameters that allow you to customize the UI of the plugin.

Table

WsEmbedParams

Parameter	Description
chainConfig?	Chain config of the Blockchain to connect with. It accepts EthereumProviderConfig.
whiteLabel?	White Label parameters to whitelisting the Wallet Services UI. It accepts WhiteLabelParams.

Interface

export interface WsEmbedParams {
  /**
   * Chain to connect with
   */
  chainConfig?: EthereumProviderConfig;
  /**
   * Build Environment of WsEmbed.
   *
   * production uses https://wallet.web3auth.io,
   *
   * staging uses https://staging-wallet.web3auth.io,
   *
   * testing uses https://develop-wallet.web3auth.io (latest internal build)
   *
   * development uses http://localhost:4050 (expects wallet-services-frontend to be run locally),
   *
   * @defaultValue production
   */
  buildEnv?: WS_EMBED_BUILD_ENV_TYPE;
  /**
   * Enables or disables logging.
   *
   * Defaults to false in prod and true in other environments
   */
  enableLogging?: boolean;
  /**
   * url of widget to load
   *
   * Defaults to true
   * @defaultValue true
   */
  walletUrls?: Partial<Record<WS_EMBED_BUILD_ENV_TYPE, WalletUrlConfig>>;
  /**
   * Allows you to customize the look & feel of the widget
   */
  whiteLabel?: WhiteLabelParams;
}

whiteLabel

The whiteLabel object provides additional options for customizing the appearance and behavior of Wallet Services UI.

Table

Parameter	Description
showWidgetButton?	Show or hide the wallet widget button. Default is true.
buttonPosition?	Position of the widget button on the screen. Default is bottom-left.
hideNftDisplay?	Hide or show NFT display in the wallet. Default is false.
hideTokenDisplay?	Hide or show token display in the wallet. Default is false.
hideTransfers?	Hide or show the transfer option in the wallet. Default is false.
hideTopup?	Hide or show the top-up option in the wallet. Default is false.
hideReceive?	Hide or show the receive option in the wallet. Default is false.
defaultPortfolio?	Set the default portfolio type. Either token or nft. Default is token.

Interface

export interface WhiteLabelParams {
  /**
   * Show or hide the wallet widget button.
   * @defaultValue true
   */
  showWidgetButton?: boolean;
  /**
   * Position of the widget button.
   * @defaultValue bottom-left
   */
  buttonPosition?: BUTTON_POSITION_TYPE;
  /**
   * Hide or show NFT display in the wallet.
   * @defaultValue false
   */
  hideNftDisplay?: boolean;
  /**
   * Hide or show token display in the wallet.
   * @defaultValue false
   */
  hideTokenDisplay?: boolean;
  /**
   * Hide or show the transfer option in the wallet.
   * @defaultValue false
   */
  hideTransfers?: boolean;
  /**
   * Hide or show the top-up option in the wallet.
   * @defaultValue false
   */
  hideTopup?: boolean;
  /**
   * Hide or show the receive option in the wallet.
   * @defaultValue false
   */
  hideReceive?: boolean;
  /**
   * Set the default portfolio type.
   * @defaultValue token
   */
  defaultPortfolio?: "token" | "nft";
}

note

For more information on customizing the whitelabel options using the WhiteLabelData object, refer to the whitelabel documentation.

Add the walletServicesPlugin class to your Web3Auth instance

After initializing the walletServicesPlugin, use the addPlugin() function to your Web3Auth instance, you can use the Wallet Services Plugin for your dApp.

web3AuthInstance.addPlugin(walletServicesPlugin);

Example

In this example, we're adding the WalletServicesPlugin with a very basic configuration.

import { WalletServicesPlugin } from "@web3auth/wallet-services-plugin";

const walletServicesPlugin = new WalletServicesPlugin({
  walletInitOptions: {
    confirmationStrategy: "modal", // pass this to use the UI modal confirmation while signing
  },
});
web3auth.addPlugin(walletServicesPlugin);

// Show the wallet services plugin UI
await walletServicesPlugin.showWalletUi();

// Show the wallet connect scanner
await walletServicesPlugin.showWalletConnectScanner();

// Show the checkout for top-up or transaction
await walletServicesPlugin.showCheckout();

// Sign a message using the `personal_sign` method with a UI confirmation screen
const signMessageUi = async () => {
  if (!web3auth.provider) {
    console.log("provider not initialized yet");
    return;
  }
  const message = "Example `personal_sign` message";
  const accounts = await web3auth.provider.request<never, string[]>({ method: "eth_accounts" });
  const from = accounts[0];
  const signedMessage = await walletServicesPlugin?.proxyProvider?.request<
    [string, string],
    string
  >({
    method: "personal_sign",
    params: [message, from],
  });
  console.log(signedMessage);
};

await signMessageUi();