# record.getAvatar

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

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.

Source: https://ensforge.com/docs/reference/sdk/record/get-avatar

<ApiMeta kind="Read" stability="stable" since="1.0.0" source="packages/sdk/src/actions/record/getAvatar/index.ts#L64" batchable />

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

## When to use [#when-to-use]

Use to show a profile picture for a name.

## Details [#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.

<Callout type="warn" title="Gotchas">
- The public `ipfs.io` gateway is rate limited (HTTP 429 under load): set your own gateway in
  production.
</Callout>

## Signature [#signature]

```ts
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](/docs/sdk/look-up-many-at-once).

In React, use [`useAvatar`](/docs/reference/react/use-avatar).

## Parameters [#parameters]

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | ENS name to read. Normalized automatically. |
| `gateways` | `Gateways` |  | HTTP gateways for IPFS and Arweave content, overriding the client's `gateways`. |
| `timeout` | `number` | `10000` | Milliseconds to wait for NFT metadata. |

Also takes the [read options](/docs/reference/sdk/client#read-options).

## Returns [#returns]

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

## Errors [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name cannot be normalized. |
| [`NotFoundError`](/docs/reference/errors/not-found-error) | [`RECORD_NOT_FOUND`](/docs/reference/errors/RECORD_NOT_FOUND), [`RESOLVER_NOT_FOUND`](/docs/reference/errors/RESOLVER_NOT_FOUND) | with `strict`. |
| [`UnsupportedError`](/docs/reference/errors/unsupported-error) | [`RESOLVER_PROFILE_UNSUPPORTED`](/docs/reference/errors/RESOLVER_PROFILE_UNSUPPORTED) | with `strict` when the resolver supports none of the records. |
| [`GatewayError`](/docs/reference/errors/gateway-error) | [`GATEWAY_REQUEST_FAILED`](/docs/reference/errors/GATEWAY_REQUEST_FAILED), [`GATEWAY_RESPONSE_INVALID`](/docs/reference/errors/GATEWAY_RESPONSE_INVALID) | with `strict` when NFT metadata cannot be loaded. |
| [`DnsError`](/docs/reference/errors/dns-error) |  | a DNS name's DNSSEC proof does not verify. |
| [`NetworkError`](/docs/reference/errors/network-error) | [`RPC_REQUEST_FAILED`](/docs/reference/errors/RPC_REQUEST_FAILED), [`RPC_TIMEOUT`](/docs/reference/errors/RPC_TIMEOUT), [`RATE_LIMITED`](/docs/reference/errors/RATE_LIMITED) | the RPC request fails. |

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

See [How errors work](/docs/sdk/errors-explained).

## Examples [#examples]

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Showing a profile picture"
const src = await ens.record.getAvatar({ name: "nick.eth" })
```
</Tab>

<Tab>
```ts title="Using your own IPFS gateway"
import { Actions } from "@ensforge/sdk"

const src = await Actions.record.getAvatar(publicClient, { name: "nick.eth", gateways: { ipfs: "https://gateway.pinata.cloud" } })
```
</Tab>

<Tab>
```ts title="Reading in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

const src = yield* Actions.record.getAvatar(ens, { name: "nick.eth" })
```
</Tab>
</Tabs>

## Example response [#example-response]

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

```ts
await ens.record.getAvatar({ name: "jesse.base.eth" })
```

```json
"https://zku9gdedgba48lmr.public.blob.vercel-storage.com/basenames/avatar/jesse.base.eth/1722020142962/cryptopunk-diuDROjlL5OLY6EcC5keHTsNAiWMSL.png"
```

## See also [#see-also]

- [`record.getText`](/docs/reference/sdk/record/get-text) to read the raw avatar record