Skip to main content

Wallet management

Configure your widget for seamless wallet management.

The widget ships a built-in wallet management UI, so users can connect a wallet and use the widget as a standalone mini dApp out of the box.

When you embed the widget inside your own dApp, reusing your existing wallet UX (same connect modal, same account state, same chain switching) usually gives the best experience.

There are several ecosystems and chain families supported by the widget (EVM, SVM, UTXO, Sui), and wallet connection may use different stacks under the hood per ecosystem.

EVM wallet connection​

To manage wallet connection to EVM chains, switching chains, and related flows, the widget uses wagmi internally. It also aims for first-class compatibility with common wagmi-based integrations, including:

Reusing your dApp’s Wagmi stack (zero extra wiring)​

If your dApp already manages wallets with wagmi or a wagmi-based library above, and the widget detects that it is rendered inside a WagmiProvider context, it can reuse your wallet management without additional configuration.

Mount your existing provider tree above BlinqWidget (same React subtree), for example:

import { BlinqWidget } from '@routerprotocol/xplore-widget';
import '@routerprotocol/xplore-widget/style.css';

function SwapPage() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <RainbowKitProvider>
        <BlinqWidget
          config={{
            apiUrl: 'https://grpc-v2.routerprotocol.com',
            networkConfigUrl: '/api/networks',
          }}
        />
      </RainbowKitProvider>
    </WagmiProvider>
  );
}
Same modal everywhere

Keep one connect flow for your whole app: your header/account button and the widget should open the same wallet UI (RainbowKit’s connect modal, Dynamic’s auth flow, AppKit modal, etc.).

Solana (SVM), Bitcoin (UTXO), and Sui​

For non-EVM ecosystems, wallet connection flows differ from EVM/wagmi. When you embed the widget:

  • Prefer mounting the widget inside the same provider layout your app already uses for that ecosystem (if any).
  • If your app uses a custom connect flow or a wallet stack the widget cannot auto-bridge to, use config.wallet.onConnectClick (see below) so the widget delegates “connect” to your host UI.

Explicit host connect (onConnectClick)​

When you need the widget to always call into your app for connect—custom modals, non-wagmi stacks, or you want to force a single host-owned entry point—pass config.wallet.onConnectClick. The widget invokes it when it needs the user to connect.

<BlinqWidget
  config={{
    apiUrl: 'https://grpc-v2.routerprotocol.com',
    networkConfigUrl: '/api/networks',
    wallet: {
      onConnectClick: () => hostOpenWalletModal(),
    },
  }}
/>;

Best practices​

  • Keep onConnectClick UI-only (open modal); avoid long async work inside the handler.
  • Keep config stable across renders (memoize the config object) to avoid resetting wallet state unnecessarily.
  • If you use WidgetProvider, keep wallet providers outside (wrapping) it so context stays consistent across re-renders.

Troubleshooting​

Connect does nothing​

  • If you rely on host connect, verify wallet.onConnectClick is provided and actually opens your modal.
  • If you rely on Wagmi reuse, verify BlinqWidget is a descendant of WagmiProvider and your wagmi config includes the chains you expose in networkConfigUrl / supportedChainIds.

Chains or wallets look wrong​

  • Confirm your networkConfigUrl payload includes the chains you expect.
  • If supportedChainIds is set, ensure ids match your network config (including non‑EVM identifiers such as solana).