0
# Transaction Management
1

2
Transaction lifecycle management including sending, monitoring, and receipt handling. This module provides comprehensive transaction functionality from creation through confirmation with full type safety and error handling.
3

4
## Capabilities
5

6
### useSendTransaction
7

8
Hook to send transactions with comprehensive parameter support and transaction lifecycle tracking.
9

10
```typescript { .api }
11
/**
12
 * Hook to send a transaction
13
 * @param parameters - Transaction sending configuration with mutation callbacks
14
 * @returns Send transaction mutation with transaction state
15
 */
16
function useSendTransaction<config = Config, context = unknown>(
17
  parameters?: UseSendTransactionParameters<config, context>
18
): UseSendTransactionReturnType<config, context>;
19

20
interface UseSendTransactionParameters<config = Config, context = unknown> {
21
  config?: Config | config;
22
  mutation?: {
23
    onMutate?: (variables: SendTransactionVariables) => Promise<context> | context;
24
    onError?: (error: SendTransactionErrorType, variables: SendTransactionVariables, context?: context) => Promise<void> | void;
25
    onSuccess?: (data: SendTransactionData, variables: SendTransactionVariables, context?: context) => Promise<void> | void;
26
    onSettled?: (data?: SendTransactionData, error?: SendTransactionErrorType, variables?: SendTransactionVariables, context?: context) => Promise<void> | void;
27
  };
28
}
29

30
interface UseSendTransactionReturnType<config = Config, context = unknown> {
31
  /** Send transaction */
32
  sendTransaction: (variables: SendTransactionVariables, options?: SendTransactionMutateOptions) => void;
33
  /** Async version of sendTransaction */
34
  sendTransactionAsync: (variables: SendTransactionVariables, options?: SendTransactionMutateAsyncOptions) => Promise<SendTransactionData>;
35
  /** Transaction hash */
36
  data?: SendTransactionData;
37
  /** Send transaction error */
38
  error: SendTransactionErrorType | null;
39
  /** Transaction status flags */
40
  isError: boolean;
41
  isIdle: boolean;
42
  isPending: boolean;
43
  isSuccess: boolean;
44
  /** Reset transaction state */
45
  reset: () => void;
46
  /** Current status */
47
  status: 'error' | 'idle' | 'pending' | 'success';
48
  /** Additional variables */
49
  variables?: SendTransactionVariables;
50
}
51

52
interface SendTransactionVariables {
53
  /** Recipient address */
54
  to: Address;
55
  /** Transaction value in wei */
56
  value?: bigint;
57
  /** Transaction data */
58
  data?: Hex;
59
  /** Account to send from */
60
  account?: Address;
61
  /** Chain ID */
62
  chainId?: number;
63
  /** Gas limit */
64
  gas?: bigint;
65
  /** Gas price (legacy) */
66
  gasPrice?: bigint;
67
  /** Max fee per gas (EIP-1559) */
68
  maxFeePerGas?: bigint;
69
  /** Max priority fee per gas (EIP-1559) */
70
  maxPriorityFeePerGas?: bigint;
71
  /** Nonce override */
72
  nonce?: number;
73
}
74

75
type SendTransactionData = Hash;
76
```
77

78
**Usage Example:**
79

80
```typescript
81
import { useSendTransaction, useWaitForTransactionReceipt } from "wagmi";
82
import { parseEther } from "viem";
83

84
function SendEther() {
85
  const { sendTransaction, data: hash, isPending } = useSendTransaction();
86

87
  const { isLoading: isConfirming, isSuccess: isConfirmed } = 
88
    useWaitForTransactionReceipt({
89
      hash,
90
    });
91

92
  const handleSend = () => {
93
    sendTransaction({
94
      to: '0x742d35Cc6634C0532925a3b8D',
95
      value: parseEther('0.1'), // 0.1 ETH
96
    });
97
  };
98

99
  return (
100
    <div>
101
      <button onClick={handleSend} disabled={isPending || isConfirming}>
102
        {isPending ? 'Preparing...' : isConfirming ? 'Confirming...' : 'Send 0.1 ETH'}
103
      </button>
104
      {hash && <p>Hash: {hash}</p>}
105
      {isConfirmed && <p>Transaction confirmed!</p>}
106
    </div>
107
  );
108
}
109
```
110

111
### useTransaction
112

113
Hook to get detailed transaction information by hash.
114

115
```typescript { .api }
116
/**
117
 * Hook to get transaction by hash
118
 * @param parameters - Transaction query parameters
119
 * @returns Transaction data with all details
120
 */
121
function useTransaction<config = Config, selectData = UseTransactionReturnType>(
122
  parameters: UseTransactionParameters<config, selectData>
123
): UseTransactionReturnType<selectData>;
124

125
interface UseTransactionParameters<config = Config, selectData = UseTransactionReturnType> {
126
  /** Transaction hash to fetch */
127
  hash: Hash;
128
  /** Block number hint for faster lookup */
129
  blockNumber?: bigint;
130
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
131
  /** Chain to use */
132
  chainId?: config['chains'][number]['id'];
133
  config?: Config | config;
134
  query?: {
135
    enabled?: boolean;
136
    staleTime?: number;
137
    gcTime?: number;
138
    refetchInterval?: number;
139
    select?: (data: UseTransactionReturnType) => selectData;
140
  };
141
}
142

143
interface UseTransactionReturnType {
144
  /** Transaction hash */
145
  hash: Hash;
146
  /** Block hash (null for pending) */
147
  blockHash?: Hash;
148
  /** Block number (null for pending) */
149
  blockNumber?: bigint;
150
  /** Transaction index in block */
151
  transactionIndex?: number;
152
  /** Sender address */
153
  from: Address;
154
  /** Recipient address */
155
  to?: Address;
156
  /** Transaction value */
157
  value: bigint;
158
  /** Gas limit */
159
  gas: bigint;
160
  /** Gas price */
161
  gasPrice?: bigint;
162
  /** Max fee per gas */
163
  maxFeePerGas?: bigint;
164
  /** Max priority fee per gas */
165
  maxPriorityFeePerGas?: bigint;
166
  /** Transaction input data */
167
  input: Hex;
168
  /** Nonce */
169
  nonce: number;
170
  /** Transaction type */
171
  type: 'legacy' | 'eip2930' | 'eip1559';
172
  /** Access list (EIP-2930/1559) */
173
  accessList?: AccessList;
174
  /** Chain ID */
175
  chainId?: number;
176
}
177
```
178

179
### useTransactionReceipt
180

181
Hook to get transaction receipt with execution details and status.
182

183
```typescript { .api }
184
/**
185
 * Hook to get transaction receipt
186
 * @param parameters - Transaction receipt query parameters
187
 * @returns Transaction receipt with execution details
188
 */
189
function useTransactionReceipt<config = Config, selectData = UseTransactionReceiptReturnType>(
190
  parameters: UseTransactionReceiptParameters<config, selectData>
191
): UseTransactionReceiptReturnType<selectData>;
192

193
interface UseTransactionReceiptParameters<config = Config, selectData = UseTransactionReceiptReturnType> {
194
  /** Transaction hash */
195
  hash: Hash;
196
  /** Chain to use */
197
  chainId?: config['chains'][number]['id'];
198
  config?: Config | config;
199
  query?: {
200
    enabled?: boolean;
201
    staleTime?: number;
202
    gcTime?: number;
203
    refetchInterval?: number;
204
    select?: (data: UseTransactionReceiptReturnType) => selectData;
205
  };
206
}
207

208
interface UseTransactionReceiptReturnType {
209
  /** Transaction hash */
210
  transactionHash: Hash;
211
  /** Block hash */
212
  blockHash: Hash;
213
  /** Block number */
214
  blockNumber: bigint;
215
  /** Transaction index */
216
  transactionIndex: number;
217
  /** Sender address */
218
  from: Address;
219
  /** Recipient address */
220
  to?: Address;
221
  /** Contract address (for deployments) */
222
  contractAddress?: Address;
223
  /** Cumulative gas used */
224
  cumulativeGasUsed: bigint;
225
  /** Gas used by this transaction */
226
  gasUsed: bigint;
227
  /** Effective gas price */
228
  effectiveGasPrice: bigint;
229
  /** Transaction status (1 = success, 0 = failure) */
230
  status: 'success' | 'reverted';
231
  /** Transaction type */
232
  type: 'legacy' | 'eip2930' | 'eip1559';
233
  /** Event logs */
234
  logs: Log[];
235
  /** Logs bloom filter */
236
  logsBloom: Hex;
237
}
238
```
239

240
### useWaitForTransactionReceipt
241

242
Hook to wait for a transaction to be confirmed and get its receipt.
243

244
```typescript { .api }
245
/**
246
 * Hook to wait for transaction receipt
247
 * @param parameters - Transaction wait parameters
248
 * @returns Transaction receipt when confirmed
249
 */
250
function useWaitForTransactionReceipt<config = Config, selectData = UseWaitForTransactionReceiptReturnType>(
251
  parameters: UseWaitForTransactionReceiptParameters<config, selectData>
252
): UseWaitForTransactionReceiptReturnType<selectData>;
253

254
interface UseWaitForTransactionReceiptParameters<config = Config, selectData = UseWaitForTransactionReceiptReturnType> {
255
  /** Transaction hash to wait for */
256
  hash: Hash;
257
  /** Number of confirmations to wait for */
258
  confirmations?: number;
259
  /** Polling interval in milliseconds */
260
  pollingInterval?: number;
261
  /** Timeout in milliseconds */
262
  timeout?: number;
263
  /** Chain to use */
264
  chainId?: config['chains'][number]['id'];
265
  config?: Config | config;
266
  query?: {
267
    enabled?: boolean;
268
    gcTime?: number;
269
    refetchInterval?: number;
270
    retry?: boolean | number;
271
    select?: (data: UseWaitForTransactionReceiptReturnType) => selectData;
272
  };
273
}
274

275
type UseWaitForTransactionReceiptReturnType = UseTransactionReceiptReturnType;
276
```
277

278
**Usage Example:**
279

280
```typescript
281
import { useWaitForTransactionReceipt } from "wagmi";
282

283
function TransactionStatus({ hash }: { hash: `0x${string}` }) {
284
  const { 
285
    data: receipt,
286
    isLoading,
287
    isSuccess,
288
    isError,
289
    error 
290
  } = useWaitForTransactionReceipt({
291
    hash,
292
    confirmations: 2, // Wait for 2 confirmations
293
  });
294

295
  if (isLoading) return <div>Waiting for confirmation...</div>;
296
  if (isError) return <div>Error: {error?.message}</div>;
297
  if (isSuccess && receipt) {
298
    return (
299
      <div>
300
        <p>Transaction confirmed!</p>
301
        <p>Block: {receipt.blockNumber.toString()}</p>
302
        <p>Gas used: {receipt.gasUsed.toString()}</p>
303
        <p>Status: {receipt.status}</p>
304
      </div>
305
    );
306
  }
307
  return null;
308
}
309
```
310

311
### useTransactionCount
312

313
Hook to get account transaction count (nonce) for a specific address.
314

315
```typescript { .api }
316
/**
317
 * Hook to get account transaction count (nonce)
318
 * @param parameters - Transaction count query parameters
319
 * @returns Transaction count for the address
320
 */
321
function useTransactionCount<config = Config, selectData = UseTransactionCountReturnType>(
322
  parameters: UseTransactionCountParameters<config, selectData>
323
): UseTransactionCountReturnType<selectData>;
324

325
interface UseTransactionCountParameters<config = Config, selectData = UseTransactionCountReturnType> {
326
  /** Address to get transaction count for */
327
  address: Address;
328
  /** Block number to check count at */
329
  blockNumber?: bigint;
330
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
331
  /** Chain to use */
332
  chainId?: config['chains'][number]['id'];
333
  config?: Config | config;
334
  query?: {
335
    enabled?: boolean;
336
    staleTime?: number;
337
    gcTime?: number;
338
    select?: (data: UseTransactionCountReturnType) => selectData;
339
  };
340
}
341

342
type UseTransactionCountReturnType = number;
343
```
344

345
### useTransactionConfirmations
346

347
Hook to get the number of confirmations for a transaction.
348

349
```typescript { .api }
350
/**
351
 * Hook to get transaction confirmations
352
 * @param parameters - Transaction confirmations query parameters
353
 * @returns Number of confirmations for the transaction
354
 */
355
function useTransactionConfirmations<config = Config, selectData = UseTransactionConfirmationsReturnType>(
356
  parameters: UseTransactionConfirmationsParameters<config, selectData>
357
): UseTransactionConfirmationsReturnType<selectData>;
358

359
interface UseTransactionConfirmationsParameters<config = Config, selectData = UseTransactionConfirmationsReturnType> {
360
  /** Transaction hash */
361
  hash: Hash;
362
  /** Chain to use */
363
  chainId?: config['chains'][number]['id'];
364
  config?: Config | config;
365
  query?: {
366
    enabled?: boolean;
367
    staleTime?: number;
368
    refetchInterval?: number;
369
    select?: (data: UseTransactionConfirmationsReturnType) => selectData;
370
  };
371
}
372

373
type UseTransactionConfirmationsReturnType = bigint;
374
```
375

376
### usePrepareTransactionRequest
377

378
Hook to prepare and validate transaction parameters before sending.
379

380
```typescript { .api }
381
/**
382
 * Hook to prepare transaction request
383
 * @param parameters - Transaction preparation parameters
384
 * @returns Prepared transaction with estimated gas and fees
385
 */
386
function usePrepareTransactionRequest<config = Config, selectData = UsePrepareTransactionRequestReturnType>(
387
  parameters: UsePrepareTransactionRequestParameters<config, selectData>
388
): UsePrepareTransactionRequestReturnType<selectData>;
389

390
interface UsePrepareTransactionRequestParameters<config = Config, selectData = UsePrepareTransactionRequestReturnType> {
391
  /** Recipient address */
392
  to: Address;
393
  /** Transaction value */
394
  value?: bigint;
395
  /** Transaction data */
396
  data?: Hex;
397
  /** Account to send from */
398
  account?: Address;
399
  /** Chain ID */
400
  chainId?: config['chains'][number]['id'];
401
  /** Gas limit */
402
  gas?: bigint;
403
  /** Gas price */
404
  gasPrice?: bigint;
405
  /** Max fee per gas */
406
  maxFeePerGas?: bigint;
407
  /** Max priority fee per gas */
408
  maxPriorityFeePerGas?: bigint;
409
  /** Nonce */
410
  nonce?: number;
411
  config?: Config | config;
412
  query?: {
413
    enabled?: boolean;
414
    staleTime?: number;
415
    select?: (data: UsePrepareTransactionRequestReturnType) => selectData;
416
  };
417
}
418

419
interface UsePrepareTransactionRequestReturnType {
420
  /** Prepared transaction parameters */
421
  to: Address;
422
  value?: bigint;
423
  data?: Hex;
424
  account: Address;
425
  chainId: number;
426
  gas: bigint;
427
  gasPrice?: bigint;
428
  maxFeePerGas?: bigint;
429
  maxPriorityFeePerGas?: bigint;
430
  nonce: number;
431
  type: 'legacy' | 'eip2930' | 'eip1559';
432
}
433
```
434

435
## Advanced Transaction Patterns
436

437
### Transaction with Confirmation Tracking
438

439
```typescript
440
import { 
441
  useSendTransaction, 
442
  useWaitForTransactionReceipt, 
443
  useTransactionConfirmations 
444
} from "wagmi";
445

446
function AdvancedTransaction() {
447
  const { sendTransaction, data: hash, isPending } = useSendTransaction();
448
  
449
  const { data: receipt, isLoading: isConfirming } = useWaitForTransactionReceipt({
450
    hash,
451
    confirmations: 1,
452
  });
453

454
  const { data: confirmations } = useTransactionConfirmations({
455
    hash: hash || '0x',
456
    query: { 
457
      enabled: !!hash && !!receipt,
458
      refetchInterval: 4000, // Check every 4 seconds
459
    }
460
  });
461

462
  const handleSend = () => {
463
    sendTransaction({
464
      to: '0x742d35Cc6634C0532925a3b8D',
465
      value: parseEther('0.01'),
466
    });
467
  };
468

469
  return (
470
    <div>
471
      <button onClick={handleSend} disabled={isPending}>
472
        Send Transaction
473
      </button>
474
      
475
      {hash && (
476
        <div>
477
          <p>Hash: {hash}</p>
478
          {isConfirming && <p>Confirming...</p>}
479
          {receipt && (
480
            <div>
481
              <p>Status: {receipt.status}</p>
482
              <p>Confirmations: {confirmations?.toString() || '0'}</p>
483
            </div>
484
          )}
485
        </div>
486
      )}
487
    </div>
488
  );
489
}
490
```
491

492
## Common Types
493

494
```typescript { .api }
495
type Hash = `0x${string}`;
496
type Hex = `0x${string}`;
497
type Address = `0x${string}`;
498

499
interface AccessList {
500
  address: Address;
501
  storageKeys: Hex[];
502
}
503

504
interface Log {
505
  address: Address;
506
  topics: Hash[];
507
  data: Hex;
508
  blockHash: Hash;
509
  blockNumber: bigint;
510
  transactionHash: Hash;
511
  transactionIndex: number;
512
  logIndex: number;
513
  removed: boolean;
514
}
515

516
interface SendTransactionMutateOptions {
517
  onError?: (error: Error, variables: SendTransactionVariables, context?: unknown) => void;
518
  onSuccess?: (data: Hash, variables: SendTransactionVariables, context?: unknown) => void;
519
  onSettled?: (data?: Hash, error?: Error, variables?: SendTransactionVariables, context?: unknown) => void;
520
}
521

522
interface SendTransactionMutateAsyncOptions {
523
  onError?: (error: Error, variables: SendTransactionVariables, context?: unknown) => void;
524
  onSuccess?: (data: Hash, variables: SendTransactionVariables, context?: unknown) => void;
525
  onSettled?: (data?: Hash, error?: Error, variables?: SendTransactionVariables, context?: unknown) => void;
526
}
527

528
type SendTransactionErrorType = Error;
529
```