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 ↗
