Documentation for agents: an index at /llms.txt, every docs page in one file at /llms-full.txt, and Markdown for any docs page by adding .md to its URL.

Skip to Content
ensforgeSDK

record.getAvatar

Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12). Options, result, errors and examples for record.getAvatar.

ReadBatchablestable
Since v1.0.0View source

Reads the avatar of an ENS name and resolves it to a URL a browser can load (ENSIP-12).

When to use

Use to show a profile picture for a name.

Details

  • http(s) and data: URIs are returned as-is; ipfs://, ipns://, ar:// and bare CIDs go through gateways: the call's, else the client's (Ensforge.create({ gateways })), else https://ipfs.io and https://arweave.net (the client config also has a Swarm gateway, https://api.gateway.ethswarm.org, used for bzz:// content hashes, not avatars).
  • NFT avatars (eip155:1/erc721:…/…, erc1155) read the token's metadata and return its image. They resolve only on the client's own chain, and only when the name's ETH address owns the token (ENSIP-12): ownerOf for ERC-721, a non-zero balance for ERC-1155.
  • Returns null when the avatar is not set or cannot be loaded, unless strict is set.

Gotchas

  • The public ipfs.io gateway is rate limited (HTTP 429 under load): set your own gateway in production.

Signature

function getAvatar(client: Like, options: getAvatar.Options): Promise<getAvatar.ReturnType>

Call it as ens.record.getAvatar(options) on a client, or Actions.record.getAvatar(client, options).

record.getAvatar.request(options) builds a deferred read for Actions.batch. See Look up many at once.

In React, use useAvatar.

Parameters

OptionTypeDefaultDescription
name (required)stringENS name to read. Normalized automatically.
gatewaysGatewaysHTTP gateways for IPFS and Arweave content, overriding the client's gateways.
timeoutnumber10000Milliseconds to wait for NFT metadata.

Also takes the read options.

Returns

Resolves to string | null. An http(s) or data: URL, or null.

Errors

ErrorCodesWhen
InvalidInputErrorINVALID_NAMEthe name cannot be normalized.
NotFoundErrorRECORD_NOT_FOUND, RESOLVER_NOT_FOUNDwith strict.
UnsupportedErrorRESOLVER_PROFILE_UNSUPPORTEDwith strict when the resolver supports none of the records.
GatewayErrorGATEWAY_REQUEST_FAILED, GATEWAY_RESPONSE_INVALIDwith strict when NFT metadata cannot be loaded.
DnsErrora DNS name's DNSSEC proof does not verify.
NetworkErrorRPC_REQUEST_FAILED, RPC_TIMEOUT, RATE_LIMITEDthe RPC request fails.

It can also fail with the errors every read can (Errors.CommonError: ConfigError, ContractRevertError, InternalError, NetworkError).

See How errors work.

Examples

Showing a profile picture
const src = await ens.record.getAvatar({ name: "nick.eth" })

Example response

Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.

await ens.record.getAvatar({ name: "jesse.base.eth" })
"https://zku9gdedgba48lmr.public.blob.vercel-storage.com/basenames/avatar/jesse.base.eth/1722020142962/cryptopunk-diuDROjlL5OLY6EcC5keHTsNAiWMSL.png"

See also

Was this page helpful?