ENS Metadata V2

---

Next-generation ENS metadata service built on Cloudflare Workers for ENS v1 and v2 on Ethereum (mainnet + sepolia testnet).

• ENS v1 & v2 Support: Native v2 names and legacy v1 names on Ethereum
• High Performance: Cloudflare Workers edge computing with global distribution
• Smart Caching: Edge + KV + R2 caching; the KV and R2 tiers use migration-aware, stale-while-revalidate TTLs, while the per-colo edge tier is a flat 300s cap
• Fallback Resilience: For name lookups, direct chain queries when the indexers are unavailable or simply don't know the name, then a stale D1 row as a last resort (the contract/tokenId reverse lookup is indexer-only)
• SVG Generation: Canvas-free SVG card generation, with in-Worker PNG rasterization via resvg/HarfBuzz WASM

Example

curl https://ens-metadata.ens-cf.workers.dev/mainnet/registry/ethereum.eth         # metadata (JSON)
curl https://ens-metadata.ens-cf.workers.dev/mainnet/registry/ethereum.eth/image   # NFT card (SVG)
curl https://ens-metadata.ens-cf.workers.dev/mainnet/avatar/ethereum.eth           # avatar image

Rendered live by the deployment.

API

{network} is mainnet or sepolia. Opened in a browser tab, an image endpoint shows a page with the image and the endpoint's documentation; <img>, fetch() and API clients get the image itself.

Method	Path	Returns
GET	/	Service info (service, version, status, timestamp)
GET	/{network}/{registryType}/{identifier}	NFT metadata (JSON)
GET	/{network}/{registryType}/{identifier}/image	NFT card (SVG)
GET	/{network}/{registryType}/{identifier}/rasterize	NFT card (PNG)
GET	/{network}/avatar/{name}	Avatar image (the avatar text record)
GET	/{network}/avatar/{name}/meta	Avatar record metadata (JSON, v1 parity)
GET	/{network}/header/{name}	Header image (the header text record)
GET	/migration-status/{name}?network=	Migration status
GET	/registry-hierarchy/{name}?network=	Registry hierarchy
POST	/batch-metadata	Metadata for many names at once
POST	/webhook	Indexer webhook (HMAC-authenticated)
GET	/health	Health check

This is the beginning of the README. Read the rest at the original. Read the full README ↗