ENS Logo


Personalization of profiles is what makes identity great. This page covers the very special avatar record that enables users to take their avatar with them across the web.


Getting the user's Avatar

Avatars are an awesome way for users to express themselves. To get the user's avatar, all you need is their name. If you only have their address, see primary names. The following code snippets let you get the avatar for a user.

import { useEnsAvatar } from "wagmi";

function App() {
  const { data: ensAvatar } = useEnsAvatar({
    address: "luc.eth",
    chainId: 1, // (1 = Ethereum Mainnet, 5 = Goerli)

  return (
      src={ensAvatar || "https://avatars.jakerunzer.com/luc.eth"}
const ensAvatar = await provider.getAvatar("luc.eth");
import { normalize } from "viem/ens";
import { publicClient } from "./client";

const ensAvatar = await publicClient.getEnsAvatar({
  name: normalize("luc.eth"),
package main

import (

	ens "github.com/wealdtech/go-ens/v3"

func main() {
	client, _ := ethclient.Dial("https://rpc.ankr.com/eth")

	domain, _ := ens.Normalize("luc.eth")
	resolver, _ := ens.NewResolver(client, domain)
	avatar, _ := resolver.Text("avatar")

	fmt.Println("Avatar: ", avatar)

The Metadata Service

The metadata service is run by ENS Labs. It is a free service web service that allows you to retrieve the avatar of an ENS name via a web request, as opposed to adding extra logic to your application and interacting with an ethereum node. This is of course centralised and should be used if absolutely necessary.

What exactly is an Avatar Record?

An avatar record is simply a text record that has "avatar" as its key and a URI as its value, with some rules about what URI schemes are supported and how to process them. For more info, see ENSIP-11.

Supported URI schemes

Clients are expected to support a number of URI schemas, which aren't always web URIs, so the final result you see in your application will vary depending on how the library you are using has decided to handle avatar records.

  • http(s): - URI Scheme for for HTTP(S) URLs. Libraries will most likely return the result directly.
  • ipfs: - URI scheme for IPFS hashes. Libraries may decide to fetch the result from a public gateway for you.
  • data: - URI Scheme for data URIs. Libraries will most likely return the result directly.
  • eip155: - The URI scheme for EIP-155 identifiers for linking to NFTs on Ethereum based chains. A little complicated to resolve manually, most libraries should resolve this for you and return the underlying resource.

Common schemes that aren't officially supported

  • ethereum: - The URI scheme for Ethereum addresses
  • bzz: - The URI scheme for Swarm hashes

File Information

Avatars come in many different shapes and sizes. Not just the above URI schemas, but also in different file formats, sizes, and more. Although standards exist for some of these, files are not required to follow these standards.

Below is some information about the avatars your app might be loading.

File ExtensionMostly png, jpeg, jpg, webp, gif, webm, but could be anything
File SizeWe recommend having sensible timeouts
Aspect RatioWe recommend object-fit: cover or setting a background color
TransparencyWe recommend setting a background color as some images may contain transparency

Luckily most browsers and network libraries have default timeouts to start with, we highly recommend that if you are doing any manual avatar downloading or fetching you add a sensible timeout.

Last Modified
2 months ago