0
# Blockchain Data
1

2
Access to blocks, chain information, balances, and general blockchain state with real-time updates. This module provides comprehensive hooks for reading blockchain data including blocks, balances, chain information, and contract storage.
3

4
## Capabilities
5

6
### useBlockNumber
7

8
Hook to get the current block number with automatic updates.
9

10
```typescript { .api }
11
/**
12
 * Hook to get current block number
13
 * @param parameters - Optional configuration parameters
14
 * @returns Current block number with query state
15
 */
16
function useBlockNumber<config = Config, selectData = UseBlockNumberReturnType>(
17
  parameters?: UseBlockNumberParameters<config, selectData>
18
): UseBlockNumberReturnType<selectData>;
19

20
interface UseBlockNumberParameters<config = Config, selectData = UseBlockNumberReturnType> {
21
  /** Chain to use for block number */
22
  chainId?: config['chains'][number]['id'];
23
  /** Custom config */
24
  config?: Config | config;
25
  /** TanStack Query parameters */
26
  query?: {
27
    enabled?: boolean;
28
    staleTime?: number;
29
    refetchInterval?: number;
30
    select?: (data: UseBlockNumberReturnType) => selectData;
31
  };
32
}
33

34
type UseBlockNumberReturnType = bigint;
35
```
36

37
### useBlock
38

39
Hook to get detailed block information by number or hash.
40

41
```typescript { .api }
42
/**
43
 * Hook to get block information
44
 * @param parameters - Block query parameters
45
 * @returns Block data with transaction details
46
 */
47
function useBlock<config = Config, selectData = UseBlockReturnType>(
48
  parameters?: UseBlockParameters<config, selectData>
49
): UseBlockReturnType<selectData>;
50

51
interface UseBlockParameters<config = Config, selectData = UseBlockReturnType> {
52
  /** Block number or hash to fetch */
53
  blockNumber?: bigint;
54
  blockHash?: Hash;
55
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
56
  /** Include full transaction data */
57
  includeTransactions?: boolean;
58
  /** Chain to use */
59
  chainId?: config['chains'][number]['id'];
60
  config?: Config | config;
61
  query?: {
62
    enabled?: boolean;
63
    staleTime?: number;
64
    select?: (data: UseBlockReturnType) => selectData;
65
  };
66
}
67

68
interface UseBlockReturnType {
69
  /** Block hash */
70
  hash: Hash;
71
  /** Block number */
72
  number: bigint;
73
  /** Parent block hash */
74
  parentHash: Hash;
75
  /** Timestamp */
76
  timestamp: bigint;
77
  /** Gas limit */
78
  gasLimit: bigint;
79
  /** Gas used */
80
  gasUsed: bigint;
81
  /** Miner/validator address */
82
  miner: Address;
83
  /** Transaction hashes or full transactions */
84
  transactions: Hash[] | Transaction[];
85
  /** Additional block properties */
86
  difficulty?: bigint;
87
  totalDifficulty?: bigint;
88
  size?: bigint;
89
  nonce?: Hex;
90
  baseFeePerGas?: bigint;
91
}
92
```
93

94
### useBalance
95

96
Hook to get account balance for native currency or ERC-20 tokens.
97

98
```typescript { .api }
99
/**
100
 * Hook to get account balance
101
 * @param parameters - Balance query parameters
102
 * @returns Balance data with decimals and symbol
103
 */
104
function useBalance<config = Config, selectData = UseBalanceReturnType>(
105
  parameters: UseBalanceParameters<config, selectData>
106
): UseBalanceReturnType<selectData>;
107

108
interface UseBalanceParameters<config = Config, selectData = UseBalanceReturnType> {
109
  /** Account address to check balance for */
110
  address: Address;
111
  /** Token contract address (omit for native currency) */
112
  token?: Address;
113
  /** Block number to check balance at */
114
  blockNumber?: bigint;
115
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
116
  /** Chain to use */
117
  chainId?: config['chains'][number]['id'];
118
  config?: Config | config;
119
  query?: {
120
    enabled?: boolean;
121
    staleTime?: number;
122
    select?: (data: UseBalanceReturnType) => selectData;
123
  };
124
}
125

126
interface UseBalanceReturnType {
127
  /** Token decimals */
128
  decimals: number;
129
  /** Formatted balance string */
130
  formatted: string;
131
  /** Token symbol */
132
  symbol: string;
133
  /** Raw balance value */
134
  value: bigint;
135
}
136
```
137

138
**Usage Example:**
139

140
```typescript
141
import { useBalance } from "wagmi";
142

143
function Balance({ address }: { address: `0x${string}` }) {
144
  const { data: balance } = useBalance({
145
    address,
146
  });
147

148
  // Get USDC balance
149
  const { data: usdcBalance } = useBalance({
150
    address,
151
    token: '0xA0b86a33E6417C90CC5F6d2c4a29f9D7e5D8ecf0', // USDC
152
  });
153

154
  return (
155
    <div>
156
      <p>ETH: {balance?.formatted} {balance?.symbol}</p>
157
      <p>USDC: {usdcBalance?.formatted} {usdcBalance?.symbol}</p>
158
    </div>
159
  );
160
}
161
```
162

163
### useChainId
164

165
Hook to get the current chain ID.
166

167
```typescript { .api }
168
/**
169
 * Hook to get current chain ID
170
 * @param parameters - Optional configuration parameters  
171
 * @returns Current chain ID
172
 */
173
function useChainId<config = Config>(
174
  parameters?: UseChainIdParameters<config>
175
): UseChainIdReturnType<config>;
176

177
interface UseChainIdParameters<config = Config> {
178
  config?: Config | config;
179
}
180

181
type UseChainIdReturnType<config = Config> = config['chains'][number]['id'];
182
```
183

184
### useChains
185

186
Hook to get all configured chains.
187

188
```typescript { .api }
189
/**
190
 * Hook to get configured chains
191
 * @param parameters - Optional configuration parameters
192
 * @returns Array of configured chains
193
 */
194
function useChains<config = Config>(
195
  parameters?: UseChainsParameters<config>
196
): UseChainsReturnType<config>;
197

198
interface UseChainsParameters<config = Config> {
199
  config?: Config | config;
200
}
201

202
type UseChainsReturnType<config = Config> = config['chains'];
203
```
204

205
### useClient
206

207
Hook to get a Viem client instance for making direct RPC calls.
208

209
```typescript { .api }
210
/**
211
 * Hook to get viem client
212
 * @param parameters - Client configuration parameters
213
 * @returns Viem client instance
214
 */
215
function useClient<config = Config>(
216
  parameters?: UseClientParameters<config>
217
): UseClientReturnType<config>;
218

219
interface UseClientParameters<config = Config> {
220
  /** Chain ID for the client */
221
  chainId?: config['chains'][number]['id'];
222
  config?: Config | config;
223
}
224

225
type UseClientReturnType<config = Config> = Client<Transport, config['chains'][number]>;
226
```
227

228
### usePublicClient
229

230
Hook to get a public Viem client for read-only operations.
231

232
```typescript { .api }
233
/**
234
 * Hook to get public viem client
235
 * @param parameters - Public client configuration parameters
236
 * @returns Public viem client instance
237
 */
238
function usePublicClient<config = Config>(
239
  parameters?: UsePublicClientParameters<config>
240
): UsePublicClientReturnType<config>;
241

242
interface UsePublicClientParameters<config = Config> {
243
  /** Chain ID for the client */
244
  chainId?: config['chains'][number]['id'];
245
  config?: Config | config;
246
}
247

248
type UsePublicClientReturnType<config = Config> = PublicClient<Transport, config['chains'][number]>;
249
```
250

251
### useBytecode
252

253
Hook to get contract bytecode at a specific address.
254

255
```typescript { .api }
256
/**
257
 * Hook to get contract bytecode
258
 * @param parameters - Bytecode query parameters
259
 * @returns Contract bytecode
260
 */
261
function useBytecode<config = Config, selectData = UseBytecodeReturnType>(
262
  parameters: UseBytecodeParameters<config, selectData>
263
): UseBytecodeReturnType<selectData>;
264

265
interface UseBytecodeParameters<config = Config, selectData = UseBytecodeReturnType> {
266
  /** Contract address to get bytecode for */
267
  address: Address;
268
  /** Block number to check bytecode at */
269
  blockNumber?: bigint;
270
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
271
  /** Chain to use */
272
  chainId?: config['chains'][number]['id'];
273
  config?: Config | config;
274
  query?: {
275
    enabled?: boolean;
276
    staleTime?: number;
277
    select?: (data: UseBytecodeReturnType) => selectData;
278
  };
279
}
280

281
type UseBytecodeReturnType = Hex | undefined;
282
```
283

284
### useStorageAt
285

286
Hook to read contract storage at a specific slot.
287

288
```typescript { .api }
289
/**
290
 * Hook to read contract storage
291
 * @param parameters - Storage query parameters
292
 * @returns Storage value at the specified slot
293
 */
294
function useStorageAt<config = Config, selectData = UseStorageAtReturnType>(
295
  parameters: UseStorageAtParameters<config, selectData>
296
): UseStorageAtReturnType<selectData>;
297

298
interface UseStorageAtParameters<config = Config, selectData = UseStorageAtReturnType> {
299
  /** Contract address */
300
  address: Address;
301
  /** Storage slot to read */
302
  slot: Hex;
303
  /** Block number to read storage at */
304
  blockNumber?: bigint;
305
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
306
  /** Chain to use */
307
  chainId?: config['chains'][number]['id'];
308
  config?: Config | config;
309
  query?: {
310
    enabled?: boolean;
311
    staleTime?: number;
312
    select?: (data: UseStorageAtReturnType) => selectData;
313
  };
314
}
315

316
type UseStorageAtReturnType = Hex | undefined;
317
```
318

319
### useBlockTransactionCount
320

321
Hook to get the number of transactions in a block.
322

323
```typescript { .api }
324
/**
325
 * Hook to get transaction count in a block
326
 * @param parameters - Block transaction count parameters
327
 * @returns Number of transactions in the block
328
 */
329
function useBlockTransactionCount<config = Config, selectData = UseBlockTransactionCountReturnType>(
330
  parameters?: UseBlockTransactionCountParameters<config, selectData>
331
): UseBlockTransactionCountReturnType<selectData>;
332

333
interface UseBlockTransactionCountParameters<config = Config, selectData = UseBlockTransactionCountReturnType> {
334
  /** Block number or hash */
335
  blockNumber?: bigint;
336
  blockHash?: Hash;
337
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
338
  /** Chain to use */
339
  chainId?: config['chains'][number]['id'];
340
  config?: Config | config;
341
  query?: {
342
    enabled?: boolean;
343
    staleTime?: number;
344
    select?: (data: UseBlockTransactionCountReturnType) => selectData;
345
  };
346
}
347

348
type UseBlockTransactionCountReturnType = number;
349
```
350

351
### useConfig
352

353
Hook to get the current Wagmi configuration.
354

355
```typescript { .api }
356
/**
357
 * Hook to get wagmi config
358
 * @param parameters - Optional configuration parameters
359
 * @returns Current wagmi configuration
360
 */
361
function useConfig<config = Config>(
362
  parameters?: UseConfigParameters<config>
363
): UseConfigReturnType<config>;
364

365
interface UseConfigParameters<config = Config> {
366
  config?: Config | config;
367
}
368

369
type UseConfigReturnType<config = Config> = config;
370
```
371

372
## Token Information
373

374
### useToken (deprecated)
375

376
Hook to get ERC-20 token information. This hook is deprecated - use `useBalance` or contract reads instead.
377

378
```typescript { .api }
379
/**
380
 * Hook to get ERC-20 token information (deprecated)
381
 * @param parameters - Token query parameters
382
 * @returns Token metadata
383
 * @deprecated Use useBalance or useReadContract instead
384
 */
385
function useToken<config = Config, selectData = UseTokenReturnType>(
386
  parameters: UseTokenParameters<config, selectData>
387
): UseTokenReturnType<selectData>;
388

389
interface UseTokenParameters<config = Config, selectData = UseTokenReturnType> {
390
  /** Token contract address */
391
  address: Address;
392
  /** Chain to use */
393
  chainId?: config['chains'][number]['id'];
394
  config?: Config | config;
395
  query?: {
396
    enabled?: boolean;
397
    staleTime?: number;
398
    select?: (data: UseTokenReturnType) => selectData;
399
  };
400
}
401

402
interface UseTokenReturnType {
403
  /** Token address */
404
  address: Address;
405
  /** Token decimals */
406
  decimals: number;
407
  /** Token name */
408
  name?: string;
409
  /** Token symbol */
410
  symbol?: string;
411
  /** Total supply */
412
  totalSupply?: {
413
    formatted: string;
414
    value: bigint;
415
  };
416
}
417
```
418

419
## Common Types
420

421
```typescript { .api }
422
type Hash = `0x${string}`;
423
type Hex = `0x${string}`;
424
type Address = `0x${string}`;
425

426
interface Transaction {
427
  hash: Hash;
428
  blockHash?: Hash;
429
  blockNumber?: bigint;
430
  transactionIndex?: number;
431
  from: Address;
432
  to?: Address;
433
  value: bigint;
434
  gas: bigint;
435
  gasPrice?: bigint;
436
  maxFeePerGas?: bigint;
437
  maxPriorityFeePerGas?: bigint;
438
  input: Hex;
439
  nonce: number;
440
  type?: 'legacy' | 'eip2930' | 'eip1559';
441
}
442

443
interface Chain {
444
  id: number;
445
  name: string;
446
  network: string;
447
  nativeCurrency: {
448
    name: string;
449
    symbol: string;
450
    decimals: number;
451
  };
452
  rpcUrls: {
453
    default: { http: readonly string[] };
454
    public: { http: readonly string[] };
455
  };
456
  blockExplorers?: {
457
    default: { name: string; url: string };
458
  };
459
}
460

461
interface Client<TTransport = Transport, TChain = Chain> {
462
  transport: TTransport;
463
  chain?: TChain;
464
  key: string;
465
  name: string;
466
  pollingInterval: number;
467
  type: string;
468
  uid: string;
469
}
470

471
interface PublicClient<TTransport = Transport, TChain = Chain> extends Client<TTransport, TChain> {
472
  mode: 'public';
473
}
474

475
interface Transport {
476
  key: string;
477
  name: string;
478
  request: (request: { method: string; params?: any[] }) => Promise<any>;
479
  type: string;
480
}
481
```