wagmi

wagmi is a collection of over 40 React Hooks for interacting with Ethereum-compatible blockchains — connecting wallets, reading and writing contracts, signing messages, sending transactions, watching blocks, and resolving ENS names. It sits on top of viem for low-level chain communication and TanStack Query for caching, request deduplication, and stale-time management, so every hook gets automatic refetching, loading/error states, and multi-chain support for free.

The project is maintained by the wevm team (also behind viem and ox) and is split into a monorepo of packages: wagmi (the React bindings), @wagmi/core (framework-agnostic actions and config), @wagmi/connectors (injected, WalletConnect, Coinbase Wallet, Safe, and other wallet connectors), @wagmi/cli (codegen for typed contract hooks from ABIs), and companion bindings for Vue and Solid. This makes wagmi less a single library and more a small ecosystem for wallet connectivity and on-chain data fetching across frameworks.

It’s become the default choice for dapp frontends that want React-idiomatic hooks instead of hand-rolling ethers.js/viem calls with manual loading state, and it pairs naturally with RainbowKit, ConnectKit, and other wallet-connection UI layers built on top of it.

What You Get

• 40+ React Hooks covering accounts, wallets, contracts, transactions, signing, blocks, and ENS
• Built-in wallet connectors for injected providers, WalletConnect, Coinbase Wallet, Safe, and Base Account
• Automatic caching, deduplication, and refetching of on-chain reads via TanStack Query
• Multi-chain and multi-account support out of the box, with per-hook chain overrides
• @wagmi/cli code generation that turns a contract ABI into fully typed hooks
• Companion @wagmi/core actions for using the same logic outside React (Vue, Solid, vanilla JS)

Common Use Cases

• Adding wallet connect/disconnect flows to a dapp frontend
• Reading and writing smart contract state from React components with typed hooks
• Displaying live wallet balances, ENS names, and transaction status with automatic refetching
• Building multi-chain dapps that need to switch networks and re-fetch chain-specific data
• Generating typed hooks directly from a contract’s ABI via @wagmi/cli

Under The Hood

Architecture wagmi (the packages/react workspace) is a thin, well-layered wrapper: each hook such as useBalance (src/hooks/useBalance.ts) resolves the active Config via useConfig/useChainId from React context (src/context.ts, exposing WagmiProvider), builds query options with a corresponding @wagmi/core/query helper (e.g. getBalanceQueryOptions), and hands them to a thin useQuery wrapper (src/utils/query.ts) around TanStack Query. The actual chain logic — connecting, RPC calls, ABI encoding — lives one layer down in the framework-agnostic @wagmi/core package (src/actions/*, src/createConfig.ts), which any of the React/Vue/Solid bindings consume identically. This separation means the entire hook surface is generated by composing a small set of primitives (config resolution, query-options builder, query hook) rather than each hook reimplementing fetch/cache logic, and swapping the underlying chain client only requires changing @wagmi/core, not any of the 68 individual hook files.

Tech Stack The monorepo is pnpm-workspace managed with packages for react (this package), core, connectors, cli, vue, solid, and create-wagmi. @wagmi/core depends on viem (peer dependency, pinned to the 2.x line) for all chain communication, zustand for its internal reactive config store, eventemitter3 for connector event handling, and mipd for EIP-6963 injected-wallet discovery. The React package’s own dependency surface is minimal — @wagmi/core, @wagmi/connectors, and use-sync-external-store — with react, @tanstack/react-query, viem, and typescript as peer dependencies so consumers control the exact versions. Builds run through tsc for dual ESM/type output, linting/formatting through Biome, and the whole repo is typed against TypeScript 5.9+.

Code Quality The packages/react/src tree pairs almost one-to-one test files with source files (91 test files against 99 non-test .ts files), including both runtime tests (*.test.ts(x)) and type-level tests (*.test-d.ts) that assert hook generic inference stays correct — a strong signal of API-surface discipline for a heavily-generic hooks library. CI (.github/workflows/verify.yml, pull-request.yml) runs type-checking, linting via Biome, and the OpenSSF Scorecard badge in the README reflects an externally-tracked security posture. Error types are exported per-action (e.g. GetBalanceErrorType) rather than left as untyped throws, and the workspace uses knip to catch unused exports/dependencies across every package.

API Design Every hook follows the same shape — a single parameters object with an optional config override, returning the same UseQueryReturnType shape (data, error, isLoading, etc.) that TanStack Query users already know, which keeps the learning curve low for anyone who has used React Query before. Getting started requires only wrapping the app in WagmiProvider with a createConfig() result; from there, framework-agnostic actions in @wagmi/core mean the same mental model transfers directly to the Vue and Solid bindings. Extensive docs at wagmi.sh, a CONTRIBUTING guide, and @wagmi/cli codegen (turning a raw ABI into fully typed hooks) further lower the barrier for teams working directly with custom contracts.