Follow for latest

Twitter @gizmolab_

Getting started

IntroductionInstall Abstract Global WalletInstall Next.js 14Install DynamicInstall Shadcn UiDeploy EVM Contract

All Components

Abstract Gasless NFT Mint ComponentAbstract Sign InChain SelectorCrypto Product CardNft Mint CardNFT Portfolio DashboardLiFi WidgetPolymarket Widget Component

Dynamic Wagmi Connector Setup Guide

Use @dynamic-labs/wagmi-connector to bridge Dynamic wallet authentication with Wagmi hooks in a Next.js app. This setup keeps wallet login, chain state, and React query wiring aligned so Gizmolab UI components can rely on one clean provider stack.

If you are still wiring the broader wallet-auth flow, start with the Install Dynamic guide first. This page focuses on the connector-specific path and the troubleshooting checks that usually fix setup issues fastest.

What the Dynamic Wagmi connector does

@dynamic-labs/wagmi-connector links Dynamic's wallet connection flow with Wagmi's React provider and hook model. That gives you one setup where Dynamic handles auth and wallet UX, while Wagmi powers account state, chain state, and downstream wallet-aware components.

The connector is useful when your app needs both a polished wallet entry point and a stable hook layer for account-dependent features like chain switching, portfolio views, gated dashboards, or transaction flows.

  • Dynamic handles login and wallet connection UX.
  • Wagmi powers hooks such as useAccount.
  • React Query supports Wagmi's async data layer.
  • Gizmolab UI components can plug into one consistent provider stack.

1. Install the required packages

Start with the same package set used across the current Dynamic-based docs and component examples:

npm install @dynamic-labs/sdk-react-core @dynamic-labs/ethereum @dynamic-labs/wagmi-connector wagmi viem @tanstack/react-query

This covers the Dynamic provider, Ethereum wallet connectors, the Wagmi bridge, Wagmi itself, and the React Query dependency Wagmi expects.

After setup, you can move into wallet-aware UI patterns such as Chain Selector, Crypto Product Card, NFT Portfolio Dashboard, and Polymarket Widget.

2. Add your Dynamic environment ID

Dynamic needs a public environment ID available at runtime. Add it to a project-level .env file as NEXT_PUBLIC_DYNAMIC_ID.

NEXT_PUBLIC_DYNAMIC_ID=your_dynamic_environment_id

If this value is missing, the wallet widget may render partially or fail during initialization. Restart the app after updating environment variables so the client bundle sees the new value.

3. Create one shared Wagmi config

Keep chain definitions and transports in one exported config. A single config prevents route-level drift and makes provider wiring much easier to reason about.

import { http, createConfig } from "wagmi";
import {
  mainnet,
  arbitrum,
  sepolia,
  avalanche,
  polygon,
  bsc,
  base,
  optimism,
} from "wagmi/chains";

export const dynamicEnvironmentId = process.env.NEXT_PUBLIC_DYNAMIC_ID;

if (!dynamicEnvironmentId) {
  console.warn("NEXT_PUBLIC_DYNAMIC_ID is not defined");
}

export const chains = [
  mainnet,
  arbitrum,
  sepolia,
  avalanche,
  polygon,
  bsc,
  base,
  optimism,
] as const;

export const wagmiConfig = createConfig({
  chains,
  multiInjectedProviderDiscovery: false,
  transports: {
    [mainnet.id]: http(),
    [arbitrum.id]: http(),
    [sepolia.id]: http(),
    [avalanche.id]: http(),
    [polygon.id]: http(),
    [bsc.id]: http(),
    [base.id]: http(),
    [optimism.id]: http(),
  },
});

Practical rules that prevent most connector issues:

  • Keep every supported chain in one exported chains array.
  • Add a transport entry for every chain you include.
  • Reuse one shared wagmiConfig instead of creating multiple configs.
  • Leave multiInjectedProviderDiscovery disabled if you want behavior aligned with the current Gizmolab setup.

4. Wrap providers in the correct order

Provider order matters. The safest baseline is Dynamic first, then Wagmi, then React Query, with DynamicWagmiConnector wrapping the children that need wallet-aware hooks.

"use client";

import React, { type ReactNode } from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider } from "wagmi";
import { DynamicContextProvider } from "@dynamic-labs/sdk-react-core";
import { DynamicWagmiConnector } from "@dynamic-labs/wagmi-connector";
import { EthereumWalletConnectors } from "@dynamic-labs/ethereum";
import { wagmiConfig, dynamicEnvironmentId } from "@/config";

const queryClient = new QueryClient();

export default function ContextProvider({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <DynamicContextProvider
      settings={{
        environmentId: dynamicEnvironmentId || "",
        walletConnectors: [EthereumWalletConnectors],
      }}
    >
      <WagmiProvider config={wagmiConfig}>
        <QueryClientProvider client={queryClient}>
          <DynamicWagmiConnector>{children}</DynamicWagmiConnector>
        </QueryClientProvider>
      </WagmiProvider>
    </DynamicContextProvider>
  );
}

This order matters because:

  1. Dynamic initializes wallet auth and connection UX.
  2. Wagmi receives the shared chain and transport config.
  3. React Query supports Wagmi's data lifecycle.
  4. The connector bridges the authenticated wallet session into Wagmi-aware children.

5. Mount the provider high in your app

In a Next.js App Router project, wrap your shared layout with the context provider so wallet-aware routes all use the same session and chain state.

import type { Metadata } from "next";
import "./globals.css";
import ContextProvider from "@/context";

export const metadata: Metadata = {
  title: "Dynamic Example App",
  description: "Powered by Dynamic, built by Gizmolab",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <ContextProvider>{children}</ContextProvider>
      </body>
    </html>
  );
}

6. Verify the connector before adding more UI

Before you add more complex components, confirm that the wallet widget renders and Wagmi can see account state.

import { DynamicWidget } from "@dynamic-labs/sdk-react-core";

export default function Header() {
  return (
    <header className="flex justify-between items-center p-4">
      <h1>My App</h1>
      <DynamicWidget />
    </header>
  );
}
"use client";

import { useAccount } from "wagmi";

export default function WalletDebug() {
  const { address, isConnected } = useAccount();

  return <pre>{JSON.stringify({ address, isConnected }, null, 2)}</pre>;
}

If both checks work, the Dynamic Wagmi connector is usually wired correctly.

Common setup mistakes

Missing NEXT_PUBLIC_DYNAMIC_ID

Confirm the variable name is exact, the value is present in the right environment file, and the dev server was restarted after the change.

Client and server boundaries are mixed

Files that initialize Dynamic or Wagmi providers must be client components. Put "use client" at the top of the provider file.

A chain exists without a matching transport

If a chain is added to the config without a corresponding transport entry, wallet connectivity can become unreliable or incomplete.

Providers are wrapped in the wrong order

When the provider stack is rearranged, hooks can fail silently and connected state may not propagate to child components.

Next docs and components to pair with this setup

After the connector is stable, use the broader Install Dynamic guide for the base wallet flow, then move into component-specific usage for wallet-aware product experiences.