钱包管理

widget 内置了钱包管理 UI，因此你可以连接钱包，并开箱即用地将 widget 作为一个独立的 dApp 使用。然而，在将 widget 嵌入现有 dApp 时，复用该 dApp 现有的钱包管理 UI 往往是最合理的做法。

在 Widget Playground 中查看钱包管理模式：在侧边栏中打开 Wallet management。

widget 支持多种生态系统和链类型：

EVM（以太坊虚拟机）- Ethereum、Polygon、Arbitrum 等。
SVM（Solana 虚拟机）- Solana
UTXO - Bitcoin
MVM（Move 虚拟机）- Sui
TVM（Tron 虚拟机）- Tron

每种生态系统使用不同的库来管理钱包连接。设置钱包管理最简单的方式是使用内置的 provider 包：

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';

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

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

EVM 钱包连接

为了管理与 EVM 链的钱包连接，widget 在内部使用 Wagmi 库，并为基于 Wagmi 的库提供一流支持，例如：

RainbowKit
ConnectKit
Reown AppKit（原 WalletConnect）
Privy
Dynamic

自动检测

如果你已经在 dApp 中使用 Wagmi 或基于 Wagmi 的库管理钱包，并且 widget 检测到它被包裹在 WagmiProvider 中，它将自动复用你的钱包管理，无需任何额外配置。

基础 Wagmi 设置

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>
  );
};

保持链列表同步

保持 Wagmi 链配置与 widget 链列表同步非常重要，这样切换链等所有功能才能正常工作。有两种方法：

手动：更新 widget 和 Wagmi 的链配置，以指定所有支持的链。
动态：从 LI.FI API 获取可用链，并动态更新 Wagmi 配置。

动态链同步

使用 @lifi/widget-provider-ethereum 提供的 useSyncWagmiConfig 钩子和 @lifi/widget 提供的 useWidgetChains：

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>
  );
};

请查看我们在 widget 仓库中的完整示例：

SVM（Solana）钱包连接

为了管理与 Solana 的钱包连接，widget 通过 @lifi/widget-provider-solana 包使用 Solana Wallet Standard。 Solana provider 会自动发现实现了 Wallet Standard 的钱包。要使用它，只需在 widget 的 providers 数组中包含 SolanaProvider()：

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} />;
};

@lifi/widget-provider-solana 包需要 bs58（>=4.0.1）作为对等依赖。

MVM（Sui）钱包连接

为了管理与 Sui 的钱包连接，widget 使用 @mysten/dapp-kit-react（^2.0.0）。

在 Widget v4 中，Sui 的对等依赖从 @mysten/dapp-kit 变更为 @mysten/dapp-kit-react。

如果 widget 检测到它被包裹在 Sui 的 DAppKitContext 中，它将自动复用你的钱包管理。要使用内置的 Sui 钱包管理，请在 providers 数组中包含 SuiProvider()：

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} />;
};

如果你的应用已经通过 @mysten/dapp-kit-react 拥有 Sui 钱包上下文，widget 将检测到它并复用你现有的连接：

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）钱包连接

为了管理与 Bitcoin 的钱包连接，widget 使用 Bigmi。要使用内置的 Bitcoin 钱包管理，请在 providers 数组中包含 BitcoinProvider()：

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} />;
};

@lifi/widget-provider-bitcoin 包需要 @bigmi/react（^0.8.0）作为对等依赖。如果 widget 检测到它被包裹在 BigmiProvider 中，它将自动复用你的钱包管理：

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）钱包连接

为了管理与 Tron 的钱包连接，widget 使用 @tronweb3/tronwallet-adapter-react-hooks（^1.1.11）。要使用内置的 Tron 钱包管理，请在 providers 数组中包含 TronProvider()：

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} />;
};

@lifi/widget-provider-tron 包需要 @tronweb3/tronwallet-adapter-react-hooks（^1.1.11）作为对等依赖。 TronProvider 接受一个可选的配置对象，其中包含 walletConnect 选项，用于为 Tron 钱包启用 WalletConnect 支持：

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

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

walletConnect 选项接受来自 @tronweb3/tronwallet-adapters 的 WalletConnectAdapterConfig，其中包含必填的 network（'Mainnet'、'Shasta'、'Nile' 或链 ID）和 options（包含你的 projectId 的 WalletConnect SignClientTypes.Options）字段。将 walletConnect 设置为 true 可使用默认设置。

配置

WidgetWalletConfig 接口

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;
}

连接钱包按钮

在使用外部钱包管理时，使用 onConnect 回调来打开你的钱包弹窗：

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 配置

在通过 EthereumProvider 使用内置钱包管理时，你可以配置钱包连接器：

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} />;
};

每个连接器选项也可以设置为 true 以使用默认设置，或者省略以禁用该连接器：

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

EthereumProviderConfig 接口

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

disableMessageSigning 选项会禁用基于 permit 的（EIP-2612）无 gas 授权，转而回退到标准的代币授权交易。这对于智能账户的兼容性很有用。参见下方的智能账户兼容性。 sdkProvider 选项让你可以提供自定义的 SDK provider。详情参见自定义 SDK Providers。

部分钱包管理

如果你的外部钱包管理不支持所有生态系统，可以启用部分钱包管理以使用混合方式：

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

在部分模式下：

外部钱包管理负责处理“选择退出”的生态系统
内部钱包管理负责处理其余的生态系统
两个钱包菜单可以同时运行

这在迁移到新设置时，或者当你的钱包库只支持某些链时（例如 RainbowKit 用于 EVM，而内部负责 Solana 和 Bitcoin）非常有用。

强制使用内部钱包管理

widget 会自动检测现有的钱包上下文（例如 EVM 的 WagmiContext）。要覆盖此行为并对所有生态系统强制使用内部管理：

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

钱包的生态系统顺序

为多链钱包定义首选的生态系统顺序：

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

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

键名必须与 widget UI 中标注的钱包名称一致。这只影响显示顺序，不影响实际的生态系统支持。

自定义 SDK Providers

每个 provider 配置都接受一个 sdkProvider 选项，让你可以用自定义实现替换内置的 SDK provider，以处理签名、链切换或其他底层操作。你可以直接传入一个 SDKProvider 对象，或者传入一个接收生态系统特定依赖并返回 SDKProvider 的工厂函数。每种生态系统向工厂暴露不同的依赖：

// 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>
}

以 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.
        };
      },
    }),
  ],
};

省略时，每个 provider 会使用其内置的 SDK provider 实现。

智能账户兼容性

在将 widget 与智能账户（Privy、Dynamic、ZeroDev 等）一起使用时，你可能会遇到签名兼容性问题。

问题所在

EOA 对标准交易使用 ECDSA 签名
智能账户 可能使用 ERC-1271 或其他签名验证方法

这可能会与用于无 gas 代币授权的原生 permit 功能（EIP-2612）产生不兼容。

EIP-7702 委托智能钱包（例如委托的 MetaMask 账户）当前需要源链原生 gas，因为此类钱包不提供无 gas 或中继（relayer）路由。参见 EIP-7702 委托钱包故障排查。

EIP-5792 交易批处理支持

如果你的智能账户 provider 支持 EIP-5792（Wallet Function Call API），则不应存在兼容性问题。widget 会自动使用批处理交易，而非单独的 permit 签名。

禁用消息签名

对于不支持 EIP-5792 的智能账户，禁用消息签名以使用标准授权交易。在 v4 中，此选项在 EthereumProvider 上配置：

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

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

禁用消息签名将回退到标准的代币授权交易，这可能需要额外的 gas 费用，但可以确保与所有智能账户实现的兼容性。

updateTransactionRequestHook

对于高级用例，你可以在交易请求发送前对其进行修改：

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

钱包管理事件

@lifi/wallet-management 包为钱包连接和断开连接事件提供了自己的事件发射器。这些事件与 Widget 事件是分开的。

import {
  useWalletManagementEvents,
  WalletManagementEvent,
} from '@lifi/wallet-management';
import type {
  WalletConnected,
  WalletDisconnected,
} from '@lifi/wallet-management';
import { useEffect } from 'react';

export const WalletEventsExample = () => {
  const walletEvents = useWalletManagementEvents();

  useEffect(() => {
    const onWalletConnected = (data: WalletConnected) => {
      console.log('Wallet connected:', data.address, data.connectorName);
    };
    const onWalletDisconnected = (data: WalletDisconnected) => {
      console.log('Wallet disconnected:', data.chainType);
    };

    walletEvents.on(
      WalletManagementEvent.WalletConnected,
      onWalletConnected
    );
    walletEvents.on(
      WalletManagementEvent.WalletDisconnected,
      onWalletDisconnected
    );

    return () => walletEvents.removeAllListeners();
  }, [walletEvents]);

  return null;
};

WalletConnected

当通过 widget 的内部钱包管理 UI 连接钱包时触发。

interface WalletConnected {
  address: string
  chainId: number
  chainType: ChainType
  connectorId: string
  connectorName: string
}

WalletDisconnected

当钱包断开连接时触发。

interface WalletDisconnected {
  address?: string
  chainId?: number
  chainType: ChainType
  connectorId?: string
  connectorName?: string
}

入门

基本设置

高级

Widget Light (iframe)

其他

使用 Widget Providers

EVM 钱包连接

自动检测

基础 Wagmi 设置

保持链列表同步

动态链同步

SVM（Solana）钱包连接

MVM（Sui）钱包连接

UTXO（Bitcoin）钱包连接

TVM（Tron）钱包连接

配置

WidgetWalletConfig 接口

连接钱包按钮

Ethereum Provider 配置

EthereumProviderConfig 接口

部分钱包管理

强制使用内部钱包管理

钱包的生态系统顺序

自定义 SDK Providers

智能账户兼容性

问题所在

EIP-5792 交易批处理支持

禁用消息签名

updateTransactionRequestHook

钱包管理事件

WalletConnected

WalletDisconnected

​使用 Widget Providers

​EVM 钱包连接

​自动检测

​基础 Wagmi 设置

​保持链列表同步

​动态链同步

​SVM（Solana）钱包连接

​MVM（Sui）钱包连接

​UTXO（Bitcoin）钱包连接

​TVM（Tron）钱包连接

​配置

​WidgetWalletConfig 接口

​连接钱包按钮

​Ethereum Provider 配置

​EthereumProviderConfig 接口

​部分钱包管理

​强制使用内部钱包管理

​钱包的生态系统顺序

​自定义 SDK Providers

​智能账户兼容性

​问题所在

​EIP-5792 交易批处理支持

​禁用消息签名

​updateTransactionRequestHook

​钱包管理事件

​WalletConnected

​WalletDisconnected

使用 Widget Providers

EVM 钱包连接

自动检测

基础 Wagmi 设置

保持链列表同步

动态链同步

SVM（Solana）钱包连接

MVM（Sui）钱包连接

UTXO（Bitcoin）钱包连接

TVM（Tron）钱包连接

配置

WidgetWalletConfig 接口

连接钱包按钮

Ethereum Provider 配置

EthereumProviderConfig 接口

部分钱包管理

强制使用内部钱包管理

钱包的生态系统顺序

自定义 SDK Providers

智能账户兼容性

问题所在

EIP-5792 交易批处理支持

禁用消息签名

updateTransactionRequestHook

钱包管理事件

WalletConnected

WalletDisconnected