Wallet Services

Web3Auth Wallet Services provides a comprehensive suite of wallet functionality including Fiat on Ramp, Swaps, and Wallet UI Interoperability with WalletConnect. These services enhance your application by offering a complete wallet experience without building these features from scratch.

tip

All these configurations can be directly accessed and managed through the Web3Auth dashboard. Manual configuration in the SDK is optional and provided here for reference purposes.

note

This is a paid feature and the minimum pricing plan to use this SDK in a production environment is the Growth Plan. You can use this feature in Web3Auth Sapphire Devnet network for free.

walletServicesConfig

The walletServicesConfig option allows you to customize the wallet services experience for your users.

walletServicesConfig?: WalletServicesConfig;

Configuration Options

Table

Property	Type	Description
confirmationStrategy	CONFIRMATION_STRATEGY_TYPE	How to display confirmation screens
modalZIndex	number	Z-index for modal windows
enableKeyExport	boolean	Enable private key export functionality
whiteLabel	Object	Customization options for the widget appearance

Confirmation Strategy Options

Strategy	Description
default	Uses auto-approve by default, modal for WalletConnect requests
modal	Always uses modal for confirmations
auto-approve	Automatically approves transactions without confirmation

WhiteLabel Options

Property	Type	Description
showWidgetButton	boolean	Whether to show the widget button
buttonPosition	BUTTON_POSITION_TYPE	Position of the widget button on the page
hideNftDisplay	boolean	Hide NFT display in the wallet
hideTokenDisplay	boolean	Hide token display in the wallet
hideTransfers	boolean	Hide transfer functionality
hideTopup	boolean	Hide top-up (fiat on-ramp) functionality
hideReceive	boolean	Hide receive address functionality
hideSwap	boolean	Hide token swap functionality
hideShowAllTokens	boolean	Hide the "show all tokens" option
hideWalletConnect	boolean	Hide WalletConnect integration
defaultPortfolio	"token" | "nft"	Default portfolio view

Button Position Options

Position	Description
bottom-left	Bottom left corner of the page
top-left	Top left corner of the page
bottom-right	Bottom right corner of the page
top-right	Top right corner of the page

Interface

export type WalletServicesConfig = Omit<
  WsEmbedParams,
  | "buildEnv"
  | "enableLogging"
  | "chainId"
  | "chains"
  | "confirmationStrategy"
  | "accountAbstractionConfig"
> & {
  /**
   * Determines how to show confirmation screens
   * @defaultValue default
   *
   * default & auto-approve
   * - use auto-approve as default
   * - if wallet connect request use modal
   *
   * modal
   * - use modal always
   */
  confirmationStrategy?: Exclude<WsEmbedParams["confirmationStrategy"], "popup">;
  modalZIndex?: number;
};

export interface WsEmbedParams {
  /**
   * Supported chains
   */
  chains: ProviderConfig[];
  /**
   * Chain to connect with
   */
  chainId: string;
  /**
   * 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>>;
  /**
   * Determines how to show confirmation screens
   * @defaultValue default
   *
   * default & popup
   * - use popop as default
   * - if wallet connect request use modal
   *
   * modal
   * - use modal always
   *
   * auto-approve
   * - does not work on embed. will use default
   */
  confirmationStrategy?: CONFIRMATION_STRATEGY_TYPE;
  /**
   * Enable and configure account abstraction
   */
  accountAbstractionConfig?: AccountAbstractionMultiChainConfig;
  /**
   * Enable private key export
   *
   * Defaults to false
   * @defaultValue false
   */
  enableKeyExport?: boolean;
  /**
   * Allows you to customize the look & feel of the widget
   */
  whiteLabel?: {
    /**
     * whether to show/hide ws-embed widget.
     *
     * Defaults to true
     * @defaultValue true
     */
    showWidgetButton?: boolean;
    /**
     * Determines where the wsEmbed widget is visible on the page.
     * @defaultValue bottom-left
     */
    buttonPosition?: BUTTON_POSITION_TYPE;
    hideNftDisplay?: boolean;
    hideTokenDisplay?: boolean;
    hideTransfers?: boolean;
    hideTopup?: boolean;
    hideReceive?: boolean;
    hideSwap?: boolean;
    hideShowAllTokens?: boolean;
    hideWalletConnect?: boolean;
    defaultPortfolio?: "token" | "nft";
  } & WhiteLabelData;
}

export declare const CONFIRMATION_STRATEGY: {
  readonly POPUP: "popup";
  readonly MODAL: "modal";
  readonly AUTO_APPROVE: "auto-approve";
  readonly DEFAULT: "default";
};
export type CONFIRMATION_STRATEGY_TYPE =
  (typeof CONFIRMATION_STRATEGY)[keyof typeof CONFIRMATION_STRATEGY];

export type AccountAbstractionMultiChainConfig = {
  smartAccountType?: SmartAccountType;
  chains?: {
    chainId: string;
    bundlerConfig: BundlerConfig;
    paymasterConfig?: PaymasterConfig;
    smartAccountConfig?: SmartAccountConfig;
  }[];
};

export declare const BUTTON_POSITION: {
  readonly BOTTOM_LEFT: "bottom-left";
  readonly TOP_LEFT: "top-left";
  readonly BOTTOM_RIGHT: "bottom-right";
  readonly TOP_RIGHT: "top-right";
};
export type BUTTON_POSITION_TYPE = (typeof BUTTON_POSITION)[keyof typeof BUTTON_POSITION];

Usage

web3AuthContext.tsx

import {
  BUTTON_POSITION,
  CONFIRMATION_STRATEGY,
  WEB3AUTH_NETWORK,
  type Web3AuthOptions,
} from "@web3auth/modal";

const web3AuthOptions: Web3AuthOptions = {
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  walletServicesConfig: {
    confirmationStrategy: CONFIRMATION_STRATEGY.MODAL,
    modalZIndex: 99999,
    enableKeyExport: false,
    whiteLabel: {
      showWidgetButton: true,
      buttonPosition: BUTTON_POSITION.BOTTOM_RIGHT,
      hideNftDisplay: false,
      hideTokenDisplay: false,
      hideTransfers: false,
      hideTopup: false,
      hideReceive: false,
      hideSwap: false,
      hideShowAllTokens: false,
      hideWalletConnect: false,
      defaultPortfolio: "token",
    },
  },
};

const web3AuthContextConfig = {
  web3AuthOptions,
};