wagmi

React hooks for Ethereum and EVM-compatible chains. Provides type-safe, composable primitives for wallet connection, contract reads/writes, transaction tracking, chain switching, and ENS resolution. Built on top of viem with TanStack Query for caching and state management.

What You Probably Got Wrong

Agents trained on pre-2024 data generate wagmi v1 code. wagmi v2 shipped breaking changes across the entire API surface. Every pattern below is different from v1.

• WagmiConfig is removed -- use WagmiProvider -- v1 used <WagmiConfig client={client}>. v2 uses <WagmiProvider config={config}>. Using the old component will throw "WagmiConfig is not exported".
• QueryClientProvider is mandatory -- wagmi v2 delegates all caching to TanStack Query. You must wrap your app in both <WagmiProvider> and <QueryClientProvider>. Without it, every hook throws "No QueryClient set".
• createConfig replaces createClient -- v1 used createClient({ autoConnect, provider }). v2 uses createConfig({ chains, connectors, transports }). The config shape is completely different.
• Hook names changed -- useContractRead -> useReadContract. useContractWrite -> useWriteContract. useWaitForTransaction -> useWaitForTransactionReceipt. usePrepareContractWrite is removed entirely.
• usePrepareContractWrite no longer exists -- v2 removes the prepare/write split. Use useWriteContract directly; it handles simulation internally via useSimulateContract if you need pre-flight checks.
• Transports are per-chain, not global -- v2 config requires a transports map keyed by chain ID: transports: { [mainnet.id]: http(), [sepolia.id]: http() }. There is no single global transport.
• Connector imports changed -- import { injected, walletConnect, coinbaseWallet } from "wagmi/connectors", not from wagmi directly or @wagmi/connectors.
• All token amounts are bigint -- wagmi v2 returns raw bigint for balances, allowances, and contract return values. Never use JavaScript number for on-chain values.
• ABIs must use as const -- For type inference on useReadContract/useWriteContract args and return types, ABI arrays require as const. Without it, args become unknown[].
• useChainId replaces useNetwork -- v1's useNetwork() returning { chain, chains } is gone. Use useChainId() for the current chain ID and useSwitchChain() for switching.