0
# ENS Integration
1

2
Ethereum Name Service functionality for resolving names, addresses, avatars, and text records. This module provides comprehensive ENS support including forward and reverse resolution, avatar fetching, and custom text records.
3

4
## Capabilities
5

6
### useEnsAddress
7

8
Hook to resolve ENS names to Ethereum addresses with caching and automatic revalidation.
9

10
```typescript { .api }
11
/**
12
 * Hook to resolve ENS name to address
13
 * @param parameters - ENS name resolution parameters
14
 * @returns Resolved Ethereum address for the ENS name
15
 */
16
function useEnsAddress<config = Config, selectData = UseEnsAddressReturnType>(
17
  parameters: UseEnsAddressParameters<config, selectData>
18
): UseEnsAddressReturnType<selectData>;
19

20
interface UseEnsAddressParameters<config = Config, selectData = UseEnsAddressReturnType> {
21
  /** ENS name to resolve (e.g., 'vitalik.eth') */
22
  name: string;
23
  /** Block number to resolve at */
24
  blockNumber?: bigint;
25
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
26
  /** Chain to use (must support ENS) */
27
  chainId?: config['chains'][number]['id'];
28
  /** Specific coin type (default: 60 for Ethereum) */
29
  coinType?: number;
30
  /** Universal resolver address override */
31
  universalResolverAddress?: Address;
32
  config?: Config | config;
33
  query?: {
34
    enabled?: boolean;
35
    staleTime?: number;
36
    gcTime?: number;
37
    select?: (data: UseEnsAddressReturnType) => selectData;
38
  };
39
}
40

41
type UseEnsAddressReturnType = Address | null;
42
```
43

44
**Usage Example:**
45

46
```typescript
47
import { useEnsAddress } from "wagmi";
48

49
function EnsProfile({ ensName }: { ensName: string }) {
50
  const { data: address, isLoading, error } = useEnsAddress({
51
    name: ensName,
52
  });
53

54
  if (isLoading) return <div>Resolving...</div>;
55
  if (error) return <div>Resolution failed</div>;
56
  if (!address) return <div>Name not found</div>;
57

58
  return (
59
    <div>
60
      <p>ENS: {ensName}</p>
61
      <p>Address: {address}</p>
62
    </div>
63
  );
64
}
65
```
66

67
### useEnsName
68

69
Hook to get ENS name for an Ethereum address (reverse resolution).
70

71
```typescript { .api }
72
/**
73
 * Hook to get ENS name for address
74
 * @param parameters - Address to ENS name resolution parameters
75
 * @returns ENS name associated with the address
76
 */
77
function useEnsName<config = Config, selectData = UseEnsNameReturnType>(
78
  parameters: UseEnsNameParameters<config, selectData>
79
): UseEnsNameReturnType<selectData>;
80

81
interface UseEnsNameParameters<config = Config, selectData = UseEnsNameReturnType> {
82
  /** Address to resolve to ENS name */
83
  address: Address;
84
  /** Block number to resolve at */
85
  blockNumber?: bigint;
86
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
87
  /** Chain to use */
88
  chainId?: config['chains'][number]['id'];
89
  /** Universal resolver address override */
90
  universalResolverAddress?: Address;
91
  config?: Config | config;
92
  query?: {
93
    enabled?: boolean;
94
    staleTime?: number;
95
    gcTime?: number;
96
    select?: (data: UseEnsNameReturnType) => selectData;
97
  };
98
}
99

100
type UseEnsNameReturnType = string | null;
101
```
102

103
### useEnsAvatar
104

105
Hook to get avatar URL associated with an ENS name.
106

107
```typescript { .api }
108
/**
109
 * Hook to get ENS avatar
110
 * @param parameters - ENS avatar query parameters
111
 * @returns Avatar URL for the ENS name
112
 */
113
function useEnsAvatar<config = Config, selectData = UseEnsAvatarReturnType>(
114
  parameters: UseEnsAvatarParameters<config, selectData>
115
): UseEnsAvatarReturnType<selectData>;
116

117
interface UseEnsAvatarParameters<config = Config, selectData = UseEnsAvatarReturnType> {
118
  /** ENS name to get avatar for */
119
  name: string;
120
  /** Whether to gateway IPFS URLs */
121
  gatewayUrls?: string[];
122
  /** Block number to query at */
123
  blockNumber?: bigint;
124
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
125
  /** Chain to use */
126
  chainId?: config['chains'][number]['id'];
127
  /** Universal resolver address override */
128
  universalResolverAddress?: Address;
129
  config?: Config | config;
130
  query?: {
131
    enabled?: boolean;
132
    staleTime?: number;
133
    gcTime?: number;
134
    select?: (data: UseEnsAvatarReturnType) => selectData;
135
  };
136
}
137

138
type UseEnsAvatarReturnType = string | null;
139
```
140

141
**Usage Example:**
142

143
```typescript
144
import { useEnsName, useEnsAvatar } from "wagmi";
145

146
function UserProfile({ address }: { address: `0x${string}` }) {
147
  const { data: ensName } = useEnsName({ address });
148
  const { data: avatar } = useEnsAvatar({ 
149
    name: ensName || '',
150
    query: { enabled: !!ensName }
151
  });
152

153
  return (
154
    <div>
155
      {avatar && <img src={avatar} alt="Avatar" />}
156
      <p>{ensName || address}</p>
157
    </div>
158
  );
159
}
160
```
161

162
### useEnsText
163

164
Hook to get text records associated with an ENS name.
165

166
```typescript { .api }
167
/**
168
 * Hook to get ENS text record
169
 * @param parameters - ENS text record query parameters
170
 * @returns Text record value for the specified key
171
 */
172
function useEnsText<config = Config, selectData = UseEnsTextReturnType>(
173
  parameters: UseEnsTextParameters<config, selectData>
174
): UseEnsTextReturnType<selectData>;
175

176
interface UseEnsTextParameters<config = Config, selectData = UseEnsTextReturnType> {
177
  /** ENS name to get text record for */
178
  name: string;
179
  /** Text record key (e.g., 'email', 'url', 'twitter', 'github') */
180
  key: string;
181
  /** Block number to query at */
182
  blockNumber?: bigint;
183
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
184
  /** Chain to use */
185
  chainId?: config['chains'][number]['id'];
186
  /** Universal resolver address override */
187
  universalResolverAddress?: Address;
188
  config?: Config | config;
189
  query?: {
190
    enabled?: boolean;
191
    staleTime?: number;
192
    gcTime?: number;
193
    select?: (data: UseEnsTextReturnType) => selectData;
194
  };
195
}
196

197
type UseEnsTextReturnType = string | null;
198
```
199

200
**Usage Example:**
201

202
```typescript
203
import { useEnsText } from "wagmi";
204

205
function EnsTextRecords({ ensName }: { ensName: string }) {
206
  const { data: email } = useEnsText({
207
    name: ensName,
208
    key: 'email',
209
  });
210

211
  const { data: twitter } = useEnsText({
212
    name: ensName,
213
    key: 'com.twitter',
214
  });
215

216
  const { data: github } = useEnsText({
217
    name: ensName,
218
    key: 'com.github',
219
  });
220

221
  return (
222
    <div>
223
      <h3>{ensName}</h3>
224
      {email && <p>Email: {email}</p>}
225
      {twitter && <p>Twitter: @{twitter}</p>}
226
      {github && <p>GitHub: {github}</p>}
227
    </div>
228
  );
229
}
230
```
231

232
### useEnsResolver
233

234
Hook to get the resolver address for an ENS name.
235

236
```typescript { .api }
237
/**
238
 * Hook to get ENS resolver
239
 * @param parameters - ENS resolver query parameters
240
 * @returns Resolver contract address for the ENS name
241
 */
242
function useEnsResolver<config = Config, selectData = UseEnsResolverReturnType>(
243
  parameters: UseEnsResolverParameters<config, selectData>
244
): UseEnsResolverReturnType<selectData>;
245

246
interface UseEnsResolverParameters<config = Config, selectData = UseEnsResolverReturnType> {
247
  /** ENS name to get resolver for */
248
  name: string;
249
  /** Block number to query at */
250
  blockNumber?: bigint;
251
  blockTag?: 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized';
252
  /** Chain to use */
253
  chainId?: config['chains'][number]['id'];
254
  /** Universal resolver address override */
255
  universalResolverAddress?: Address;
256
  config?: Config | config;
257
  query?: {
258
    enabled?: boolean;
259
    staleTime?: number;
260
    gcTime?: number;
261
    select?: (data: UseEnsResolverReturnType) => selectData;
262
  };
263
}
264

265
type UseEnsResolverReturnType = Address | null;
266
```
267

268
## Advanced ENS Usage
269

270
### Multiple Text Records
271

272
```typescript
273
import { useEnsText } from "wagmi";
274

275
function ComprehensiveEnsProfile({ ensName }: { ensName: string }) {
276
  // Common text record keys
277
  const textRecords = [
278
    'email',
279
    'url', 
280
    'avatar',
281
    'description',
282
    'notice',
283
    'keywords',
284
    'com.discord',
285
    'com.github',
286
    'com.reddit',
287
    'com.twitter',
288
    'org.telegram',
289
  ];
290

291
  const records = textRecords.map(key => ({
292
    key,
293
    ...useEnsText({ name: ensName, key })
294
  }));
295

296
  return (
297
    <div>
298
      <h2>{ensName}</h2>
299
      {records
300
        .filter(record => record.data)
301
        .map(record => (
302
          <p key={record.key}>
303
            {record.key}: {record.data}
304
          </p>
305
        ))
306
      }
307
    </div>
308
  );
309
}
310
```
311

312
### ENS Profile Component
313

314
```typescript
315
import { useEnsAddress, useEnsName, useEnsAvatar, useEnsText } from "wagmi";
316

317
interface EnsProfileProps {
318
  nameOrAddress: string;
319
}
320

321
function EnsProfile({ nameOrAddress }: EnsProfileProps) {
322
  // Determine if input is ENS name or address
323
  const isAddress = nameOrAddress.startsWith('0x');
324
  
325
  // Get address if ENS name provided
326
  const { data: resolvedAddress } = useEnsAddress({
327
    name: nameOrAddress,
328
    query: { enabled: !isAddress }
329
  });
330
  
331
  // Get ENS name if address provided
332
  const { data: ensName } = useEnsName({
333
    address: nameOrAddress as Address,
334
    query: { enabled: isAddress }
335
  });
336

337
  const finalAddress = isAddress ? nameOrAddress as Address : resolvedAddress;
338
  const finalName = isAddress ? ensName : nameOrAddress;
339

340
  // Get avatar and description
341
  const { data: avatar } = useEnsAvatar({
342
    name: finalName || '',
343
    query: { enabled: !!finalName }
344
  });
345

346
  const { data: description } = useEnsText({
347
    name: finalName || '',
348
    key: 'description',
349
    query: { enabled: !!finalName }
350
  });
351

352
  if (!finalAddress && !finalName) {
353
    return <div>Unable to resolve ENS name or address</div>;
354
  }
355

356
  return (
357
    <div className="ens-profile">
358
      {avatar && <img src={avatar} alt="ENS Avatar" className="avatar" />}
359
      <div>
360
        {finalName && <h3>{finalName}</h3>}
361
        <p className="address">{finalAddress}</p>
362
        {description && <p className="description">{description}</p>}
363
      </div>
364
    </div>
365
  );
366
}
367
```
368

369
## Common Types
370

371
```typescript { .api }
372
type Address = `0x${string}`;
373

374
interface EnsRecord {
375
  /** The resolved value */
376
  value: string | null;
377
  /** Whether the record exists */
378
  exists: boolean;
379
}
380

381
// Standard ENS text record keys
382
type StandardTextRecordKey = 
383
  | 'avatar'
384
  | 'description' 
385
  | 'display'
386
  | 'email'
387
  | 'keywords'
388
  | 'mail'
389
  | 'notice'
390
  | 'location'
391
  | 'phone'
392
  | 'url'
393
  | 'com.discord'
394
  | 'com.github'
395
  | 'com.peepeth'
396
  | 'com.linkedin'
397
  | 'com.reddit'
398
  | 'com.twitter'
399
  | 'io.keybase'
400
  | 'org.telegram';
401

402
// Coin types for address resolution (SLIP-44)
403
type CoinType = 
404
  | 0   // Bitcoin
405
  | 2   // Litecoin
406
  | 3   // Dogecoin
407
  | 60  // Ethereum (default)
408
  | 61  // Ethereum Classic
409
  | 144 // Ripple
410
  | 145 // Bitcoin Cash
411
  | 714 // Binance Chain;
412

413
interface EnsConfig {
414
  /** ENS registry address */
415
  ensRegistry?: Address;
416
  /** Universal resolver address */
417
  universalResolverAddress?: Address;
418
}
419
```