0
# Wagmi
1

2
Wagmi is a React Hooks library for Ethereum that provides a collection of composable hooks for interacting with wallets, contracts, and blockchain data. It offers reactive primitives for wallet connections, smart contract interactions, and comprehensive blockchain data access with full TypeScript support.
3

4
## Package Information
5

6
- **Package Name**: wagmi
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install wagmi viem @tanstack/react-query`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  WagmiProvider, 
16
  useAccount, 
17
  useConnect, 
18
  useReadContract, 
19
  useSendTransaction 
20
} from "wagmi";
21
import { createConfig, http } from "wagmi";
22
import { mainnet, sepolia } from "wagmi/chains";
23
```
24

25
For actions (imperative API):
26

27
```typescript
28
import { connect, disconnect, readContract } from "wagmi/actions";
29
```
30

31
For connectors:
32

33
```typescript
34
import { metaMask, walletConnect, coinbaseWallet } from "wagmi/connectors";
35
```
36

37
For query utilities:
38

39
```typescript
40
import { useQuery, useMutation, useInfiniteQuery } from "wagmi/query";
41
```
42

43
For experimental features:
44

45
```typescript
46
import { useCallsStatus, useSendCalls } from "wagmi/experimental";
47
```
48

49
For code generation:
50

51
```typescript
52
import { createUseReadContract, createUseWriteContract } from "wagmi/codegen";
53
```
54

55
## Basic Usage
56

57
```typescript
58
import { WagmiProvider, createConfig, http, useAccount, useConnect } from "wagmi";
59
import { mainnet, sepolia } from "wagmi/chains";
60
import { metaMask, walletConnect } from "wagmi/connectors";
61
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
62

63
// 1. Create wagmi config
64
const config = createConfig({
65
  chains: [mainnet, sepolia],
66
  connectors: [
67
    metaMask(),
68
    walletConnect({ projectId: "YOUR_PROJECT_ID" }),
69
  ],
70
  transports: {
71
    [mainnet.id]: http(),
72
    [sepolia.id]: http(),
73
  },
74
});
75

76
// 2. Create query client
77
const queryClient = new QueryClient();
78

79
// 3. Wrap app with providers
80
function App() {
81
  return (
82
    <WagmiProvider config={config}>
83
      <QueryClientProvider client={queryClient}>
84
        <ConnectWallet />
85
      </QueryClientProvider>
86
    </WagmiProvider>
87
  );
88
}
89

90
// 4. Use wagmi hooks
91
function ConnectWallet() {
92
  const { address, isConnected } = useAccount();
93
  const { connect, connectors } = useConnect();
94

95
  if (isConnected) {
96
    return <div>Connected to {address}</div>;
97
  }
98

99
  return (
100
    <div>
101
      {connectors.map((connector) => (
102
        <button key={connector.id} onClick={() => connect({ connector })}>
103
          Connect {connector.name}
104
        </button>
105
      ))}
106
    </div>
107
  );
108
}
109
```
110

111
## Architecture
112

113
Wagmi is built around several key architectural components:
114

115
- **Configuration System**: Centralized config with chains, connectors, and transports
116
- **React Context**: `WagmiProvider` manages global state and configuration access
117
- **TanStack Query Integration**: Built-in caching, background refetching, and optimistic updates
118
- **Type Safety**: Full TypeScript support with generic types preserving chain and connector information
119
- **Connector System**: Pluggable wallet connection interfaces (MetaMask, WalletConnect, etc.)
120
- **Transport Layer**: Configurable RPC transports for different chains using Viem
121
- **Hydration Support**: SSR/SSG compatibility with initial state management
122

123
## Capabilities
124

125
### Account Management
126

127
Wallet connection, disconnection, and account switching functionality with full connector lifecycle management.
128

129
```typescript { .api }
130
function useAccount<config = Config>(
131
  parameters?: UseAccountParameters<config>
132
): UseAccountReturnType<config>;
133

134
function useConnect<config = Config, context = unknown>(
135
  parameters?: UseConnectParameters<config, context>
136
): UseConnectReturnType<config, context>;
137

138
function useDisconnect<config = Config, context = unknown>(
139
  parameters?: UseDisconnectParameters<config, context>
140
): UseDisconnectReturnType<config, context>;
141
```
142

143
[Account Management](./account.md)
144

145
### Blockchain Data
146

147
Access to blocks, chain information, balances, and general blockchain state with real-time updates.
148

149
```typescript { .api }
150
function useBlockNumber<config = Config, selectData = UseBlockNumberReturnType>(
151
  parameters?: UseBlockNumberParameters<config, selectData>
152
): UseBlockNumberReturnType<selectData>;
153

154
function useBalance<config = Config, selectData = UseBalanceReturnType>(
155
  parameters: UseBalanceParameters<config, selectData>
156
): UseBalanceReturnType<selectData>;
157

158
function useChainId<config = Config>(
159
  parameters?: UseChainIdParameters<config>
160
): UseChainIdReturnType<config>;
161
```
162

163
[Blockchain Data](./blockchain.md)
164

165
### Smart Contracts
166

167
Contract interaction hooks for reading from and writing to smart contracts with full type safety.
168

169
```typescript { .api }
170
function useReadContract<config = Config, selectData = UseReadContractReturnType>(
171
  parameters: UseReadContractParameters<config, selectData>
172
): UseReadContractReturnType<selectData>;
173

174
function useWriteContract<config = Config, context = unknown>(
175
  parameters?: UseWriteContractParameters<config, context>
176
): UseWriteContractReturnType<config, context>;
177

178
function useSimulateContract<config = Config, selectData = UseSimulateContractReturnType>(
179
  parameters: UseSimulateContractParameters<config, selectData>
180
): UseSimulateContractReturnType<selectData>;
181
```
182

183
[Smart Contracts](./contracts.md)
184

185
### ENS Integration
186

187
Ethereum Name Service functionality for resolving names, addresses, avatars, and text records.
188

189
```typescript { .api }
190
function useEnsAddress<config = Config, selectData = UseEnsAddressReturnType>(
191
  parameters: UseEnsAddressParameters<config, selectData>
192
): UseEnsAddressReturnType<selectData>;
193

194
function useEnsName<config = Config, selectData = UseEnsNameReturnType>(
195
  parameters: UseEnsNameParameters<config, selectData>
196
): UseEnsNameReturnType<selectData>;
197

198
function useEnsAvatar<config = Config, selectData = UseEnsAvatarReturnType>(
199
  parameters: UseEnsAvatarParameters<config, selectData>
200
): UseEnsAvatarReturnType<selectData>;
201
```
202

203
[ENS Integration](./ens.md)
204

205
### Transaction Management
206

207
Transaction lifecycle management including sending, monitoring, and receipt handling.
208

209
```typescript { .api }
210
function useSendTransaction<config = Config, context = unknown>(
211
  parameters?: UseSendTransactionParameters<config, context>
212
): UseSendTransactionReturnType<config, context>;
213

214
function useTransaction<config = Config, selectData = UseTransactionReturnType>(
215
  parameters: UseTransactionParameters<config, selectData>
216
): UseTransactionReturnType<selectData>;
217

218
function useTransactionReceipt<config = Config, selectData = UseTransactionReceiptReturnType>(
219
  parameters: UseTransactionReceiptParameters<config, selectData>
220
): UseTransactionReceiptReturnType<selectData>;
221
```
222

223
[Transaction Management](./transactions.md)
224

225
### Gas & Fee Estimation
226

227
Gas price monitoring and transaction fee estimation with support for EIP-1559 fee markets.
228

229
```typescript { .api }
230
function useEstimateGas<config = Config, selectData = UseEstimateGasReturnType>(
231
  parameters: UseEstimateGasParameters<config, selectData>
232
): UseEstimateGasReturnType<selectData>;
233

234
function useGasPrice<config = Config, selectData = UseGasPriceReturnType>(
235
  parameters?: UseGasPriceParameters<config, selectData>
236
): UseGasPriceReturnType<selectData>;
237

238
function useEstimateFeesPerGas<config = Config, selectData = UseEstimateFeesPerGasReturnType>(
239
  parameters?: UseEstimateFeesPerGasParameters<config, selectData>
240
): UseEstimateFeesPerGasReturnType<selectData>;
241
```
242

243
[Gas & Fee Estimation](./gas-fees.md)
244

245
### Message Signing & Verification
246

247
Cryptographic signing of messages and typed data with EIP-712 support for secure authentication.
248

249
```typescript { .api }
250
function useSignMessage<config = Config, context = unknown>(
251
  parameters?: UseSignMessageParameters<config, context>
252
): UseSignMessageReturnType<config, context>;
253

254
function useSignTypedData<config = Config, context = unknown>(
255
  parameters?: UseSignTypedDataParameters<config, context>
256
): UseSignTypedDataReturnType<config, context>;
257

258
function useVerifyMessage<config = Config, selectData = UseVerifyMessageReturnType>(
259
  parameters: UseVerifyMessageParameters<config, selectData>
260
): UseVerifyMessageReturnType<selectData>;
261
```
262

263
[Message Signing & Verification](./signing.md)
264

265
### Real-time Data Watching
266

267
Event listeners and watchers for real-time blockchain data updates and contract events.
268

269
```typescript { .api }
270
function useWatchBlockNumber<config = Config>(
271
  parameters?: UseWatchBlockNumberParameters<config>
272
): UseWatchBlockNumberReturnType;
273

274
function useWatchContractEvent<config = Config>(
275
  parameters: UseWatchContractEventParameters<config>
276
): UseWatchContractEventReturnType;
277

278
function useWatchBlocks<config = Config>(
279
  parameters?: UseWatchBlocksParameters<config>
280
): UseWatchBlocksReturnType;
281
```
282

283
[Real-time Data Watching](./watch.md)
284

285
### Atomic Batch Transactions
286

287
EIP-5792 atomic batch transaction support for executing multiple operations as a single unit.
288

289
```typescript { .api }
290
function useSendCalls<config = Config, context = unknown>(
291
  parameters?: UseSendCallsParameters<config, context>
292
): UseSendCallsReturnType<config, context>;
293

294
function useCallsStatus<config = Config, selectData = UseCallsStatusReturnType>(
295
  parameters: UseCallsStatusParameters<config, selectData>
296
): UseCallsStatusReturnType<selectData>;
297

298
function useCapabilities<config = Config, selectData = UseCapabilitiesReturnType>(
299
  parameters?: UseCapabilitiesParameters<config, selectData>
300
): UseCapabilitiesReturnType<selectData>;
301
```
302

303
[Atomic Batch Transactions](./batch.md)
304

305
### Advanced Features
306

307
Advanced functionality including proof generation, SSR hydration, and error handling.
308

309
```typescript { .api }
310
function useProof<config = Config, selectData = UseProofReturnType>(
311
  parameters: UseProofParameters<config, selectData>
312
): UseProofReturnType<selectData>;
313

314
interface WagmiProviderProps {
315
  config: ResolvedRegister['config'];
316
  initialState?: State;
317
  reconnectOnMount?: boolean;
318
}
319

320
interface HydrateProps {
321
  config: ResolvedRegister['config'];
322
  initialState?: State;
323
  reconnectOnMount?: boolean;
324
}
325
```
326

327
[Advanced Features](./advanced.md)
328

329
## Core Types
330

331
```typescript { .api }
332
type Config = {
333
  chains: readonly Chain[];
334
  connectors: Connector[];
335
  transports: Record<number, Transport>;
336
  state: State;
337
  storage?: Storage;
338
  ssr?: boolean;
339
  syncConnectedChain?: boolean;
340
  multiInjectedProviderDiscovery?: boolean;
341
};
342

343
interface State {
344
  chainId: number;
345
  connections: Map<string, Connection>;
346
  current?: string;
347
  status: 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
348
}
349

350
interface Connection {
351
  accounts: readonly Address[];
352
  chainId: number;
353
  connector: Connector;
354
}
355

356
interface UseAccountReturnType {
357
  address?: Address;
358
  addresses?: readonly Address[];
359
  chain?: Chain;
360
  chainId?: number;
361
  connector?: Connector;
362
  isConnected: boolean;
363
  isConnecting: boolean;
364
  isDisconnected: boolean;
365
  isReconnecting: boolean;
366
  status: 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
367
}
368
```
369

370
## Deprecated Hook Aliases
371

372
Some hooks have deprecated aliases that are still available for backward compatibility:
373

374
```typescript
375
// Provider aliases
376
WagmiContext (formerly Context)
377
WagmiProvider (formerly WagmiConfig)
378

379
// Hook aliases (deprecated - use new names)
380
useEstimateFeesPerGas (formerly useFeeData)
381
useInfiniteReadContracts (formerly useContractInfiniteReads)
382
useReadContract (formerly useContractRead)
383
useReadContracts (formerly useContractReads)
384
useWriteContract (formerly useContractWrite)
385
useToken (deprecated - use useReadContracts instead)
386
```