Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.layerswap.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

For applications that already use wagmi for EVM wallet management, Layerswap offers seamless integration that detects and manages externally connected wallets. This hybrid approach gives you the best of both worlds: your existing wallet infrastructure plus Layerswap’s swap functionality.

​
How It Works

When you integrate Layerswap with your existing wagmi configuration:
  1. External Connection Detection - Wallets connected outside the widget (through your app’s UI) are automatically detected and displayed in Layerswap
  2. Bidirectional Management - Users can connect and disconnect wallets from both your app’s UI and the Layerswap widget
  3. Unified State - Single source of truth for wallet connections across your entire application

​
Implementation

​
Prerequisites

Your application should already have:
  • wagmi installed and configured
  • @tanstack/react-query set up
  • Wallet connectors configured (WalletConnect, MetaMask, Coinbase, etc.)

​
Step 1: Install Layerswap Packages

npm install @layerswap/widget @layerswap/wallet-evm

​
Step 2: Fetch Layerswap Settings

Use the useSettings hook to fetch Layerswap’s network configurations: 
import { useSettings } from "@layerswap/widget"

const App = () => {
  const apiKey = "YOUR_API_KEY" // Optional, from Partner Dashboard
  const { settings, loading } = useSettings(apiKey)

  if (loading) return <WidgetLoading />

  // Use settings to configure wagmi...
}
Server-Side Settings: For server-side rendering (SSR), you can fetch Layerswap settings server-side using the getSettings() function:
import { getSettings } from "@layerswap/widget"

// In your server-side code or getServerSideProps
const settings = await getSettings(apiKey)
This allows you to pre-configure Layerswap networks on the server before rendering, eliminating the loading state on the client.

​
Step 3: Configure Wagmi with Layerswap Networks

Use useChainConfigs to get chain configurations from Layerswap settings: 
import { useSettings, LayerswapProvider, Swap, WidgetLoading } from "@layerswap/widget"
import { useChainConfigs, createEVMProvider } from "@layerswap/wallets"
import { createConfig, WagmiProvider } from "wagmi"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import { walletConnect, coinbaseWallet } from "wagmi/connectors"

const queryClient = new QueryClient()

const App = () => {
  const apiKey = "YOUR_API_KEY"
  const { settings, loading } = useSettings(apiKey)
  const { chains, transports } = useChainConfigs(settings.networks)

  if (loading) return <WidgetLoading />

  const connectors = [
    // Configure your connectors
  ]

  // Create wagmi config with Layerswap's chains and transports
  const wagmiConfig = createConfig({
    chains,
    transports,
    connectors
  })

  // Create EVM provider
  const evmProvider = createEVMProvider({
    walletConnectConfigs: {
      projectId: "YOUR_WALLETCONNECT_PROJECT_ID",
      name: "Your App Name",
      description: "Your app description",
      url: "https://yourapp.com",
      icons: ["https://yourapp.com/logo.png"]
    }
  })

  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <LayerswapProvider
          config={{ settings }}
          walletProviders={[evmProvider]}
        >
          <YourApp />
          <Swap />
        </LayerswapProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

​
Complete Example

Here’s a full example showing the entire integration: 
import { useSettings, LayerswapProvider, Swap, WidgetLoading } from "@layerswap/widget"
import { useChainConfigs, createEVMProvider } from "@layerswap/wallet-evm"
import { createConfig, WagmiProvider, useAccount, useConnect, useDisconnect } from "wagmi"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import { walletConnect, coinbaseWallet, injected } from "wagmi/connectors"
import "@layerswap/widget/index.css"

const queryClient = new QueryClient()

const App = () => {
  const apiKey = process.env.NEXT_PUBLIC_LAYERSWAP_API_KEY
  const { settings, loading } = useSettings(apiKey)
  const { chains, transports } = useChainConfigs(settings.networks)

  if (loading) return <WidgetLoading />

  const connectors = [
    injected(), // MetaMask, Rabby, etc.
    walletConnect({
      projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,
      metadata: {
        name: "Your App",
        description: "Your app description",
        url: "https://yourapp.com",
        icons: ["https://yourapp.com/logo.png"]
      }
    }),
    coinbaseWallet({
      appName: "Your App"
    })
  ]

  const wagmiConfig = createConfig({
    chains,
    transports,
    connectors
  })

  const evmProvider = createEVMProvider({
    walletConnectConfigs: {
      projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,
      name: "Your App",
      description: "Your app description",
      url: "https://yourapp.com",
      icons: ["https://yourapp.com/logo.png"]
    }
  })

  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <LayerswapProvider
          config={{
            apiKey,
            settings,
            version: "mainnet"
          }}
          walletProviders={[evmProvider]}
        >
          <Layout>
            <Header />
            <Main>
              <Swap />
            </Main>
          </Layout>
        </LayerswapProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

// Your app's header with wallet connection
const Header = () => {
  const { address, isConnected } = useAccount()
  const { connect, connectors } = useConnect()
  const { disconnect } = useDisconnect()

  return (
    <header>
      <h1>Your App</h1>
      {isConnected ? (
        <div>
          <span>{address?.slice(0, 6)}...{address?.slice(-4)}</span>
          <button onClick={() => disconnect()}>Disconnect</button>
        </div>
      ) : (
        <div>
          {connectors.map((connector) => (
            <button
              key={connector.id}
              onClick={() => connect({ connector })}
            >
              Connect {connector.name}
            </button>
          ))}
        </div>
      )}
    </header>
  )
}

export default App

​
User Experience Flow

​
Scenario 1: User Connects via Your App

  1. User clicks “Connect Wallet” in your app’s header
  2. User selects MetaMask and approves connection
  3. Your app displays connected wallet in header
  4. Layerswap widget automatically detects the wallet and shows it as connected
  5. User can now use Layerswap swap features immediately

​
Scenario 2: User Connects via Layerswap Widget

  1. User opens Layerswap widget (no wallet connected yet)
  2. User clicks “Connect Wallet” in the widget
  3. User selects WalletConnect and approves connection
  4. Your app automatically detects the wallet and shows it in header
  5. User can now use both your app features and Layerswap swaps

​
Scenario 3: User Disconnects from Either Interface

  1. User has wallet connected
  2. User clicks “Disconnect” in either your app OR the widget
  3. Both interfaces update to show disconnected state
  4. Wallet state remains synchronized

​
Limitations

  • EVM Only - Partial integration currently only works for EVM chains
  • wagmi Required - Your app must already use wagmi
  • Network Compatibility - Only Layerswap-supported EVM networks will be configured
For non-EVM chains, use: