Avatar Resolution

Resolve avatar images from ENS records, NFT collections, and social platform profiles with automatic IPFS gateway handling.

Endpoints

Endpoint	Description	Price
GET /api/avatar/{identifier}	Universal avatar	$0.001
GET /api/avatar/ens/{name}	ENS avatar	$0.001
GET /api/avatar/nft/{contract}/{tokenId}	NFT image	$0.001
GET /api/avatar/batch	Multiple avatars	$0.005

---

GET /api/avatar/{identifier}

Universal avatar resolution. Accepts ENS names, addresses, or Farcaster usernames.

Resolution Priority

1. ENS avatar record
2. Primary NFT profile picture
3. Farcaster PFP (if connected)
4. Generated identicon fallback

Request

curl https://api.web3identity.com/api/avatar/vitalik.eth

Response

{
  "identifier": "vitalik.eth",
  "avatar": "https://api.web3identity.com/cdn/avatar/vitalik.eth.png",
  "original": "eip155:1/erc721:0xb7f7f6c52f2e2fdb1963eab30438024864c313f6/2430",
  "type": "nft",
  "source": "ens",
  "dimensions": {
    "width": 512,
    "height": 512
  },
  "cached": true,
  "cacheExpiry": "2026-02-09T04:30:00Z"
}

Avatar Types

Type	Description	Example
nft	ERC-721/1155 token	eip155:1/erc721:0x.../123
ipfs	IPFS hash	ipfs://Qm...
url	Direct URL	https://...
data	Base64 data URI	data:image/svg+xml;...
identicon	Generated fallback	Auto-generated

SDK

const avatar = await client.getAvatar('vitalik.eth');

// Get as image buffer
const imageBuffer = await client.getAvatarImage('vitalik.eth');

---

GET /api/avatar/ens/{name}

Get avatar specifically from ENS records.

Request

curl https://api.web3identity.com/api/avatar/ens/nick.eth

Response

{
  "name": "nick.eth",
  "avatar": "https://api.web3identity.com/cdn/avatar/nick.eth.png",
  "record": "eip155:1/erc721:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/69",
  "collection": "Bored Ape Yacht Club",
  "tokenId": "69",
  "contract": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
  "chain": "ethereum"
}

Handle IPFS Avatars

IPFS avatars are automatically resolved through fast gateways:

# Original record: ipfs://QmYxvT...
# Response includes resolved URL
curl https://api.web3identity.com/api/avatar/ens/example.eth

{
  "name": "example.eth",
  "avatar": "https://api.web3identity.com/cdn/avatar/example.eth.png",
  "record": "ipfs://QmYxvTkWE4w...",
  "gateway": "https://cloudflare-ipfs.com/ipfs/QmYxvTkWE4w..."
}

---

GET /api/avatar/nft/{contract}/{tokenId}

Get the image for any NFT directly.

Request

curl https://api.web3identity.com/api/avatar/nft/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1234

Response

{
  "contract": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
  "tokenId": "1234",
  "collection": "Bored Ape Yacht Club",
  "image": "https://api.web3identity.com/cdn/nft/bayc/1234.png",
  "originalUri": "ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/1234",
  "attributes": [
    { "trait_type": "Background", "value": "Blue" },
    { "trait_type": "Fur", "value": "Golden Brown" }
  ]
}

Query Parameters

Param	Type	Default	Description
chain	string	ethereum	Chain for contract
size	string	medium	small, medium, large

Supported Chains

• ethereum (default)
• polygon
• arbitrum
• optimism
• base

---

GET /api/avatar/batch

Resolve multiple avatars in a single request.

Request

curl -X POST https://api.web3identity.com/api/avatar/batch \
  -H "Content-Type: application/json" \
  -d '{"identifiers": ["vitalik.eth", "nick.eth", "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]}'

Or via GET:

curl "https://api.web3identity.com/api/avatar/batch?identifiers=vitalik.eth,nick.eth,dwr.eth"

Response

{
  "avatars": {
    "vitalik.eth": {
      "avatar": "https://api.web3identity.com/cdn/avatar/vitalik.eth.png",
      "type": "nft"
    },
    "nick.eth": {
      "avatar": "https://api.web3identity.com/cdn/avatar/nick.eth.png",
      "type": "nft"
    },
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045": {
      "avatar": "https://api.web3identity.com/cdn/avatar/vitalik.eth.png",
      "type": "nft"
    }
  },
  "count": 3
}

SDK

const avatars = await client.batchAvatars([
  'vitalik.eth',
  'nick.eth',
  'dwr.eth'
]);

---

Image Sizes

Request specific sizes via query parameter:

# Small (64x64)
curl "https://api.web3identity.com/api/avatar/vitalik.eth?size=small"

# Medium (256x256) - default
curl "https://api.web3identity.com/api/avatar/vitalik.eth?size=medium"

# Large (512x512)
curl "https://api.web3identity.com/api/avatar/vitalik.eth?size=large"

# Original (uncropped)
curl "https://api.web3identity.com/api/avatar/vitalik.eth?size=original"

---

Direct Image Endpoint

For embedding in <img> tags, use the CDN endpoint directly:

<img src="https://api.web3identity.com/cdn/avatar/vitalik.eth.png" alt="vitalik.eth" />

This returns the raw image with proper Content-Type header.

---

Errors

Code	HTTP	Description
NO_AVATAR	404	No avatar record found
INVALID_NFT	404	NFT doesn't exist
IPFS_TIMEOUT	504	IPFS gateway timeout
INVALID_FORMAT	400	Unsupported avatar format

Fallback Behavior

When no avatar is found, an identicon is generated:

{
  "identifier": "unknown.eth",
  "avatar": "https://api.web3identity.com/cdn/identicon/unknown.eth.svg",
  "type": "identicon",
  "generated": true
}

---

Related Endpoints

• ENS Resolution — Full ENS profile lookup
• Text Records — All ENS text records
• Farcaster — Farcaster profile pictures