ENS Avatar field format specification
This document describes a process for retrieving avatar URIs from ENS, several URI schemes for the ENS 'avatar' text field, and how they should be interpreted by clients wishing to display a user's avatar image.
Retrieving the avatar URI
The process for retrieving the avatar URI depends on whether the client has an Ethereum address or an ENS name to start with.
To determine the avatar URI for an ENS name, the client MUST first look up the resolver for the name and call
.text(namehash(name), 'avatar') on it to retrieve the avatar URI for the name.
The client MUST treat the absence of a resolver, an revert when calling the
addr method on the resolver, or an empty string returned by the resolver identically, as a failure to find a valid avatar URI.
To determine the avatar URI for an Ethereum address, the client MUST reverse-resolve the address by querying the ENS registry for the resolver of
<address> is the lowercase hex-encoded Ethereum address, without leading '0x'. Then, the client calls
.text(namehash('<address>.addr.reverse'), 'avatar') to retrieve the avatar URI for the address.
If a resolver is returned for the reverse record, but calling
text causes a revert or returns an empty string, the client MUST call
.name(namehash('<address>.addr.reverse')). If this method returns a valid ENS name, the client MUST:
- Validate that the reverse record is valid, by resolving the returned name and calling
addron the resolver, checking it matches the original Ethereum address.
- Perform the process described under 'ENS Name' to look for a valid avatar URI on the name.
A failure at any step of this process MUST be treated by the client identically as a failure to find a valid avatar URI.
The 'avatar' text field MUST be formatted as a URI. Clients MUST ignore URI types they do not recognise, treating them the same as if no value was set for the field.
Clients MUST support images with mime types of
image/svg+xml. Clients MAY support additional image types.
All clients SHOULD support the URI schemes defined below. They MAY implement additional schemes not defined in this specification.
If an https URI is provided, it MUST resolve to an avatar image directly. https URLs MUST NOT resolve to HTML pages, metadata, or other content containing the avatar image.
If an ipfs URI is provided, it MUST resolve to an avatar image directly. Clients without built-in IPFS support MAY rewrite the URI to an https URL referencing an IPFS gateway as described in this document before resolving it as an https URL.
If a data URL is provided, it MUST resolve to an avatar image directly.
Clients MUST support at least ERC721 and ERC1155 type NFTs, and MAY support additional types of NFT.
To resolve an NFT URI, a client follows this process:
- Retrieve the metadata URI for the token specified in the
- Resolve the metadata URI, fetching the ERC721 or ERC1155 metadata.
- Extract the image URL specified in the NFT metadata.
- Resolve the image URL and use it as the avatar.
Clients MUST support at least
ipfs URIs for resolving the metadata URI and the avatar image, and MAY support additional schemes. Clients MAY implement
ifps scheme support by rewriting the URI to an HTTPS URL referencing an IPFS gateway as described above.
Clients SHOULD additionally take the following verification steps:
- Where the avatar URI was retrieved via forward resolution (starting from an ENS name), call the
addrfunction on the same resolver and for the same name to retrieve the Ethereum address to which the name resolves. Otherwise, if the avatar URI was retrieved via reverse resolution (starting from an Ethereum address), use that address.
- Verify that the address from step 1 is an owner of the NFT specified in the URI. If it is not, the client MUST treat the URI as invalid and behave in the same manner as they would if no avatar URI was specified.
Clients MAY support NFT URIs by rewriting them to
https URIs for a service that provides NFT avatar image resolution support.
The following examples all resolve to the same avatar image:
eip155:1/erc721:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/0 # BAYC token 0 ipfs://QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ # IPFS hash for BAYC token 0 image https://ipfs.io/ipfs/QmRRPWG96cmgTn2qSzjwr2qvfNEuhunv6FNeMFGa9bx6mQ # HTTPS URL to IPFS gateway for BAYC token 0 image