@lifi/widget 4.7.1 → 4.8.0

package/dist/esm/types/widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget.d.ts","names":[],"sources":["../../../src/types/widget.ts"],"mappings":"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"}
+{"version":3,"file":"widget.d.ts","names":[],"sources":["../../../src/types/widget.ts"],"mappings":"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"}

package/dist/esm/types/widget.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget.js","names":[],"sources":["../../../src/types/widget.ts"],"sourcesContent":["import type {\n  BaseToken,\n  ChainType,\n  ContractCall,\n  ExecutionOptions,\n  ExtendedChain,\n  Order,\n  Route,\n  RouteOptions,\n  SDKConfig,\n  StaticToken,\n  Token,\n} from '@lifi/sdk'\nimport type { WalletMenuOpenArgs } from '@lifi/wallet-management'\nimport type { WidgetProviderProps } from '@lifi/widget-provider'\nimport type {\n  Components,\n  PaletteMode,\n  PaletteOptions,\n  Shape,\n  SxProps,\n  Theme,\n} from '@mui/material'\nimport type { TypographyVariantsOptions } from '@mui/material/styles'\nimport type {\n  CSSProperties,\n  PropsWithChildren,\n  ReactNode,\n  RefObject,\n} from 'react'\nimport type {\n  LanguageKey,\n  LanguageResources,\n} from '../providers/I18nProvider/types.js'\nimport type { DefaultFieldValues } from '../stores/form/types.js'\n\nexport type WidgetVariant = 'compact' | 'wide' | 'drawer'\n\n/** @internal Not part of the public API. */\nexport type InternalWidgetMode = 'limit'\nexport type WidgetMode =\n  | 'default'\n  | 'split'\n  | 'custom'\n  | 'refuel'\n  | InternalWidgetMode\nexport type SplitMode = 'bridge' | 'swap'\nexport type SplitModeOptions = {\n  defaultTab: SplitMode\n}\nexport type CustomMode = 'checkout' | 'deposit'\nexport interface ModeOptions {\n  /**\n   * Configure split mode behavior:\n   * - 'bridge' | 'swap': Single mode without tabs\n   * - { defaultTab: 'bridge' | 'swap' }: Tabs mode with configurable default tab\n   */\n  split?: SplitMode | SplitModeOptions\n  custom?: { type: CustomMode }\n}\n\n/**\n * Identity of a header navigation tab. Each key maps to a widget variant, mode and\n * (optionally) mode options; labels are resolved from the key.\n */\nexport type SplitNavigationTabKey = SplitMode\n/** @internal Not part of the public API. */\nexport type InternalNavigationTabKey =\n  | 'default'\n  | 'private'\n  | 'refuel'\n  | 'swap-advanced'\n  | 'bridge-advanced'\n  | 'limit'\nexport type NavigationTabKey = InternalNavigationTabKey | SplitNavigationTabKey\n\nexport type Appearance = PaletteMode | 'system'\nexport interface NavigationProps {\n  /**\n   * If given, uses a negative margin to counteract the padding on sides for navigation elements like icon buttons.\n   * @default true\n   */\n  edge?: boolean\n}\nexport type WidgetThemeComponents = Partial<\n  Pick<\n    Components<Theme>,\n    | 'MuiAppBar'\n    | 'MuiAvatar'\n    | 'MuiButton'\n    | 'MuiCard'\n    | 'MuiDrawer'\n    | 'MuiIconButton'\n    | 'MuiInputCard'\n    | 'MuiNavigationTabs'\n    | 'MuiNavigationTab'\n    | 'MuiTabs'\n    | 'MuiCheckbox'\n  >\n>\n\nexport type WidgetTheme = {\n  colorSchemes?: {\n    light?: {\n      palette: PaletteOptions\n    }\n    dark?: {\n      palette: PaletteOptions\n    }\n  }\n  shape?: Partial<Shape>\n  typography?: TypographyVariantsOptions\n  components?: WidgetThemeComponents\n  container?: CSSProperties\n  routesContainer?: CSSProperties\n  chainSidebarContainer?: CSSProperties\n  header?: CSSProperties\n  navigation?: NavigationProps\n}\n\nexport interface DisabledUIConfig {\n  fromAmount?: boolean\n  fromToken?: boolean\n  toAddress?: boolean\n  toToken?: boolean\n}\n\nexport interface HiddenUIConfig {\n  addressBookConnectedWallets?: boolean\n  allNetworks?: boolean\n  appearance?: boolean\n  bridgesSettings?: boolean\n  chainSelect?: boolean\n  /**\n   * Hide the chain sidebar in the `wide` variant. No effect in other variants.\n   * @default false\n   */\n  chainSidebar?: boolean\n  contactSupport?: boolean\n  /**\n   * Hide the drawer close button. Only meaningful when `variant === 'drawer'`.\n   * @default false\n   */\n  drawerCloseButton?: boolean\n  fromToken?: boolean\n  gasRefuelMessage?: boolean\n  hideSmallBalances?: boolean\n  history?: boolean\n  insufficientGasMessage?: boolean\n  integratorStepDetails?: boolean\n  language?: boolean\n  /**\n   * Hide the warning shown when sending to an address with low historical\n   * on-chain activity (low transaction count or contract-like behavior).\n   * @default false\n   */\n  lowAddressActivityConfirmation?: boolean\n  poweredBy?: boolean\n  /**\n   * Hide the \"Recent searches\" section in the token select view.\n   * @default false\n   */\n  recentSearches?: boolean\n  reverseTokensButton?: boolean\n  routeCardPriceImpact?: boolean\n  routeTokenDescription?: boolean\n  searchTokenInput?: boolean\n  toAddress?: boolean\n  toToken?: boolean\n  walletMenu?: boolean\n}\n\nexport interface RequiredUIConfig {\n  accountDeployedMessage?: boolean\n  toAddress?: boolean\n}\n\nexport type DefaultUI = {\n  transactionDetailsExpanded?: boolean\n  navigationHeaderTitleNoWrap?: boolean\n  /**\n   * Layout for the main form.\n   * - `'default'`: the chain/token selectors plus single amount input.\n   * - `'cards'`: the redesigned card-based layout — stacked Send/Receive amount\n   *   cards (`AmountInputCardPair`) with inline token pill selectors and a swap\n   *   button.\n   * @default 'default'\n   */\n  layout?: 'default' | 'cards'\n}\n\nexport interface WidgetWalletConfig {\n  walletEcosystemsOrder?: Record<string, ChainType[]>\n  onConnect?(args?: WalletMenuOpenArgs): void\n  /**\n   * Determines whether the widget should provide partial wallet management functionality.\n   *\n   * In partial mode, external wallet management will be used for \"opt-out\" providers,\n   * while the internal management is applied for any remaining providers that do not opt out.\n   * This allows a flexible balance between the integrator's custom wallet menu and the widget's native wallet menu.\n   * @default false\n   */\n  usePartialWalletManagement?: boolean\n  /**\n   * This option forces the widget to always use internal wallet management ignoring external wallet management contexts\n   * @default false\n   */\n  forceInternalWalletManagement?: boolean\n}\n\nexport interface WidgetSDKConfig\n  extends Omit<\n    SDKConfig,\n    | 'apiKey'\n    | 'disableVersionCheck'\n    | 'integrator'\n    | 'providers'\n    | 'routeOptions'\n    | 'widgetVersion'\n  > {\n  routeOptions?: Omit<\n    RouteOptions,\n    'bridges' | 'exchanges' | 'fee' | 'referrer' | 'order' | 'slippage'\n  >\n  executionOptions?: Pick<ExecutionOptions, 'updateTransactionRequestHook'>\n}\n\nexport interface WidgetContractTool {\n  name: string\n  logoURI: string\n}\n\nexport interface CalculateFeeParams {\n  fromChain: ExtendedChain\n  toChain: ExtendedChain\n  fromToken: Token\n  toToken: Token\n  fromAddress?: string\n  toAddress?: string\n  fromAmount?: bigint\n  toAmount?: bigint\n  slippage?: number\n}\n\nexport interface WidgetFeeConfig {\n  name?: string\n  logoURI?: string\n  fee?: number\n  /**\n   * Whether to show the fee percentage in the fee details.\n   * @default false\n   */\n  showFeePercentage?: boolean\n  /**\n   * Whether to show a tooltip with the fee details. Requires `name` or `feeTooltipComponent` to be set.\n   * @default false\n   */\n  showFeeTooltip?: boolean\n  /**\n   * Custom tooltip component to show with the fee details.\n   */\n  feeTooltipComponent?: ReactNode\n  /**\n   * Function to calculate fees before fetching quotes.\n   * If provided, this function will be used instead of the `fee` parameter.\n   * Only one of `fee` or `calculateFee` should be used.\n   *\n   * @param params Object containing the fee calculation parameters\n   * @returns A promise that resolves to the calculated fee as a number (e.g., 0.03 represents a 3% fee)\n   */\n  calculateFee?(params: CalculateFeeParams): Promise<number | undefined>\n}\n\nexport interface ToAddress {\n  name?: string\n  address: string\n  chainType: ChainType\n  logoURI?: string\n}\n\nexport interface AllowDeny<T> {\n  allow?: T[]\n  deny?: T[]\n}\n\nexport type AllowDenySetItem = string | number\nexport interface AllowDenySet {\n  allow?: Set<AllowDenySetItem>\n  deny?: Set<AllowDenySetItem>\n}\n\nexport type AllowDenySets = {\n  from?: AllowDenySet\n  to?: AllowDenySet\n} & AllowDenySet\n\nexport type AllowDenyItems<T> = {\n  from?: AllowDeny<T>\n  to?: AllowDeny<T>\n} & AllowDeny<T>\n\nexport type WidgetChains = {\n  types?: AllowDeny<ChainType>\n} & AllowDenyItems<number>\n\nexport type WidgetTokens = {\n  featured?: StaticToken[]\n  include?: Token[]\n  popular?: StaticToken[]\n  verified?: BaseToken[]\n} & AllowDenyItems<BaseToken>\n\nexport type WidgetLanguages = {\n  default?: LanguageKey\n} & AllowDeny<LanguageKey>\n\nexport type PoweredByType = 'default' | 'jumper'\n\nexport interface RouteLabel {\n  text: string\n  sx?: SxProps<Theme>\n}\n\nexport interface RouteLabelRule {\n  label: RouteLabel\n  // Matching criteria\n  bridges?: AllowDeny<string>\n  exchanges?: AllowDeny<string>\n  fromChainId?: number[]\n  toChainId?: number[]\n  fromTokenAddress?: string[]\n  toTokenAddress?: string[]\n  /**\n   * Custom match function evaluated against the route. When provided, its\n   * result is AND'd with the other matching criteria — all specified\n   * conditions must pass for the label to apply. Use this for matching logic\n   * that the built-in fields cannot express (gas costs, step count, route\n   * tags, etc.).\n   */\n  match?: (route: Route) => boolean\n}\n\nexport type ExplorerUrl =\n  | string\n  | {\n      url: string\n      txPath?: string\n      addressPath?: string\n    }\n\nexport type WidgetProvider = (\n  props: PropsWithChildren<WidgetProviderProps>\n) => ReactNode\n\nexport interface WidgetConfig {\n  fromChain?: number\n  toChain?: number\n  fromToken?: string\n  toToken?: string\n  toAddress?: ToAddress\n  toAddresses?: ToAddress[]\n  fromAmount?: number | string\n  minFromAmountUSD?: number\n  toAmount?: number | string\n  formUpdateKey?: string\n\n  providers?: WidgetProvider[]\n\n  contractCalls?: ContractCall[]\n  contractComponent?: ReactNode\n  contractSecondaryComponent?: ReactNode\n  contractCompactComponent?: ReactNode\n  contractTool?: WidgetContractTool\n  integrator: string\n  apiKey?: string\n  feeConfig?: WidgetFeeConfig\n  referrer?: string\n\n  routePriority?: Order\n  slippage?: number\n\n  variant?: WidgetVariant\n  mode?: WidgetMode\n  modeOptions?: ModeOptions\n  /**\n   * Header navigation tabs, in order. When set, the widget renders a tab bar\n   * and the active tab drives the displayed flow. Each entry is a tab key.\n   *\n   * @internal Not part of the public API.\n   */\n  _navigationTabs?: NavigationTabKey[]\n\n  appearance?: Appearance\n  theme?: WidgetTheme\n\n  disabledUI?: DisabledUIConfig\n  hiddenUI?: HiddenUIConfig\n  requiredUI?: RequiredUIConfig\n  defaultUI?: DefaultUI\n  /**\n   * When true, shows only the recommended route and hides the route\n   * selector UI. Distinct from `routePriority`, which sets the SDK\n   * ranking order across multiple displayed routes.\n   * @default false\n   */\n  showSingleRoute?: boolean\n  useRelayerRoutes?: boolean\n\n  walletConfig?: WidgetWalletConfig\n  sdkConfig?: WidgetSDKConfig\n\n  buildUrl?: boolean\n  keyPrefix?: string\n\n  bridges?: AllowDeny<string>\n  exchanges?: AllowDeny<string>\n  chains?: WidgetChains\n  tokens?: WidgetTokens\n  languages?: WidgetLanguages\n  languageResources?: LanguageResources\n  explorerUrls?: Record<number, ExplorerUrl[]> &\n    Partial<Record<'internal', ExplorerUrl[]>>\n  poweredBy?: PoweredByType\n\n  /**\n   * Custom labels/badges to show on routes based on specified rules\n   */\n  routeLabels?: RouteLabelRule[]\n}\n\nexport interface FormFieldOptions {\n  setUrlSearchParam: boolean\n}\n\nexport interface FieldValues\n  extends Omit<DefaultFieldValues, 'fromAmount' | 'toAmount' | 'toAddress'> {\n  fromAmount?: number | string\n  toAmount?: number | string\n  toAddress?: ToAddress | string\n}\n\nexport type FieldNames = keyof FieldValues\n\nexport type SetFieldValueFunction = <K extends FieldNames>(\n  key: K,\n  value: FieldValues[K],\n  options?: FormFieldOptions\n) => void\n\nexport type FormState = {\n  setFieldValue: SetFieldValueFunction\n}\n\nexport type FormRef = RefObject<FormState | null>\n\nexport interface FormRefProps {\n  formRef?: FormRef\n}\n\nexport interface WidgetConfigProps extends FormRefProps {\n  config: WidgetConfig\n}\n\nexport interface WidgetConfigPartialProps {\n  config?: Partial<WidgetConfig>\n}\n\nexport type WidgetProps = WidgetDrawerProps &\n  WidgetConfig &\n  WidgetConfigPartialProps &\n  FormRefProps\n\nexport interface WidgetDrawerProps extends WidgetConfigPartialProps {\n  elementRef?: RefObject<HTMLDivElement>\n  open?: boolean\n  /**\n   * Make sure to make the onClose callback stable (e.g. using useCallback) to avoid causing re-renders of the entire widget\n   */\n  onClose?(): void\n}\n\nexport enum ExpansionType {\n  Routes = 'routes',\n  FromChain = 'fromChain',\n  ToChain = 'toChain',\n}\n"],"mappings":";AAieA,IAAY,gBAAL,yBAAA,eAAA;CACL,cAAA,YAAA;CACA,cAAA,eAAA;CACA,cAAA,aAAA;;AACF,EAAA,CAAA,CAAA"}
+{"version":3,"file":"widget.js","names":[],"sources":["../../../src/types/widget.ts"],"sourcesContent":["import type {\n  BaseToken,\n  ChainType,\n  ContractCall,\n  ExecutionOptions,\n  ExtendedChain,\n  Order,\n  Route,\n  RouteOptions,\n  SDKConfig,\n  StaticToken,\n  Token,\n} from '@lifi/sdk'\nimport type { WalletMenuOpenArgs } from '@lifi/wallet-management'\nimport type { WidgetProviderProps } from '@lifi/widget-provider'\nimport type {\n  Components,\n  PaletteMode,\n  PaletteOptions,\n  Shape,\n  SxProps,\n  Theme,\n} from '@mui/material'\nimport type { TypographyVariantsOptions } from '@mui/material/styles'\nimport type {\n  CSSProperties,\n  PropsWithChildren,\n  ReactNode,\n  RefObject,\n} from 'react'\nimport type {\n  LanguageKey,\n  LanguageResources,\n} from '../providers/I18nProvider/types.js'\nimport type { DefaultFieldValues } from '../stores/form/types.js'\n\nexport type WidgetVariant = 'compact' | 'wide' | 'drawer'\n\n/** @internal Not part of the public API. */\nexport type InternalWidgetMode = 'limit'\nexport type WidgetMode =\n  | 'default'\n  | 'split'\n  | 'custom'\n  | 'refuel'\n  | InternalWidgetMode\nexport type SplitMode = 'bridge' | 'swap'\nexport type SplitModeOptions = {\n  defaultTab: SplitMode\n}\nexport type CustomMode = 'checkout' | 'deposit'\nexport interface ModeOptions {\n  /**\n   * Configure split mode behavior:\n   * - 'bridge' | 'swap': Single mode without tabs\n   * - { defaultTab: 'bridge' | 'swap' }: Tabs mode with configurable default tab\n   */\n  split?: SplitMode | SplitModeOptions\n  custom?: { type: CustomMode }\n}\n\n/**\n * Identity of a header navigation tab. Each key maps to a widget variant, mode and\n * (optionally) mode options; labels are resolved from the key.\n */\nexport type SplitNavigationTabKey = SplitMode\n/** @internal Not part of the public API. */\nexport type InternalNavigationTabKey =\n  | 'default'\n  | 'private'\n  | 'refuel'\n  | 'swap-advanced'\n  | 'bridge-advanced'\n  | 'limit'\nexport type NavigationTabKey = InternalNavigationTabKey | SplitNavigationTabKey\n\nexport type Appearance = PaletteMode | 'system'\nexport interface NavigationProps {\n  /**\n   * If given, uses a negative margin to counteract the padding on sides for navigation elements like icon buttons.\n   * @default true\n   */\n  edge?: boolean\n}\nexport type WidgetThemeComponents = Partial<\n  Pick<\n    Components<Theme>,\n    | 'MuiAppBar'\n    | 'MuiAvatar'\n    | 'MuiButton'\n    | 'MuiCard'\n    | 'MuiDrawer'\n    | 'MuiIconButton'\n    | 'MuiInputCard'\n    | 'MuiNavigationTabs'\n    | 'MuiNavigationTab'\n    | 'MuiTabs'\n    | 'MuiCheckbox'\n  >\n>\n\nexport type WidgetTheme = {\n  colorSchemes?: {\n    light?: {\n      palette: PaletteOptions\n    }\n    dark?: {\n      palette: PaletteOptions\n    }\n  }\n  shape?: Partial<Shape>\n  typography?: TypographyVariantsOptions\n  components?: WidgetThemeComponents\n  container?: CSSProperties\n  routesContainer?: CSSProperties\n  chainSidebarContainer?: CSSProperties\n  header?: CSSProperties\n  navigation?: NavigationProps\n}\n\nexport interface DisabledUIConfig {\n  fromAmount?: boolean\n  fromToken?: boolean\n  toAddress?: boolean\n  toToken?: boolean\n}\n\nexport interface HiddenUIConfig {\n  addressBookConnectedWallets?: boolean\n  allNetworks?: boolean\n  appearance?: boolean\n  bridgesSettings?: boolean\n  chainSelect?: boolean\n  /**\n   * Hide the chain sidebar in the `wide` variant. No effect in other variants.\n   * @default false\n   */\n  chainSidebar?: boolean\n  contactSupport?: boolean\n  /**\n   * Hide the drawer close button. Only meaningful when `variant === 'drawer'`.\n   * @default false\n   */\n  drawerCloseButton?: boolean\n  fromToken?: boolean\n  gasRefuelMessage?: boolean\n  hideSmallBalances?: boolean\n  history?: boolean\n  insufficientGasMessage?: boolean\n  integratorStepDetails?: boolean\n  language?: boolean\n  /**\n   * Hide the warning shown when sending to an address with low historical\n   * on-chain activity (low transaction count or contract-like behavior).\n   * @default false\n   */\n  lowAddressActivityConfirmation?: boolean\n  poweredBy?: boolean\n  /**\n   * Hide the \"Recent searches\" section in the token select view.\n   * @default false\n   */\n  recentSearches?: boolean\n  reverseTokensButton?: boolean\n  routeCardPriceImpact?: boolean\n  routeTokenDescription?: boolean\n  searchTokenInput?: boolean\n  toAddress?: boolean\n  toToken?: boolean\n  walletMenu?: boolean\n}\n\nexport interface RequiredUIConfig {\n  accountDeployedMessage?: boolean\n  toAddress?: boolean\n}\n\nexport type DefaultUI = {\n  transactionDetailsExpanded?: boolean\n  navigationHeaderTitleNoWrap?: boolean\n  /**\n   * Layout for the main form.\n   * - `'default'`: the chain/token selectors plus single amount input.\n   * - `'cards'`: the redesigned card-based layout — stacked Send/Receive amount\n   *   cards (`AmountInputCardPair`) with inline token pill selectors and a swap\n   *   button.\n   * @default 'default'\n   */\n  layout?: 'default' | 'cards'\n}\n\nexport interface WidgetWalletConfig {\n  walletEcosystemsOrder?: Record<string, ChainType[]>\n  onConnect?(args?: WalletMenuOpenArgs): void\n  /**\n   * Determines whether the widget should provide partial wallet management functionality.\n   *\n   * In partial mode, external wallet management will be used for \"opt-out\" providers,\n   * while the internal management is applied for any remaining providers that do not opt out.\n   * This allows a flexible balance between the integrator's custom wallet menu and the widget's native wallet menu.\n   * @default false\n   */\n  usePartialWalletManagement?: boolean\n  /**\n   * This option forces the widget to always use internal wallet management ignoring external wallet management contexts\n   * @default false\n   */\n  forceInternalWalletManagement?: boolean\n}\n\nexport interface WidgetSDKConfig\n  extends Omit<\n    SDKConfig,\n    | 'apiKey'\n    | 'disableVersionCheck'\n    | 'integrator'\n    | 'providers'\n    | 'routeOptions'\n    | 'widgetVersion'\n  > {\n  routeOptions?: Omit<\n    RouteOptions,\n    'bridges' | 'exchanges' | 'fee' | 'referrer' | 'order' | 'slippage'\n  >\n  executionOptions?: Pick<ExecutionOptions, 'updateTransactionRequestHook'>\n}\n\nexport interface WidgetContractTool {\n  name: string\n  logoURI: string\n}\n\nexport interface CalculateFeeParams {\n  fromChain: ExtendedChain\n  toChain: ExtendedChain\n  fromToken: Token\n  toToken: Token\n  fromAddress?: string\n  toAddress?: string\n  fromAmount?: bigint\n  toAmount?: bigint\n  slippage?: number\n}\n\nexport interface WidgetFeeConfig {\n  name?: string\n  logoURI?: string\n  fee?: number\n  /**\n   * Whether to show the fee percentage in the fee details.\n   * @default false\n   */\n  showFeePercentage?: boolean\n  /**\n   * Whether to show a tooltip with the fee details. Requires `name` or `feeTooltipComponent` to be set.\n   * @default false\n   */\n  showFeeTooltip?: boolean\n  /**\n   * Custom tooltip component to show with the fee details.\n   */\n  feeTooltipComponent?: ReactNode\n  /**\n   * Function to calculate fees before fetching quotes.\n   * If provided, this function will be used instead of the `fee` parameter.\n   * Only one of `fee` or `calculateFee` should be used.\n   *\n   * @param params Object containing the fee calculation parameters\n   * @returns A promise that resolves to the calculated fee as a number (e.g., 0.03 represents a 3% fee)\n   */\n  calculateFee?(params: CalculateFeeParams): Promise<number | undefined>\n}\n\nexport interface ToAddress {\n  name?: string\n  address: string\n  chainType: ChainType\n  logoURI?: string\n}\n\nexport interface AllowDeny<T> {\n  allow?: T[]\n  deny?: T[]\n}\n\nexport type AllowDenySetItem = string | number\nexport interface AllowDenySet {\n  allow?: Set<AllowDenySetItem>\n  deny?: Set<AllowDenySetItem>\n}\n\nexport type AllowDenySets = {\n  from?: AllowDenySet\n  to?: AllowDenySet\n} & AllowDenySet\n\nexport type AllowDenyItems<T> = {\n  from?: AllowDeny<T>\n  to?: AllowDeny<T>\n} & AllowDeny<T>\n\nexport type WidgetChains = {\n  types?: AllowDeny<ChainType>\n} & AllowDenyItems<number>\n\nexport type WidgetTokens = {\n  featured?: StaticToken[]\n  include?: Token[]\n  popular?: StaticToken[]\n  verified?: BaseToken[]\n} & AllowDenyItems<BaseToken>\n\nexport type WidgetLanguages = {\n  default?: LanguageKey\n} & AllowDeny<LanguageKey>\n\nexport type PoweredByType = 'default' | 'jumper'\n\nexport interface RouteLabel {\n  text: string\n  sx?: SxProps<Theme>\n}\n\nexport interface RouteLabelRule {\n  label: RouteLabel\n  // Matching criteria\n  bridges?: AllowDeny<string>\n  exchanges?: AllowDeny<string>\n  fromChainId?: number[]\n  toChainId?: number[]\n  fromTokenAddress?: string[]\n  toTokenAddress?: string[]\n  /**\n   * Custom match function evaluated against the route. When provided, its\n   * result is AND'd with the other matching criteria — all specified\n   * conditions must pass for the label to apply. Use this for matching logic\n   * that the built-in fields cannot express (gas costs, step count, route\n   * tags, etc.).\n   */\n  match?: (route: Route) => boolean\n}\n\nexport type ExplorerUrl =\n  | string\n  | {\n      url: string\n      txPath?: string\n      addressPath?: string\n    }\n\nexport type WidgetProvider = (\n  props: PropsWithChildren<WidgetProviderProps>\n) => ReactNode\n\nexport interface WidgetConfig {\n  fromChain?: number\n  toChain?: number\n  fromToken?: string\n  toToken?: string\n  toAddress?: ToAddress\n  toAddresses?: ToAddress[]\n  fromAmount?: number | string\n  minFromAmountUSD?: number\n  toAmount?: number | string\n  formUpdateKey?: string\n\n  providers?: WidgetProvider[]\n\n  contractCalls?: ContractCall[]\n  contractComponent?: ReactNode\n  contractSecondaryComponent?: ReactNode\n  contractCompactComponent?: ReactNode\n  contractTool?: WidgetContractTool\n  integrator: string\n  apiKey?: string\n  feeConfig?: WidgetFeeConfig\n  referrer?: string\n\n  routePriority?: Order\n  slippage?: number\n\n  variant?: WidgetVariant\n  mode?: WidgetMode\n  modeOptions?: ModeOptions\n  /**\n   * Header navigation tabs, in order. When set, the widget renders a tab bar\n   * and the active tab drives the displayed flow. Each entry is a tab key.\n   *\n   * @internal Not part of the public API.\n   */\n  _navigationTabs?: NavigationTabKey[]\n\n  appearance?: Appearance\n  theme?: WidgetTheme\n\n  disabledUI?: DisabledUIConfig\n  hiddenUI?: HiddenUIConfig\n  requiredUI?: RequiredUIConfig\n  defaultUI?: DefaultUI\n  /**\n   * When true, shows only the recommended route and hides the route\n   * selector UI. Distinct from `routePriority`, which sets the SDK\n   * ranking order across multiple displayed routes.\n   * @default false\n   */\n  showSingleRoute?: boolean\n  useRelayerRoutes?: boolean\n\n  walletConfig?: WidgetWalletConfig\n  sdkConfig?: WidgetSDKConfig\n\n  buildUrl?: boolean\n  /**\n   * @deprecated Use `storageScopeKey` for persisted state and `queryScopeKey`\n   * for the query cache. Still honoured as the fallback for both.\n   */\n  keyPrefix?: string\n  /**\n   * Namespaces the widget's persisted state in `localStorage`: bookmarks,\n   * pinned tokens, recent tokens, chain order and route history, as\n   * `keyPrefix` does. Use a different value per widget instance that should\n   * keep its own state. Settings keep one shared name.\n   *\n   * It also scopes the widget's other queries (routes, tokens, balances, …),\n   * so instances with different values keep their data apart.\n   *\n   * Falls back to `keyPrefix`, then to the historical `li.fi-*` names.\n   */\n  storageScopeKey?: string\n  /**\n   * Scopes the widget's chains and tools queries inside the host's react-query\n   * `QueryClient`. Widget instances - and a host app using the\n   * `@lifi/widget/queries` factories - that pass the same value\n   * share those entries. The other widget queries are scoped by\n   * `storageScopeKey`.\n   *\n   * The keys start with a plain `'chains'` / `'tools'`, as in wagmi, so a host\n   * that matches on those roots (for example `setQueriesData({ queryKey:\n   * ['chains'] })`) also reaches the widget's entries.\n   *\n   * Falls back to `keyPrefix`, then to `'li.fi'`.\n   */\n  queryScopeKey?: string\n\n  bridges?: AllowDeny<string>\n  exchanges?: AllowDeny<string>\n  chains?: WidgetChains\n  tokens?: WidgetTokens\n  languages?: WidgetLanguages\n  languageResources?: LanguageResources\n  explorerUrls?: Record<number, ExplorerUrl[]> &\n    Partial<Record<'internal', ExplorerUrl[]>>\n  poweredBy?: PoweredByType\n\n  /**\n   * Custom labels/badges to show on routes based on specified rules\n   */\n  routeLabels?: RouteLabelRule[]\n}\n\nexport interface FormFieldOptions {\n  setUrlSearchParam: boolean\n}\n\nexport interface FieldValues\n  extends Omit<DefaultFieldValues, 'fromAmount' | 'toAmount' | 'toAddress'> {\n  fromAmount?: number | string\n  toAmount?: number | string\n  toAddress?: ToAddress | string\n}\n\nexport type FieldNames = keyof FieldValues\n\nexport type SetFieldValueFunction = <K extends FieldNames>(\n  key: K,\n  value: FieldValues[K],\n  options?: FormFieldOptions\n) => void\n\nexport type FormState = {\n  setFieldValue: SetFieldValueFunction\n}\n\nexport type FormRef = RefObject<FormState | null>\n\nexport interface FormRefProps {\n  formRef?: FormRef\n}\n\nexport interface WidgetConfigProps extends FormRefProps {\n  config: WidgetConfig\n}\n\nexport interface WidgetConfigPartialProps {\n  config?: Partial<WidgetConfig>\n}\n\nexport type WidgetProps = WidgetDrawerProps &\n  WidgetConfig &\n  WidgetConfigPartialProps &\n  FormRefProps\n\nexport interface WidgetDrawerProps extends WidgetConfigPartialProps {\n  elementRef?: RefObject<HTMLDivElement>\n  open?: boolean\n  /**\n   * Make sure to make the onClose callback stable (e.g. using useCallback) to avoid causing re-renders of the entire widget\n   */\n  onClose?(): void\n}\n\nexport enum ExpansionType {\n  Routes = 'routes',\n  FromChain = 'fromChain',\n  ToChain = 'toChain',\n}\n"],"mappings":";AA+fA,IAAY,gBAAL,yBAAA,eAAA;CACL,cAAA,YAAA;CACA,cAAA,eAAA;CACA,cAAA,aAAA;;AACF,EAAA,CAAA,CAAA"}

package/dist/esm/utils/queries.js.map

@@ -1 +1 @@
-{"version":3,"file":"queries.js","names":[],"sources":["../../../src/utils/queries.ts"],"sourcesContent":["export const getQueryKey = (key: string, prefix?: string) =>\n  `${prefix || 'li.fi'}-widget-${key}`\n"],"mappings":";AAAA,MAAa,eAAe,KAAa,WACvC,GAAG,UAAU,QAAQ,UAAU"}
+{"version":3,"file":"queries.js","names":[],"sources":["../../../src/utils/queries.ts"],"sourcesContent":["// Legacy keys: callers pass the storage scope, so instances stay apart.\nexport const getQueryKey = (key: string, prefix?: string) =>\n  `${prefix || 'li.fi'}-widget-${key}`\n"],"mappings":";AACA,MAAa,eAAe,KAAa,WACvC,GAAG,UAAU,QAAQ,UAAU"}

package/dist/esm/utils/scopeKeys.d.ts

@@ -0,0 +1,6 @@
+import { WidgetConfig } from "../types/widget.js";
+//#region src/utils/scopeKeys.d.ts
+type ScopeKeyConfig = Pick<WidgetConfig, "storageScopeKey" | "queryScopeKey" | "keyPrefix">;
+export declare const resolveStorageScopeKey: (config: Partial<ScopeKeyConfig> | undefined) => string | undefined;
+//#endregion
+//# sourceMappingURL=scopeKeys.d.ts.map

package/dist/esm/utils/scopeKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeKeys.d.ts","names":[],"sources":["../../../src/utils/scopeKeys.ts"],"mappings":";;KAKK,iBAAiB,KACpB;qBAKW,yBACX,QAAQ,QAAQ"}

package/dist/esm/utils/scopeKeys.js

@@ -0,0 +1,8 @@
+//#region src/utils/scopeKeys.ts
+const defaultQueryScopeKey = "li.fi";
+const resolveStorageScopeKey = (config) => config?.storageScopeKey ?? config?.keyPrefix;
+const resolveQueryScopeKey = (config) => config?.queryScopeKey ?? config?.keyPrefix ?? "li.fi";
+//#endregion
+export { defaultQueryScopeKey, resolveQueryScopeKey, resolveStorageScopeKey };
+
+//# sourceMappingURL=scopeKeys.js.map

package/dist/esm/utils/scopeKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeKeys.js","names":[],"sources":["../../../src/utils/scopeKeys.ts"],"sourcesContent":["import type { WidgetConfig } from '../types/widget.js'\n\n// Non-empty, so an unconfigured widget never shares a host's unscoped entries.\nexport const defaultQueryScopeKey = 'li.fi'\n\ntype ScopeKeyConfig = Pick<\n  WidgetConfig,\n  'storageScopeKey' | 'queryScopeKey' | 'keyPrefix'\n>\n\n// `undefined` keeps the historical `li.fi-*` store names.\nexport const resolveStorageScopeKey = (\n  config: Partial<ScopeKeyConfig> | undefined\n): string | undefined => config?.storageScopeKey ?? config?.keyPrefix\n\nexport const resolveQueryScopeKey = (\n  config: Partial<ScopeKeyConfig> | undefined\n): string => config?.queryScopeKey ?? config?.keyPrefix ?? defaultQueryScopeKey\n"],"mappings":";AAGA,MAAa,uBAAuB;AAQpC,MAAa,0BACX,WACuB,QAAQ,mBAAmB,QAAQ;AAE5D,MAAa,wBACX,WACW,QAAQ,iBAAiB,QAAQ,aAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/widget",
-  "version": "4.7.1",
+  "version": "4.8.0",
   "description": "LI.FI Widget for cross-chain bridging and swapping. It will drive your multi-chain strategy and attract new users from everywhere.",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -21,6 +21,11 @@
       "import": "./dist/esm/shared.js",
       "default": "./dist/esm/shared.js"
     },
+    "./queries": {
+      "types": "./dist/esm/queries/index.d.ts",
+      "import": "./dist/esm/queries/index.js",
+      "default": "./dist/esm/queries/index.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -52,9 +57,9 @@
   "dependencies": {
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.1",
-    "@lifi/sdk": "^4.8.0",
-    "@lifi/wallet-management": "4.3.0",
-    "@lifi/widget-provider": "4.5.0",
+    "@lifi/sdk": "^4.10.0",
+    "@lifi/wallet-management": "4.3.1",
+    "@lifi/widget-provider": "4.5.1",
     "@mui/icons-material": "^9.4.0",
     "@mui/material": "^9.4.0",
     "@mui/system": "^9.4.0",
@@ -82,6 +87,9 @@
       ],
       "shared": [
         "./dist/esm/shared.d.ts"
+      ],
+      "queries": [
+        "./dist/esm/queries/index.d.ts"
       ]
     }
   },

package/src/config/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/widget'
-export const version = '4.7.1'
+export const version = '4.8.0'

package/src/hooks/useAvailableChains.test.tsx

@@ -0,0 +1,170 @@
+/** @vitest-environment happy-dom */
+
+import type * as LifiSdk from '@lifi/sdk'
+import { ChainType, type ExtendedChain, type SDKClient } from '@lifi/sdk'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { WidgetConfig } from '../types/widget.js'
+
+/**
+ * The chains entry is shared with the host app through
+ * `getChainsQueryOptions`, keyed by the client's API base, the requested chain
+ * types and the widget's `queryScopeKey`. The widget's own SDK client still
+ * gets the chains, whoever filled the entry.
+ */
+
+const API_URL = 'https://api.example/v1'
+
+const mocks = vi.hoisted(() => ({
+  getChains: vi.fn(),
+  setChains: vi.fn(),
+}))
+
+vi.mock('@lifi/sdk', async (importOriginal) => ({
+  ...(await importOriginal<typeof LifiSdk>()),
+  getChains: mocks.getChains,
+}))
+
+let widgetConfig: Partial<WidgetConfig> = {}
+
+vi.mock('../providers/WidgetProvider/WidgetProvider.js', () => ({
+  useWidgetConfig: () => widgetConfig,
+}))
+
+const client = {
+  config: { apiUrl: API_URL },
+  setChains: mocks.setChains,
+} as unknown as SDKClient
+vi.mock('../providers/SDKClientProvider.js', () => ({
+  useSDKClient: () => client,
+}))
+
+import { getChainsQueryKey } from '../queries/getChains.js'
+import { useAvailableChains } from './useAvailableChains.js'
+
+const CHAINS = [{ id: 1, name: 'Ethereum' }] as ExtendedChain[]
+
+let root: Root
+let queryClient: QueryClient
+let externalConfig: WidgetConfig | undefined
+
+const Probe = () => {
+  useAvailableChains(undefined, externalConfig)
+  return null
+}
+
+const render = async () => {
+  await act(async () => {
+    root.render(
+      <QueryClientProvider client={queryClient}>
+        <Probe />
+      </QueryClientProvider>
+    )
+  })
+}
+
+const evmKey = getChainsQueryKey({
+  apiUrl: API_URL,
+  chainTypes: [ChainType.EVM],
+  scopeKey: 'host',
+})
+
+describe('useAvailableChains', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.getChains.mockResolvedValue(CHAINS)
+    widgetConfig = {
+      queryScopeKey: 'host',
+      chains: { types: { allow: [ChainType.EVM] } },
+    }
+    externalConfig = undefined
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    await act(async () => root.unmount())
+    queryClient.clear()
+  })
+
+  it('fetches the allowed chain types under the widget scope and hands them to the client', async () => {
+    await render()
+
+    await vi.waitFor(() => {
+      expect(mocks.setChains).toHaveBeenCalledWith(CHAINS)
+    })
+    expect(mocks.getChains).toHaveBeenCalledWith(client, {
+      chainTypes: [ChainType.EVM],
+    })
+    expect(queryClient.getQueryData(evmKey)).toBe(CHAINS)
+  })
+
+  it('reads an entry the host filled, and still hands the chains to the client', async () => {
+    queryClient.setQueryData(evmKey, CHAINS)
+
+    await render()
+
+    await vi.waitFor(() => {
+      expect(mocks.setChains).toHaveBeenCalledWith(CHAINS)
+    })
+    expect(mocks.getChains).not.toHaveBeenCalled()
+  })
+
+  it('hands the chains to the client again after a refetch with equal data', async () => {
+    // Structural sharing keeps the data reference on an equal refetch. The
+    // client's own chain storage expires, so every fetch must refresh it.
+    await render()
+    await vi.waitFor(() => {
+      expect(mocks.setChains).toHaveBeenCalledTimes(1)
+    })
+
+    await act(async () => {
+      await queryClient.refetchQueries({ queryKey: evmKey })
+    })
+
+    await vi.waitFor(() => {
+      expect(mocks.setChains).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  it('refreshes the chains every five minutes', async () => {
+    await render()
+    await vi.waitFor(() => {
+      expect(queryClient.getQueryData(evmKey)).toBe(CHAINS)
+    })
+
+    const [observer] = queryClient
+      .getQueryCache()
+      .find({ queryKey: evmKey })!.observers
+    expect(observer.options.refetchInterval).toBe(300_000)
+    expect(observer.options.staleTime).toBe(300_000)
+  })
+
+  it('uses the API base and scope of an external widget config', async () => {
+    externalConfig = {
+      integrator: 'partner',
+      keyPrefix: 'partner',
+      sdkConfig: { apiUrl: 'https://partner.example/v1' },
+      chains: { types: { allow: [ChainType.SVM] } },
+    }
+
+    await render()
+
+    const partnerKey = getChainsQueryKey({
+      apiUrl: 'https://partner.example/v1',
+      chainTypes: [ChainType.SVM],
+      scopeKey: 'partner',
+    })
+    await vi.waitFor(() => {
+      expect(queryClient.getQueryData(partnerKey)).toBe(CHAINS)
+    })
+    // The external config's own client, not the widget's.
+    expect(mocks.getChains.mock.calls[0][0]).not.toBe(client)
+  })
+})

package/src/hooks/useAvailableChains.ts

@@ -1,26 +1,23 @@
-import type { ExtendedChain } from '@lifi/sdk'
-import { ChainType, createClient, getChains } from '@lifi/sdk'
+import type { ChainType, ExtendedChain } from '@lifi/sdk'
+import { createClient } from '@lifi/sdk'
 import { useQuery } from '@tanstack/react-query'
 import { useCallback, useEffect, useMemo } from 'react'
 import { useSDKClient } from '../providers/SDKClientProvider.js'
 import { useWidgetConfig } from '../providers/WidgetProvider/WidgetProvider.js'
+import {
+  getChainsQueryOptions,
+  supportedChainTypes,
+} from '../queries/getChains.js'
 import type { WidgetConfig } from '../types/widget.js'
 import { getConfigItemSets, isItemAllowedForSets } from '../utils/item.js'
-import { getQueryKey } from '../utils/queries.js'
+import { resolveQueryScopeKey } from '../utils/scopeKeys.js'
 
 type GetChainById = (
   chainId?: number,
   chains?: ExtendedChain[]
 ) => ExtendedChain | undefined
 
-const supportedChainTypes = [
-  ChainType.EVM,
-  ChainType.SVM,
-  ChainType.UTXO,
-  ChainType.MVM,
-  ChainType.TVM,
-  ChainType.STL,
-]
+const refetchInterval = 300_000
 
 export const useAvailableChains = (
   chainTypes?: ChainType[],
@@ -30,7 +27,7 @@ export const useAvailableChains = (
   getChainById: GetChainById
   isLoading: boolean
 } => {
-  const { chains: internalChains, keyPrefix: internalKeyPrefix } =
+  const { chains: internalChains, queryScopeKey: internalQueryScopeKey } =
     useWidgetConfig()
   const internalClient = useSDKClient()
 
@@ -46,46 +43,31 @@ export const useAvailableChains = (
   }, [widgetConfig])
 
   // Overwrite widget config if passed as param
-  const keyPrefix = widgetConfig?.keyPrefix ?? internalKeyPrefix
+  const client = externalClient ?? internalClient
   const chains = widgetConfig?.chains ?? internalChains
+  const queryScopeKey = widgetConfig
+    ? resolveQueryScopeKey(widgetConfig)
+    : internalQueryScopeKey
 
-  const { data, isLoading } = useQuery({
-    queryKey: [
-      getQueryKey('chains', keyPrefix),
-      chains?.types,
-      chains?.allow,
-      chains?.deny,
-      chains?.from,
-      chains?.to,
-      !!externalClient,
-    ] as const,
-    queryFn: async ({ queryKey: [, chainTypesConfig] }) => {
-      const chainsConfigSets = getConfigItemSets(
-        chainTypesConfig,
-        (chains) => new Set(chains)
-      )
-      const chainTypesRequest = supportedChainTypes.filter((chainType) =>
-        isItemAllowedForSets(chainType, chainsConfigSets)
-      )
-      const client = externalClient ?? internalClient
-      const availableChains = await getChains(client, {
-        chainTypes: chainTypes || chainTypesRequest,
-      })
-      client.setChains(availableChains)
-      return availableChains
-    },
-    refetchInterval: 300_000,
-    staleTime: 300_000,
-  })
+  const typeSets = getConfigItemSets(chains?.types, (types) => new Set(types))
+  const requestedTypes =
+    chainTypes ??
+    supportedChainTypes.filter((type) => isItemAllowedForSets(type, typeSets))
+
+  const { data, dataUpdatedAt, isLoading } = useQuery(
+    getChainsQueryOptions(client, {
+      chainTypes: requestedTypes,
+      scopeKey: queryScopeKey,
+      query: { refetchInterval, staleTime: refetchInterval },
+    })
+  )
 
-  // Ensure the current internal client always has chains, even when:
-  // - the query result came from cache (external call populated it first)
-  // - the client was recreated due to config changes (stale closure in queryFn)
+  // A host may fill the entry; key on dataUpdatedAt, as a refetch keeps data.
   useEffect(() => {
-    if (data && !externalClient) {
-      internalClient.setChains(data)
+    if (data && dataUpdatedAt) {
+      client.setChains(data)
     }
-  }, [data, externalClient, internalClient])
+  }, [data, dataUpdatedAt, client])
 
   const getChainById: GetChainById = useCallback(
     (chainId?: number, chains: ExtendedChain[] | undefined = data) => {

package/src/hooks/useFromTokenSufficiency.ts

@@ -22,7 +22,7 @@ export const useFromTokenSufficiency = (
     'fromToken',
     'fromAmount'
   )
-  const { keyPrefix } = useWidgetConfig()
+  const { storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
 
   let chainId = fromChainId
@@ -42,7 +42,7 @@ export const useFromTokenSufficiency = (
 
   const { data: insufficientFromToken, isLoading } = useQuery({
     queryKey: [
-      getQueryKey('from-token-sufficiency-check', keyPrefix),
+      getQueryKey('from-token-sufficiency-check', storageScopeKey),
       account.address,
       chainId,
       tokenAddress,

package/src/hooks/useGasRecommendation.ts

@@ -14,7 +14,7 @@ export const useGasRecommendation = (
   fromToken?: string
 ): UseQueryResult<Awaited<ReturnType<typeof getGasRecommendation>> | null> => {
   const { chains } = useAvailableChains()
-  const { keyPrefix, hiddenUI } = useWidgetConfig()
+  const { storageScopeKey, hiddenUI } = useWidgetConfig()
   const sdkClient = useSDKClient()
 
   const checkRecommendationLiFuel =
@@ -28,7 +28,7 @@ export const useGasRecommendation = (
 
   return useQuery({
     queryKey: [
-      getQueryKey('gas-recommendation', keyPrefix),
+      getQueryKey('gas-recommendation', storageScopeKey),
       toChainId,
       fromChain,
       fromToken,

package/src/hooks/useGasSufficiency.ts

@@ -32,7 +32,7 @@ export const useGasSufficiency = (
   const { account: EVMAccount, accounts } = useAccount({
     chainType: ChainType.EVM,
   })
-  const { keyPrefix, hiddenUI } = useWidgetConfig()
+  const { storageScopeKey, hiddenUI } = useWidgetConfig()
   const sdkClient = useSDKClient()
 
   const { relevantAccounts, relevantAccountsQueryKey } = useMemo(() => {
@@ -67,7 +67,7 @@ export const useGasSufficiency = (
 
   const { data: insufficientGas, isLoading } = useQuery<GasSufficiency[]>({
     queryKey: [
-      getQueryKey('gas-sufficiency-check', keyPrefix),
+      getQueryKey('gas-sufficiency-check', storageScopeKey),
       relevantAccountsQueryKey,
       route?.id,
       isContractAddress,

package/src/hooks/useIsBatchingSupported.ts

@@ -13,7 +13,7 @@ export function useIsBatchingSupported(
   isBatchingSupported: boolean | undefined
   isBatchingSupportedLoading: boolean
 } {
-  const { keyPrefix } = useWidgetConfig()
+  const { storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
   const { isBatchingSupported } = useEthereumContext()
 
@@ -22,7 +22,7 @@ export function useIsBatchingSupported(
   )
   const { data, isLoading } = useQuery({
     queryKey: [
-      getQueryKey('isBatchingSupported', keyPrefix),
+      getQueryKey('isBatchingSupported', storageScopeKey),
       chain?.id,
       address,
     ],

package/src/hooks/useRouteExecution.ts

@@ -43,7 +43,7 @@ export const useRouteExecution = ({
   const queryClient = useQueryClient()
   const { account } = useAccount()
   const resumedAfterMount = useRef(false)
-  const { keyPrefix } = useWidgetConfig()
+  const { storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
   const emitter = useWidgetEvents()
   const routeExecutionStoreContext = useRouteExecutionStoreContext()
@@ -84,16 +84,16 @@ export const useRouteExecution = ({
     if (executionCompleted || executionFailed) {
       const invalidateKeys = [
         [
-          getQueryKey('token-balances', keyPrefix),
+          getQueryKey('token-balances', storageScopeKey),
           clonedUpdatedRoute.fromAddress,
           clonedUpdatedRoute.fromChainId,
         ],
         [
-          getQueryKey('token-balances', keyPrefix),
+          getQueryKey('token-balances', storageScopeKey),
           clonedUpdatedRoute.toAddress,
           clonedUpdatedRoute.toChainId,
         ],
-        [getQueryKey('transaction-history', keyPrefix)],
+        [getQueryKey('transaction-history', storageScopeKey)],
       ]
       for (const key of invalidateKeys) {
         queryClient.invalidateQueries(
@@ -133,7 +133,7 @@ export const useRouteExecution = ({
         throw new Error('Execution route not found.')
       }
       queryClient.removeQueries({
-        queryKey: [getQueryKey('routes', keyPrefix)],
+        queryKey: [getQueryKey('routes', storageScopeKey)],
         exact: false,
       })
       return executeRoute(sdkClient, routeExecution.route, {

package/src/hooks/useRoutes.ts

@@ -82,7 +82,7 @@ export const useRoutes = ({
     exchanges,
     feeConfig,
     useRelayerRoutes,
-    keyPrefix,
+    storageScopeKey,
   } = useWidgetConfig()
   const sdkClient = useSDKClient()
   const setExecutableRoute = useSetExecutableRoute()
@@ -214,7 +214,7 @@ export const useRoutes = ({
   const queryKey = useMemo(
     () =>
       [
-        getQueryKey('routes', keyPrefix),
+        getQueryKey('routes', storageScopeKey),
         effectiveFromAddress,
         fromChain?.id as number,
         fromToken?.address as string,
@@ -244,7 +244,7 @@ export const useRoutes = ({
         observableRoute?.id,
       ] as const,
     [
-      keyPrefix,
+      storageScopeKey,
       effectiveFromAddress,
       fromChain?.id,
       fromToken?.address,
@@ -550,14 +550,14 @@ export const useRoutes = ({
         ;[fromToken, toToken].forEach((token) => {
           // Update main tokens cache (verified)
           queryClient.setQueriesData<TokensByChain>(
-            { queryKey: [getQueryKey('tokens', keyPrefix)] },
+            { queryKey: [getQueryKey('tokens', storageScopeKey)] },
             (data) => updateTokenInCache(data, token)
           )
 
           // Update search tokens cache (unverified) - matches any search query
           queryClient.setQueriesData<TokensByChain>(
             {
-              queryKey: [getQueryKey('tokens-search', keyPrefix)],
+              queryKey: [getQueryKey('tokens-search', storageScopeKey)],
               exact: false,
             },
             (data) => updateTokenInCache(data, token)
@@ -566,7 +566,7 @@ export const useRoutes = ({
           queryClient.setQueriesData<Token[]>(
             {
               queryKey: [
-                getQueryKey('token-balances', keyPrefix),
+                getQueryKey('token-balances', storageScopeKey),
                 fromAddress,
                 token.chainId,
               ],

package/src/hooks/useTokenBalance.ts

@@ -23,18 +23,18 @@ export const useTokenBalance = (
   getTokenBalancesWithRetry: typeof getTokenBalancesWithRetry
 } => {
   const queryClient = useQueryClient()
-  const { keyPrefix } = useWidgetConfig()
+  const { storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
 
   const tokenBalanceQueryKey = useMemo(
     () =>
       [
-        getQueryKey('token-balance', keyPrefix),
+        getQueryKey('token-balance', storageScopeKey),
         accountAddress,
         token?.chainId,
         token?.address,
       ] as const,
-    [token?.address, token?.chainId, accountAddress, keyPrefix]
+    [token?.address, token?.chainId, accountAddress, storageScopeKey]
   )
 
   const { data, isLoading, refetch } = useQuery({
@@ -67,7 +67,7 @@ export const useTokenBalance = (
       queryClient.setQueriesData<TokenAmount[]>(
         {
           queryKey: [
-            getQueryKey('token-balances', keyPrefix),
+            getQueryKey('token-balances', storageScopeKey),
             accountAddress,
             tokenChainId,
           ],