Wallet Management

The widget has a built-in wallet management UI, so you can connect wallets and use the widget as a standalone dApp out of the box. However, when embedding the widget into an existing dApp, reusing the existing wallet management UI of that dApp often makes the most sense.

See wallet management modes in the Widget Playground — open Wallet management in the sidebar.

There are several ecosystems and types of chains supported by the widget:

EVM (Ethereum Virtual Machine) - Ethereum, Polygon, Arbitrum, etc.
SVM (Solana Virtual Machine) - Solana
UTXO - Bitcoin
MVM (Move Virtual Machine) - Sui
TVM (Tron Virtual Machine) - Tron
STL (Stellar) - Stellar

Each ecosystem uses different libraries to manage wallet connections. The simplest way to set up wallet management is using the built-in provider packages:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { EthereumProvider } from '@lifi/widget-provider-ethereum';
import { SolanaProvider } from '@lifi/widget-provider-solana';
import { BitcoinProvider } from '@lifi/widget-provider-bitcoin';
import { SuiProvider } from '@lifi/widget-provider-sui';
import { TronProvider } from '@lifi/widget-provider-tron';
import { StellarProvider } from '@lifi/widget-provider-stellar';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider(),
    SolanaProvider(),
    BitcoinProvider(),
    SuiProvider(),
    TronProvider(),
    StellarProvider(),
  ],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="your-dapp-name" config={widgetConfig} />;
};

EVM Wallet Connection

To manage wallet connections to EVM chains, the widget uses the Wagmi library internally and provides first-class support for Wagmi-based libraries such as:

RainbowKit
ConnectKit
Reown AppKit (formerly WalletConnect)
Privy
Dynamic

Automatic Detection

If you already manage wallets using Wagmi or a Wagmi-based library in your dApp and the Widget detects that it is wrapped in WagmiProvider, it will automatically reuse your wallet management without any additional configuration.

Basic Wagmi Setup

import { LiFiWidget } from '@lifi/widget';
import { createClient } from 'viem';
import { WagmiProvider, createConfig, http } from 'wagmi';
import { mainnet, arbitrum, optimism, scroll } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

const wagmiConfig = createConfig({
  // Provide the full list of chains you want to support
  chains: [mainnet, arbitrum, optimism, scroll],
  connectors: [injected()],
  client({ chain }) {
    return createClient({ chain, transport: http() });
  },
});

export const WidgetPage = () => {
  return (
    <WagmiProvider config={wagmiConfig} reconnectOnMount>
      <LiFiWidget integrator="wagmi-example" />
    </WagmiProvider>
  );
};

Keep Chains in Sync

It’s important to keep the Wagmi chains configuration in sync with the Widget chain list so all functionality, like switching chains, works correctly. There are two approaches:

Manual: Update both Widget and Wagmi chains configuration to specify all supported chains.
Dynamic: Get available chains from LI.FI API and dynamically update Wagmi configuration.

Dynamic Chain Sync

Use the useSyncWagmiConfig hook from @lifi/widget-provider-ethereum and useWidgetChains from @lifi/widget:

import { useSyncWagmiConfig } from '@lifi/widget-provider-ethereum';
import { useWidgetChains } from '@lifi/widget';
import type { WidgetConfig } from '@lifi/widget';
import { injected } from '@wagmi/connectors';
import { useRef, type FC, type PropsWithChildren } from 'react';
import { createClient, http } from 'viem';
import { mainnet } from 'viem/chains';
import type { Config } from 'wagmi';
import { createConfig, WagmiProvider } from 'wagmi';

const connectors = [injected()];

// useWidgetChains requires a WidgetConfig to fetch chains from the LI.FI API
const widgetConfig: WidgetConfig = {
  integrator: 'your-dapp-name',
};

export const WalletProvider: FC<PropsWithChildren> = ({ children }) => {
  const { chains } = useWidgetChains(widgetConfig);
  const wagmi = useRef<Config>(null);

  if (!wagmi.current) {
    wagmi.current = createConfig({
      chains: [mainnet],
      client({ chain }) {
        return createClient({ chain, transport: http() });
      },
      ssr: true,
    });
  }

  useSyncWagmiConfig(wagmi.current, connectors, chains);

  return (
    <WagmiProvider config={wagmi.current} reconnectOnMount={false}>
      {children}
    </WagmiProvider>
  );
};

import { LiFiWidget } from '@lifi/widget';
import { WalletProvider } from '../providers/WalletProvider';

export const WidgetPage = () => {
  return (
    <WalletProvider>
      <LiFiWidget integrator="wagmi-example" />
    </WalletProvider>
  );
};

Please check out our complete examples in the widget repository:

SVM (Solana) Wallet Connection

To manage wallet connections to Solana, the widget uses the Solana Wallet Standard via the @lifi/widget-provider-solana package. The Solana provider automatically discovers wallets that implement the Wallet Standard. To use it, simply include SolanaProvider() in your widget’s providers array:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { SolanaProvider } from '@lifi/widget-provider-solana';

const widgetConfig: WidgetConfig = {
  providers: [SolanaProvider()],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="solana-example" config={widgetConfig} />;
};

The @lifi/widget-provider-solana package requires bs58 (>=4.0.1) as a peer dependency.

MVM (Sui) Wallet Connection

To manage wallet connections to Sui, the widget uses @mysten/dapp-kit-react (^2.0.0).

In Widget v4, the Sui peer dependency changed from @mysten/dapp-kit to @mysten/dapp-kit-react.

If the Widget detects it’s wrapped in a Sui DAppKitContext, it will reuse your wallet management automatically. To use the built-in Sui wallet management, include SuiProvider() in the providers array:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { SuiProvider } from '@lifi/widget-provider-sui';

const widgetConfig: WidgetConfig = {
  providers: [SuiProvider()],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="sui-example" config={widgetConfig} />;
};

If you already have a Sui wallet context in your app using @mysten/dapp-kit-react, the widget will detect it and reuse your existing connection:

import type { FC, PropsWithChildren } from 'react';
import { createDAppKit, DAppKitProvider } from '@mysten/dapp-kit-react';
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';

const dAppKit = createDAppKit({
  networks: ['mainnet'],
  createClient: (network) =>
    new SuiGrpcClient({
      network,
      baseUrl: getJsonRpcFullnodeUrl(network),
    }),
  autoConnect: true,
  storage: localStorage,
  storageKey: 'my-dapp',
});

export const SuiWalletProvider: FC<PropsWithChildren> = ({ children }) => {
  return <DAppKitProvider dAppKit={dAppKit}>{children}</DAppKitProvider>;
};

import { LiFiWidget } from '@lifi/widget';
import { SuiProvider } from '@lifi/widget-provider-sui';
import { SuiWalletProvider } from '../providers/SuiWalletProvider';

export const WidgetPage = () => {
  return (
    <SuiWalletProvider>
      <LiFiWidget
        integrator="sui-example"
        config={{ providers: [SuiProvider()] }}
      />
    </SuiWalletProvider>
  );
};

UTXO (Bitcoin) Wallet Connection

To manage wallet connections to Bitcoin, the widget uses Bigmi. To use the built-in Bitcoin wallet management, include BitcoinProvider() in the providers array:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { BitcoinProvider } from '@lifi/widget-provider-bitcoin';

const widgetConfig: WidgetConfig = {
  providers: [BitcoinProvider()],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="bitcoin-example" config={widgetConfig} />;
};

The @lifi/widget-provider-bitcoin package requires @bigmi/react (^0.8.0) as a peer dependency. If the Widget detects it’s wrapped in BigmiProvider, it will reuse your wallet management automatically:

import type { Config, CreateConnectorFn } from '@bigmi/client';
import { createConfig, phantom, unisat, xverse } from '@bigmi/client';
import { bitcoin, createClient, http } from '@bigmi/core';
import { BigmiProvider } from '@bigmi/react';
import { LiFiWidget } from '@lifi/widget';

const connectors: CreateConnectorFn[] = [phantom(), unisat(), xverse()];

const config = createConfig({
  chains: [bitcoin],
  connectors,
  client({ chain }) {
    return createClient({ chain, transport: http() });
  },
}) as Config;

export const WidgetPage = () => {
  return (
    <BigmiProvider config={config} reconnectOnMount>
      <LiFiWidget integrator="bigmi-example" />
    </BigmiProvider>
  );
};

TVM (Tron) Wallet Connection

To manage wallet connections to Tron, the widget uses @tronweb3/tronwallet-adapter-react-hooks (^1.1.11). To use the built-in Tron wallet management, include TronProvider() in the providers array:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { TronProvider } from '@lifi/widget-provider-tron';

const widgetConfig: WidgetConfig = {
  providers: [TronProvider()],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="tron-example" config={widgetConfig} />;
};

The @lifi/widget-provider-tron package requires @tronweb3/tronwallet-adapter-react-hooks (^1.1.11) as a peer dependency. The TronProvider accepts an optional configuration object with a walletConnect option to enable WalletConnect support for Tron wallets:

import { TronProvider } from '@lifi/widget-provider-tron';

const widgetConfig: WidgetConfig = {
  providers: [
    TronProvider({
      walletConnect: {
        network: 'Mainnet',
        options: {
          projectId: 'your-walletconnect-project-id',
        },
      },
    }),
  ],
};

The walletConnect option accepts a WalletConnectAdapterConfig from @tronweb3/tronwallet-adapters with required network ('Mainnet', 'Shasta', 'Nile', or a chain ID) and options (WalletConnect SignClientTypes.Options including your projectId) fields. Set walletConnect to true to use default settings.

STL (Stellar) Wallet Connection

To manage wallet connections to Stellar, the widget uses the Stellar Wallets Kit, bundled as a direct dependency. There is no peer dependency to install. To use the built-in Stellar wallet management, include StellarProvider() in the providers array:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { StellarProvider } from '@lifi/widget-provider-stellar';

const widgetConfig: WidgetConfig = {
  providers: [StellarProvider()],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="stellar-example" config={widgetConfig} />;
};

The provider connects Freighter, xBull, Lobstr, Rabet, Hana, Klever, OneKey, and Bitget, and renders them in the widget’s own wallet menu.

Stellar differs from the other ecosystems in three ways:

The provider runs on the public Stellar network only. There is no testnet option.
It detects no external Stellar wallet context. Unlike Wagmi, Sui DAppKitContext, or BigmiProvider, there is nothing to reuse, so the widget always manages the Stellar connection itself.
Its only configuration option is sdkProvider.

A Stellar-to-Stellar route always settles to the account that signs it. The widget therefore hides the destination address field for those routes, and a toAddress or a required receiver is not honoured. Cross-chain routes out of Stellar take a normal destination address.

Configuration

WidgetWalletConfig Interface

interface WidgetWalletConfig {
  // Callback when "Connect wallet" button is clicked
  onConnect?(args?: WalletMenuOpenArgs): void;
  
  // Define ecosystem order for multichain wallets
  walletEcosystemsOrder?: Record<string, ChainType[]>;
  
  // Enable hybrid external/internal wallet management
  // @default false
  usePartialWalletManagement?: boolean;
  
  // Force internal wallet management, ignoring external contexts
  // @default false
  forceInternalWalletManagement?: boolean;
}

Connect Wallet Button

When using external wallet management, use the onConnect callback to open your wallet modal:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { useConnectModal } from '@rainbow-me/rainbowkit';

export const WidgetPage = () => {
  const { openConnectModal } = useConnectModal();
  
  return (
    <LiFiWidget
      integrator="your-dapp"
      config={{
        walletConfig: {
          onConnect() {
            openConnectModal?.();
          },
        },
      }}
    />
  );
};

Ethereum Provider Configuration

When using the built-in wallet management via EthereumProvider, you can configure wallet connectors:

import { LiFiWidget, WidgetConfig } from '@lifi/widget';
import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider({
      walletConnect: {
        projectId: 'your-walletconnect-project-id',
      },
      coinbase: {
        appName: 'Your App Name',
      },
      metaMask: {
        // MetaMask SDK options
      },
      porto: {
        // Porto connector options (EIP-7702)
      },
      baseAccount: {
        // Base Account options
      },
    }),
  ],
};

export const WidgetPage = () => {
  return <LiFiWidget integrator="your-dapp" config={widgetConfig} />;
};

Each connector option can also be set to true to use default settings, or omitted to disable that connector:

EthereumProvider({
  walletConnect: true,   // Use defaults (no projectId required for basic discovery)
  coinbase: true,        // Use defaults
  metaMask: false,       // Explicitly disabled (same as omitting)
})

EthereumProviderConfig Interface

interface EthereumProviderConfig {
  walletConnect?: WalletConnectParameters | boolean
  coinbase?: CoinbaseWalletParameters | boolean
  metaMask?: MetaMaskParameters | boolean
  baseAccount?: BaseAccountParameters | boolean
  porto?: Partial<PortoParameters> | boolean
  disableMessageSigning?: boolean
  sdkProvider?: SDKProvider | SDKProviderFactory<EthereumProviderDeps>
}

The disableMessageSigning option disables permit-based (EIP-2612) gasless approvals, falling back to standard token approval transactions. This is useful for smart account compatibility. See Smart Accounts Compatibility below. The sdkProvider option lets you supply a custom SDK provider. See Custom SDK Providers for details.

Partial Wallet Management

If your external wallet management doesn’t support all ecosystems, enable partial wallet management to use a hybrid approach:

const widgetConfig: WidgetConfig = {
  walletConfig: {
    usePartialWalletManagement: true,
  },
};

In partial mode:

External wallet management handles “opt-out” ecosystems
Internal wallet management handles remaining ecosystems
Both wallet menus can operate together

This is useful when migrating to a new setup or when your wallet library only supports certain chains (e.g., RainbowKit for EVM, while internal handles Solana and Bitcoin).

Force Internal Wallet Management

The widget automatically detects existing wallet contexts (e.g., WagmiContext for EVM). To override this and force internal management for all ecosystems:

const widgetConfig: WidgetConfig = {
  walletConfig: {
    forceInternalWalletManagement: true,
  },
};

Ecosystem Order for Wallets

Define the preferred ecosystem order for multichain wallets:

import { ChainType } from '@lifi/widget';

const widgetConfig: WidgetConfig = {
  walletConfig: {
    walletEcosystemsOrder: {
      MetaMask: [ChainType.EVM, ChainType.SVM],
      Phantom: [ChainType.SVM, ChainType.EVM],
    },
  },
};

The keys must match wallet names as labeled in the Widget UI. This only affects display order, not actual ecosystem support.

Custom SDK Providers

Every provider config accepts an sdkProvider option that lets you replace the built-in SDK provider with a custom implementation for signing, chain switching, or other low-level operations. You can pass either an SDKProvider object directly or a factory function that receives ecosystem-specific dependencies and returns an SDKProvider. Each ecosystem exposes different dependencies to the factory:

// EVM
interface EthereumProviderDeps {
  getWalletClient: () => Promise<Client>
  switchChain: (chainId: number) => Promise<Client | undefined>
  disableMessageSigning?: boolean
}

// Solana
interface SolanaProviderDeps {
  getWallet: () => Promise<Wallet>
}

// Bitcoin
interface BitcoinProviderDeps {
  getWalletClient: () => Promise<Client>
}

// Sui
interface SuiProviderDeps {
  getClient: () => Promise<ClientWithCoreApi>
  getSigner: () => Promise<Signer>
}

// Tron
interface TronProviderDeps {
  getWallet: () => Promise<Adapter>
}

// Stellar
interface StellarProviderDeps {
  getWallet: () => Promise<StellarWallet>
  // The network the Wallets Kit was initialized with. Balance reads resolve
  // their network from the provider options, so a custom sdkProvider has to
  // forward this to stay on the network it signs on.
  networkPassphrase: string
}

Example using a factory function with the Ethereum provider:

import { EthereumProvider } from '@lifi/widget-provider-ethereum';
import type { EthereumProviderDeps } from '@lifi/widget-provider-ethereum';
import type { SDKProvider } from '@lifi/sdk';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider({
      sdkProvider: (deps: EthereumProviderDeps): SDKProvider => {
        return {
          // Custom SDKProvider implementation using deps.getWalletClient,
          // deps.switchChain, etc.
        };
      },
    }),
  ],
};

When omitted, each provider uses its built-in SDK provider implementation.

Smart Accounts Compatibility

When using the Widget with smart accounts (Privy, Dynamic, ZeroDev, etc.), you may encounter signature compatibility issues.

The Problem

EOAs use ECDSA signatures for standard transactions
Smart Accounts may use ERC-1271 or other signature validation methods

This can cause incompatibility with native permit functionality (EIP-2612) used for gasless token approvals.

EIP-7702 delegated smart wallets, such as delegated MetaMask accounts, currently require source-chain native gas because gasless or relayer routes are not offered for this wallet type. See EIP-7702 delegated wallet troubleshooting.

EIP-5792 Transaction Batching Support

If your smart account provider supports EIP-5792 (Wallet Function Call API), there should be no compatibility issues. The widget will automatically use batch transactions instead of individual permit signatures.

Disabling Message Signing

For smart accounts without EIP-5792 support, disable message signing to use standard approval transactions. In v4, this option is configured on the EthereumProvider:

import { EthereumProvider } from '@lifi/widget-provider-ethereum';

const widgetConfig: WidgetConfig = {
  providers: [
    EthereumProvider({
      disableMessageSigning: true,
    }),
  ],
};

Disabling message signing will fallback to standard token approval transactions, which may require additional gas fees but ensures compatibility with all smart account implementations.

updateTransactionRequestHook

For advanced use cases, you can modify transaction requests before they’re sent:

const widgetConfig: WidgetConfig = {
  sdkConfig: {
    executionOptions: {
      updateTransactionRequestHook: async (txRequest) => {
        // Modify the transaction request
        return {
          ...txRequest,
          // Your modifications
        };
      },
    },
  },
};