Layerswap Docs

This page applies only to the self-bundled @layerswap/widget integration. The loader packages do not accept custom wallet-provider factories. If your EVM wallet manager exposes a wagmi Config, use Sharing your wagmi config instead.

Use custom wallet management when your application already owns the wallet UI and connection lifecycle through a service such as Dynamic, Privy, or another host-managed wallet SDK. The current API is store-based. A chain factory receives customConnection, which creates a WalletConnectionStore backed by a vanilla Zustand store. The previous customHook and walletConnectionProvider fields are no longer part of the provider contract. The chain factory still supplies its normal balance, gas, transfer, gasless, and other resolvers. customConnection replaces only its connection state.

Choose the integration shape

You read your wallet SDK through React hooks: return a WalletConnectionProvider snapshot from a custom hook, bridge it with createReactHookConnectionAdapter, and render the adapter’s Hydrator.
Your wallet SDK exposes an external store or event API: create the vanilla Zustand store directly and return a WalletConnectionStore. No hydrator is needed.

The repository’s Dynamic Starknet example uses the React-hook adapter described below.

Adapt a React hook

1. Install the eager chain package

Custom connections are configured on a chain’s eager provider factory. Import that factory from its chain package, not a lazy descriptor from @layerswap/wallets:

npm install @layerswap/widget @layerswap/widget-types @layerswap/wallet-starknet \
  @dynamic-labs/sdk-react-core @dynamic-labs/starknet

Replace @layerswap/wallet-starknet with the package for the chain family you are adapting.

Next.js hosts must add @layerswap/widget, @layerswap/widget-types, @layerswap/utils, @layerswap/ui-kit, @layerswap/wallet-core, and every installed @layerswap/wallet-* package to transpilePackages. The published next builds contain extensionless ESM imports that Node’s SSR loader can otherwise reject with ERR_MODULE_NOT_FOUND, often for a path ending in /knownIds. See Build troubleshooting for the configuration.

2. Return the current connection snapshot

The hook translates third-party wallet state into WalletConnectionProvider. Both files below belong to the integrating application: the first adapts Dynamic’s React state, and the second turns a generic Dynamic wallet into the concrete Starknet account required by Layerswap.

Wallet hook
Account adapter

useCustomStarknet.ts

import { useCallback, useEffect, useMemo, useState } from 'react';
import {
  dynamicEvents,
  useDynamicContext,
  useUserWallets,
  type Wallet as DynamicWallet,
} from '@dynamic-labs/sdk-react-core';
import {
  isStarknetWallet,
  type StarknetWallet,
} from '@dynamic-labs/starknet';
import {
  createReactHookConnectionAdapter,
  resolveWalletConnectorIcon,
} from '@layerswap/widget/internal';
import type { Wallet } from '@layerswap/widget-types';
import type {
  WalletConnectionProvider,
  WalletConnectionProviderProps,
} from '@layerswap/widget/types';
import {
  resolveStarknetAccount,
  type DynamicStarknetAccount,
} from './resolveStarknetAccount';

const STARKNET_NETWORKS = ['STARKNET_MAINNET', 'STARKNET_SEPOLIA'];

type ResolvedConnection = {
  connection: StarknetWallet;
  account: DynamicStarknetAccount;
};

function getWalletId(connection: DynamicWallet): string | undefined {
  const address = connection.address;
  const connectorName = connection.connector.name;
  return address && connectorName ? `${connectorName}:${address}` : undefined;
}

function useCustomStarknet({
  networks,
}: WalletConnectionProviderProps): WalletConnectionProvider {
  const { setShowAuthFlow, handleLogOut } = useDynamicContext();
  const externalWallets = useUserWallets();
  const starknetWallets = useMemo(
    () => externalWallets.filter(isStarknetWallet),
    [externalWallets],
  );

  const supportedNetworks = useMemo(
    () =>
      STARKNET_NETWORKS.filter((name) =>
        networks.some((network) => network.name === name),
      ),
    [networks],
  );

  const disconnectWallets = useCallback(async () => {
    await handleLogOut();
  }, [handleLogOut]);

  const mapWallet = useCallback(
    (
      connection: DynamicWallet,
      isActive: boolean,
      starknetAccount: DynamicStarknetAccount,
    ): Wallet | undefined => {
      if (!isStarknetWallet(connection)) return;

      const address = connection.address;
      const connectorName = connection.connector.name;
      if (!address || !connectorName) return;

      return {
        id: `${connectorName}:${address}`,
        isActive,
        address,
        addresses: [address],
        displayName: `${connectorName} - Starknet`,
        providerName: 'Starknet',
        icon: resolveWalletConnectorIcon({
          iconUrl: connection.connector.metadata.icon,
        }),
        disconnect: disconnectWallets,
        asSourceSupportedNetworks: supportedNetworks,
        autofillSupportedNetworks: supportedNetworks,
        withdrawalSupportedNetworks: supportedNetworks,
        networkIcon: networks.find((network) =>
          supportedNetworks.includes(network.name),
        )?.logo,
        // This must be the resolved account, not getWalletAccount()'s Promise.
        metadata: { starknetAccount },
      };
    },
    [disconnectWallets, networks, supportedNetworks],
  );

  const walletSetKey = useMemo(
    () =>
      starknetWallets
        .map(getWalletId)
        .filter((id): id is string => Boolean(id))
        .join('|'),
    [starknetWallets],
  );

  const [resolution, setResolution] = useState<{
    walletSetKey: string;
    connections: ResolvedConnection[];
  }>({ walletSetKey: '', connections: [] });

  useEffect(() => {
    let cancelled = false;

    const loadAccounts = async () => {
      const connections = (
        await Promise.all(
          starknetWallets.map(async (connection) => {
            const id = getWalletId(connection);
            if (!id) return;

            const account = await resolveStarknetAccount(connection);
            return account ? { connection, account } : undefined;
          }),
        )
      ).filter(
        (item): item is ResolvedConnection => item !== undefined,
      );

      if (!cancelled) setResolution({ walletSetKey, connections });
    };

    void loadAccounts().catch((error) => {
      if (!cancelled) {
        setResolution({ walletSetKey, connections: [] });
        console.error('Unable to initialize Dynamic Starknet accounts', error);
      }
    });

    return () => {
      cancelled = true;
    };
  }, [starknetWallets, walletSetKey]);

  const connectedWallets = useMemo<Wallet[] | undefined>(() => {
    // `undefined` tells the Widget that a restored session is still resolving.
    if (resolution.walletSetKey !== walletSetKey) return undefined;

    return resolution.connections
      .map(({ connection, account }, index) =>
        mapWallet(connection, index === 0, account),
      )
      .filter((wallet): wallet is Wallet => Boolean(wallet));
  }, [mapWallet, resolution, walletSetKey]);

  const connectWallet = useCallback(async (): Promise<Wallet | undefined> => {
    const connection = await new Promise<DynamicWallet | undefined>((resolve) => {
      const cleanup = () => {
        dynamicEvents.off('walletAdded', onAdded);
        dynamicEvents.off('authFlowCancelled', onCancelled);
      };
      const onAdded = (wallet: DynamicWallet) => {
        cleanup();
        resolve(wallet);
      };
      // Cancellation is a normal no-connection result. Do not reject here:
      // the Widget awaits connector-less calls without a rejection handler.
      const onCancelled = () => {
        cleanup();
        resolve(undefined);
      };

      dynamicEvents.on('walletAdded', onAdded);
      dynamicEvents.on('authFlowCancelled', onCancelled);
      setShowAuthFlow(true);
    });
    if (!connection) return undefined;

    const account = await resolveStarknetAccount(connection);
    return account ? mapWallet(connection, true, account) : undefined;
  }, [mapWallet, setShowAuthFlow]);

  const providerIcon = networks.find((network) =>
    supportedNetworks.includes(network.name),
  )?.logo;

  return {
    id: 'starknet',
    name: 'Starknet',
    ready: true, // Use the SDK's initialization state when it exposes one.
    providerIcon,
    connectWallet,
    disconnectWallets,
    connectedWallets,
    activeWallet: connectedWallets?.find((wallet) => wallet.isActive),
    asSourceSupportedNetworks: supportedNetworks,
    autofillSupportedNetworks: supportedNetworks,
    withdrawalSupportedNetworks: supportedNetworks,
  };
}

// Create this adapter once, outside a component.
export const customStarknetAdapter =
  createReactHookConnectionAdapter(useCustomStarknet);

resolveStarknetAccount.ts

import type { Wallet as DynamicWallet } from '@dynamic-labs/sdk-react-core';
import {
  isStarknetWallet,
  type StarknetWallet,
} from '@dynamic-labs/starknet';

export type DynamicStarknetAccount = Awaited<
  ReturnType<StarknetWallet['getWalletAccount']>
>;

export async function resolveStarknetAccount(
  connection: DynamicWallet,
): Promise<DynamicStarknetAccount | undefined> {
  if (!isStarknetWallet(connection)) return undefined;

  return connection.getWalletAccount();
}

createReactHookConnectionAdapter creates one singleton store per adapter. Create the adapter once, outside a component. Two Widget instances that use the same adapter also share that connection store and its state. Dynamic’s getWalletAccount() is asynchronous. Resolve it before assigning metadata.starknetAccount; do not assign the promise itself. The resulting account supplies the estimateInvokeFee and execute methods used by the default Starknet gas and transfer resolvers. If your wallet SDK does not expose a compatible Starknet account, leave asSourceSupportedNetworks and withdrawalSupportedNetworks empty so the Widget does not offer a signing flow it cannot complete, or replace the default gas and transfer resolvers. ready should stay false until the third-party SDK can service connection requests. Use connectedWallets: undefined while restoring an unknown session and connectedWallets: [] once initialization has finished with no connected wallet. The Widget shows a restoring state while the value is undefined; if the SDK’s account resolution never settles, the wallet UI remains blocked, so consider applying a timeout. This sample marks only the first resolved wallet as isActive and does not implement switchAccount. The Widget therefore cannot switch between multiple Dynamic wallets. Implement switchAccount and keep isActive and activeWallet synchronized if your integration needs account switching.

3. Render the hydrator

The adapter’s Hydrator runs the hook and mirrors each snapshot into the external store. It must be inside both the third-party SDK provider and LayerswapProvider, because it consumes both contexts. Its props also require a network adapter.

walletNetworkAdapter.ts

import { NetworkType, type NetworkWithTokens } from '@layerswap/widget-types';
import type { WalletConnectionProviderProps } from '@layerswap/widget/types';

type NetworkAdapter =
  WalletConnectionProviderProps<NetworkWithTokens>['networkAdapter'];

export const walletNetworkAdapter: NetworkAdapter = {
  getId: (network) => network.name,
  getDisplayName: (network) => network.display_name,
  getChainId: (network) => network.chain_id,
  getRpcUrls: (network) =>
    network.nodes?.length ? network.nodes : [network.node_url].filter(Boolean),
  getIcon: (network) => network.logo,
  getTransactionExplorerUrl: (network) =>
    network.transaction_explorer_template,
  getAccountExplorerUrl: (network) => network.account_explorer_template,
  getNativeCurrency: (network) =>
    network.token && {
      symbol: network.token.symbol,
      decimals: network.token.decimals,
    },
  getMulticallAddress: (network) =>
    network.metadata?.evm_multicall_contract ?? undefined,
  isEvmNetwork: (network) => network.type === NetworkType.EVM,
  isSolanaNetwork: (network) => network.type === NetworkType.Solana,
  isStarknetNetwork: (network) => network.type === NetworkType.Starknet,
  isTronNetwork: (network) => network.type === NetworkType.Tron,
  isBitcoinNetwork: (network) => network.type === NetworkType.Bitcoin,
  isTonNetwork: (network) => network.type === NetworkType.TON,
  isFuelNetwork: (network) => network.type === NetworkType.Fuel,
};

networkAdapter is required by the Hydrator contract, but the Widget does not currently export the adapter it uses internally. This host-side copy mirrors the Widget’s NetworkWithTokens adapter and derives its type through WalletConnectionProviderProps, so the host does not need a direct @layerswap/wallet-core dependency for the adapter type.

CustomStarknetHydrator.tsx

'use client';

import { useSettingsState } from '@layerswap/widget';
import { customStarknetAdapter } from './useCustomStarknet';
import { walletNetworkAdapter } from './walletNetworkAdapter';

export function CustomStarknetHydrator() {
  const { networks } = useSettingsState();
  return (
    <customStarknetAdapter.Hydrator
      networks={networks}
      networkAdapter={walletNetworkAdapter}
    />
  );
}

Render this Hydrator only on the client. It uses useLayoutEffect internally; in the Next.js Pages Router, load it with next/dynamic and ssr: false to avoid the server-render warning.

4. Pass `customConnection` to the chain factory

Layerswap.tsx

import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
import { StarknetWalletConnectors } from '@dynamic-labs/starknet';
import { createStarknetProvider } from '@layerswap/wallet-starknet';
import { LayerswapProvider, Swap } from '@layerswap/widget';
import dynamic from 'next/dynamic';
import { customStarknetAdapter } from './useCustomStarknet';
import '@layerswap/widget/index.css';

const CustomStarknetHydrator = dynamic(
  () =>
    import('./CustomStarknetHydrator').then(
      (module) => module.CustomStarknetHydrator,
    ),
  { ssr: false },
);

const walletProviders = [
  createStarknetProvider({
    customConnection: customStarknetAdapter.createConnection,
  }),
];

export function Layerswap() {
  return (
    <DynamicContextProvider
      settings={{
        environmentId: process.env.NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID!,
        walletConnectors: [StarknetWalletConnectors],
        initialAuthenticationMode: 'connect-only',
      }}
    >
      <LayerswapProvider
        config={{ apiKey: process.env.NEXT_PUBLIC_LAYERSWAP_API_KEY! }}
        walletProviders={walletProviders}
      >
        <CustomStarknetHydrator />
        <Swap />
      </LayerswapProvider>
    </DynamicContextProvider>
  );
}

Keep the adapter, provider object, and walletProviders array stable. Recreating them during render tears down and recreates connection state.

createReactHookConnectionAdapter is exported from @layerswap/widget/internal. Keep @layerswap/widget and every @layerswap/wallet-* package on compatible releases when using this advanced integration.

External-store wallet managers

If the third-party SDK already exposes subscribe/get-state primitives, create the Zustand store directly. The Widget calls updateProps when settings networks change and destroy when the connection is removed or the provider unmounts.

npm install zustand@^4.5.7

The ./walletManager module below is illustrative and is not provided by Layerswap. Implement its wallets, activeWalletId, ready, connect, disconnect, and subscribe operations—and the mapWallet and supportedNetworkNames helpers—against your SDK. Its connect operation must resolve undefined when the user cancels.

createCustomConnection.ts

import { createStore } from 'zustand/vanilla';
import type {
  WalletConnectionProvider,
  WalletConnectionProviderProps,
  WalletConnectionStore,
} from '@layerswap/widget/types';
import {
  mapWallet,
  supportedNetworkNames,
  walletManager,
} from './walletManager';

export function createCustomConnection(
  initialProps: WalletConnectionProviderProps,
): WalletConnectionStore {
  let props = initialProps;

  const buildSnapshot = (): WalletConnectionProvider => {
    const connectedWallets = walletManager.wallets().map(mapWallet);
    const activeWalletId = walletManager.activeWalletId();

    return {
      id: 'starknet',
      name: 'Starknet',
      ready: walletManager.ready(),
      providerIcon: undefined,
      connectWallet: async () => {
        const externalWallet = await walletManager.connect(props.networks);
        return externalWallet ? mapWallet(externalWallet) : undefined;
      },
      disconnectWallets: () => walletManager.disconnect(),
      connectedWallets,
      activeWallet: connectedWallets.find(
        (wallet) => wallet.id === activeWalletId,
      ),
      asSourceSupportedNetworks: supportedNetworkNames(props.networks),
      autofillSupportedNetworks: supportedNetworkNames(props.networks),
      withdrawalSupportedNetworks: supportedNetworkNames(props.networks),
    };
  };

  const store = createStore<WalletConnectionProvider>(() => buildSnapshot());
  const unsubscribe = walletManager.subscribe(() => {
    store.setState(buildSnapshot(), true);
  });

  return {
    store,
    updateProps(nextProps) {
      props = nextProps;
      store.setState(buildSnapshot(), true);
    },
    destroy() {
      unsubscribe();
    },
  };
}

Pass this factory directly as customConnection:

import { createStarknetProvider } from '@layerswap/wallet-starknet';
import { createCustomConnection } from './createCustomConnection';

const walletProviders = [
  createStarknetProvider({ customConnection: createCustomConnection }),
];

Because no React hook is involved, do not create or render a Hydrator.

Current contract

`WalletConnectionStore`

import type { StoreApi } from 'zustand/vanilla';

type WalletConnectionStore = {
  store: StoreApi<WalletConnectionProvider>;
  updateProps?: (props: WalletConnectionProviderProps) => void;
  destroy?: () => void;
};

type WalletConnectionProviderProps<Network = NetworkWithTokens> = {
  networks: Network[];
  networkAdapter: AppNetworkAdapter<Network>;
  walletProvidersRegistry?: WalletProviderStoreRegistry;
};

Required connection snapshot fields

Field	Type	Purpose
`id`	`string`	Provider-family id. Match the chain factory, such as `starknet` or `evm`.
`name`	`string`	Provider-family label shown by the Widget.
`ready`	`boolean`	Whether connection requests can be handled.
`connectWallet`	`(props?) => Promise<Wallet \| undefined> \| undefined`	Opens your connection flow. If you expose connectors, honor `props.connector`. On cancellation, resolve `undefined`; never reject.
`connectedWallets`	`Wallet[] \| undefined`	Current wallets; use `undefined` while the state is unresolved.
`activeWallet`	`Wallet \| undefined`	The selected wallet, normally one of `connectedWallets`.
`withdrawalSupportedNetworks`	`string[]`	Exact Layerswap network names from `networks` that this provider can sign from.

Common optional fields include disconnectWallets, switchAccount, switchChain, availableConnectors, asSourceSupportedNetworks, autofillSupportedNetworks, providerIcon, unsupportedPlatforms, and hideFromList.

`Wallet`

These are the fields most custom adapters need:

type Wallet = {
  id: string;
  isActive: boolean;
  address: string;
  addresses: string[];
  providerName: string;

  displayName?: string;
  icon?: string; // URL or data URI, not a React component
  chainId?: string | number;
  disconnect?: () => Promise<void> | void;
  connect?: () => Promise<Wallet | undefined>;
  metadata?: {
    starknetAccount?: any;
    wallet?: any;
    l1Address?: string;
    l1ProviderName?: string;
    l1ChainId?: string | number;
    deepLink?: string;
  };
  asSourceSupportedNetworks?: string[];
  autofillSupportedNetworks?: string[];
  withdrawalSupportedNetworks?: string[];
  networkIcon?: string;
};

Give each wallet a stable, unique id. icon is now an image string; omit it to let the Widget render its address-based fallback.

Preserve signing support

The connection snapshot tells the Widget which accounts exist; it does not automatically teach the chain package how your third-party SDK signs.

The default Starknet gas and transfer resolvers read wallet.metadata.starknetAccount.
Other chain packages can use package-owned SDK state or signer adapters. A custom connection must either populate compatible state or replace those resolvers.
balanceProviders, gasProviders, and transferProviders can be passed beside customConnection. Supplying one of these fields replaces that factory’s default list for the capability.
For EVM integrations backed by wagmi, pass the existing wagmiConfig so the EVM transfer resolver uses the same signer. In most cases, the dedicated wagmi integration is simpler than a custom connection.

Test connection, account restoration, address autofill, balance loading, gas estimation, signing, disconnect, and account or chain changes before shipping. Cancel the SDK’s modal as well and confirm the Widget returns to its idle state instead of remaining on “Connecting…”.

Migrating an older custom provider

Old API	Current API
`customHook: useWalletConnection`	`customConnection: adapter.createConnection`
`walletConnectionProvider` on `WalletProvider`	`createConnection` returning `WalletConnectionStore`
Hook passed directly to a factory	Module-level adapter plus a rendered `adapter.Hydrator`
`Wallet.icon` as a React component	`Wallet.icon` as a URL/data-URI string or `undefined`
`createStarknetProvider` from `@layerswap/wallets`	Eager factory from `@layerswap/wallet-starknet`

Remove the old object-spreading pattern as well; provider constants such as StarknetProvider are no longer the customization surface.

Wallet management

Understand the self-bundled provider architecture.

Wallet providers

Choose the eager chain factory and configure its native credentials.

Sharing your wagmi config

Reuse an app-owned EVM connection without a custom store.

Self-bundled Widget

Install and render the package-based Widget.

Start here

Configuration

Production

Guides & tools

Self-bundled Widget

Custom wallet management

Choose the integration shape

Adapt a React hook

1. Install the eager chain package

2. Return the current connection snapshot

3. Render the hydrator

4. Pass `customConnection` to the chain factory

External-store wallet managers

Current contract

`WalletConnectionStore`

Required connection snapshot fields

`Wallet`

Preserve signing support

Migrating an older custom provider

Wallet management

Wallet providers

Sharing your wagmi config

Self-bundled Widget

​Choose the integration shape

​Adapt a React hook

​1. Install the eager chain package

​2. Return the current connection snapshot

​3. Render the hydrator

​4. Pass customConnection to the chain factory

​External-store wallet managers

​Current contract

​WalletConnectionStore

​Required connection snapshot fields

​Wallet

​Preserve signing support

​Migrating an older custom provider

​Related guides

Wallet management

Wallet providers

Sharing your wagmi config

Self-bundled Widget

Choose the integration shape

Adapt a React hook

1. Install the eager chain package

2. Return the current connection snapshot

3. Render the hydrator

4. Pass `customConnection` to the chain factory

External-store wallet managers

Current contract

`WalletConnectionStore`

Required connection snapshot fields

`Wallet`

Preserve signing support

Migrating an older custom provider

Related guides