Skip to main content

Torus EVM Wallet UI Plugin

@web3auth/torus-wallet-connector-plugin

Torus EVM Wallet UI Plugin helps you get the functionalities of the Torus EVM Wallet into your Web3Auth Instance. It helps you use your Web3Auth key in the Torus EVM Wallet, making it easier for your end user to make transactions, add money into their wallet and even use it across different applications using Torus Wallet.

After initialisation, this plugin you a provider from the Torus EVM Wallet, injecting the Torus Wallet UI into your dApp and helping you make the wallet calls directly through it without the need of making your own wallet UI flow.

In this section we'll explore more about how you can use the Torus EVM Wallet UI Plugin for your dApp.

Installation

@web3auth/torus-wallet-connector-plugin

npm install --save @web3auth/torus-wallet-connector-plugin

Initialisation

Import the TorusWalletConnectorPlugin class from @web3auth/torus-wallet-connector-plugin.

import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";

Assign the TorusWalletConnectorPlugin class to a variable

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

const torusPlugin = new TorusWalletConnectorPlugin(options);

This constructor takes an objects with torusWalletOpts & walletInitOptions as input.

Arguments

While initializing the plugin, you need to pass on the following parameters to the constructor:

ParameterTypeDescriptionMandatory
torusWalletOpts?TorusCtorArgsConfiguration options for Torus WalletNo
walletInitOptionsPartial<TorusParams> & Required<Pick<TorusParams, "whiteLabel">>Parameters to customise your Torus Wallet Embed UI within the applicationYes

torusWalletOpts

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

TorusCtorArgs

ParameterTypeDescriptionDefault ValueMandatory
buttonPosition?enum - (bottom-left, top-left, bottom-right, top-right)Determines where the torus widget is visible on the page.bottom-leftNo
modalZIndex?numberZ-index of the modal and iframe99999No
buttonSizenumberSize of the widget button56No
apiKey?stringTorus Wallet API Key - Get it from Web3Auth DashboardNo

walletInitOptions

The walletInitOptions from Torus Wallet is a required parameter that allows you to customise your Torus Wallet Embed Modal UI within the application. It takes the objet TorusParams as input which contains multiple parameters mentioned in the Torus Wallet Documentation.

Out of those mentioned parameters, the following 3 parameters are important for whitelabeling the plugin:

TorusParams

ParameterTypeMandatoryDescriptionDefault
whiteLabelWhiteLabelParamsYesParams to enable whitelabelling of torus website and widget. Know more about whitelabeling options for Torus Wallet here.N/A
showTorusButtonbooleanNoDetermines whether to show/hide torus widget.true
useWalletConnectbooleanNoSetting useWalletConnect to true allows to display wallet connect qr scanner from torus-embed.false

While initializing the plugin, you need to pass on the following parameters to the constructor:

whiteLabel

As you can see, the whiteLabel parameter is a required parameter within the plugin. This is because this plugin needs you to incorporate basic whitelabel to avoid showing the Torus Wallet branding on your website.

The whiteLabel parameter takes WhiteLabelParams object as input which contains the following parameters:

ParameterTypeMandatoryDescriptionDefault
themeThemeParams
(contains two params, isDark: boolean &
colors: Record<string, string>)
YesParams to customise the theme for the wallet embed. You can enable darkMode and use the colours of your choice for the modal.N/A
logoDarkstringYesLogo to be shown on dark background (dark theme)N/A
logoLightstringYesLogo to be shown on light background (light theme)N/A
defaultLanguage?stringNoLanguage of whitelabelOrder of preference: Whitelabel language > user language (in torus-website) > browser language
topupHide?booleanNoShows/hides topup option in torus-website/widget.false
featuredBillboardHide?booleanNoShows/hides billboard in torus-website.false
disclaimerHide?booleanNoShows/hides disclaimers on login page. Only works if special logins are hiddenfalse
tncLink?stringNoLanguage specific link for terms and conditions on torus-website.
Choose between:
  • en - English
  • de - German
  • ja - Japanese
  • ko - Korean
  • zh - Mandarin
  • es - Spanish
  • fr - French
  • pt - Portuguese
  • nl - Dutch
en - English
privacyPolicy?stringNoLanguage specific link for privacy policy on torus-website.en - English
contactLink?stringNoLanguage specific link for contact links on torus-website.en - English
customTranslations?stringNoCustom translations.en - English
info

For additional information on the init options for Torus Wallet, please check the Torus Wallet documentation

Add the torusPlugin class to your Web3Auth instance

After initialising the torusPlugin, use the addPlugin() function to your Web3Auth instance, you can use the Torus Wallet UI Plugin for your dApp.

await web3AuthInstance.addPlugin(torusPlugin);

Example

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

import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";

const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true,
enableLogging: true,
},
});
await web3auth.addPlugin(torusPlugin);

Using the Torus EVM Wallet Provider

As soon as you add the torusPlugin class to your Web3Auth instance, you have access to the Torus Wallet Provider. You can use this provider to access the Torus Wallet UI within your dApp and make RPC calls through that. To use the provider, use the following command:

setWalletProvider((torusPlugin?.proxyProvider as IProvider) || web3auth?.provider);

showWalletConnectScanner()

Shows the Wallet Connect Scanner to connect with dApps having Wallet Connect login option.

Example

import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";

const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true, // make sure this is enabled before using the showWalletConnectScanner function
enableLogging: true,
},
});

await web3auth.addPlugin(torusPlugin); // add plugin to web3auth instance

await torusPlugin.showWalletConnectScanner();

initiateTopup()

Initiates the Top Up flow with selected provider.

Arguments

ParameterTypeDescriptionMandatory
providerPAYMENT_PROVIDER_TYPE ["moonpay", "wyre", "rampnetwork", "xanpool", "mercuryo", "transak", "banxa"]Payment Provider nameYes
paramsPaymentParamsPayment Params objectYes

PaymentParams

ParameterTypeDescriptionMandatory
selectedAddress?stringAddress to send the funds toNo
selectedCurrency?stringDefault fiat currency for the user to make the payment inNo
fiatValue?numberAmount to buy in the selectedCurrencyNo
selectedCryptoCurrency?stringCryptocurrency to buyNo
chainNetwork?SUPPORTED_PAYMENT_NETWORK_TYPE ["mainnet", "matic", "bsc_mainnet", "avalanche_mainnet", "xdai"]Chain Network to useNo

Example

import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";

const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true,
enableLogging: true,
},
});

await web3auth.addPlugin(torusPlugin); // add plugin to web3auth instance

await torusPlugin.initiateTopup("moonpay", {
selectedAddress: "wallet_address",
selectedCurrency: "USD", // Fiat currency
fiatValue: 100, // Fiat Value
selectedCryptoCurrency: "ETH", // Cryptocurreny `SOL`, `MATIC` etc.
chainNetwork: "mainnet", // Blockchain network
});

Additional Reading

Initialiazing the Torus Plugin with a custom provider

You can also initialize the Torus Wallet UI Plugin with a custom provider. If your dApp is already initiating another provider, you can use that provider to initialize the Torus Wallet UI Plugin. This way it will be easier for you to use the Torus Wallet UI Plugin with your dApp.

Example

import { TorusWalletConnectorPlugin } from "@web3auth/torus-wallet-connector-plugin";

const torusPlugin = new TorusWalletConnectorPlugin({
torusWalletOpts: {
buttonPosition: "bottom-left",
},
walletInitOptions: {
whiteLabel: {
theme: { isDark: true, colors: { primary: "#00a8ff" } },
logoDark: "https://web3auth.io/images/w3a-L-Favicon-1.svg",
logoLight: "https://web3auth.io/images/w3a-D-Favicon-1.svg",
},
useWalletConnect: true,
enableLogging: true,
},
});

torusPlugin.initWithProvider(YOUR_CUSTOM_PROVIDER, userInfo);

Know more about how to use the Torus EVM Wallet Provider