ENS resolution API — forward and reverse, multi-chain, with per-item caching.

Swagger UI · OpenAPI JSON · Telegram · Twitter

---

What it does

• Forward resolution — ENS name → addresses (any chain), text records, content hash, full profile
• Reverse resolution — Ethereum address → primary ENS name, with bulk support
• Multi-chain — resolve addresses by chain name (eth, base, btc) or coinType number (60, 0)
• Per-item caching — cache hits on individual keys don't block fetching misses
• Single RPC call — /profile fetches texts + addresses + contenthash in one request

---

Quick start

cp .env.example .env   # fill in RPC_URL
npm install
npm run start:dev

The API will be available at http://localhost:3000.

---

Environment variables

Variable	Description	Default
RPC_URL	Ethereum mainnet RPC endpoint	— (required)
FORWARD_RESOLVE_CACHE_EXPIRY	Forward cache TTL in seconds. 0 disables caching.	300
REVERSE_RESOLVE_CACHE_EXPIRY	Reverse cache TTL in seconds. 0 disables caching.	1800
MAX_BULK_REVERSE_REQUEST	Max addresses per bulk reverse request	20
MAX_BULK_PROFILE_REQUEST	Max names per bulk profile request	20
ENABLE_DOCS	Expose Swagger UI at /api-docs and OpenAPI JSON at /api-docs.json	false
DEBUG_MODE	Log request and response details at debug level	false
IS_TESTNET	Use ENS testnet registry	false

---

API

Forward resolution

Method	Path	Description
GET	/ens/v2/profile/:name	Full profile — texts, addresses, contenthash in one RPC call
GET	/ens/v2/profile/bulk	Profiles for multiple names in parallel
GET	/ens/v2/texts/:name	Text records
GET	/ens/v2/addresses/:name	Addresses by chain name or coinType
GET	/ens/v2/contenthash/:name	Content hash
GET	/ens/v2/chains	All supported chains with name and coinType
DELETE	/ens/v2/cache/:name	Clear cached records for a name

Reverse resolution

Method	Path	Description
GET	/ens/v2/reverse/:address	Single address → ENS name
GET	/ens/v2/reverse/bulk	Multiple addresses → ENS names (batched RPC call)

---

Usage examples

# Full default profile (12 text keys, 8 chains, contenthash)
curl https://api.resolvio.xyz/ens/v2/profile/vitalik.eth

# Custom selection
curl "https://api.resolvio.xyz/ens/v2/profile/vitalik.eth?texts=avatar,com.twitter&addresses=eth,base,btc&contenthash=false"

# Bulk profiles (up to 20 names)
curl "https://api.resolvio.xyz/ens/v2/profile/bulk?names=vitalik.eth,artii.eth"

# Addresses by chain name or coinType
curl "https://api.resolvio.xyz/ens/v2/addresses/vitalik.eth?chains=eth,base,btc"
curl "https://api.resolvio.xyz/ens/v2/addresses/vitalik.eth?coins=60,2147492101"

# Text records
curl "https://api.resolvio.xyz/ens/v2/texts/vitalik.eth?keys=avatar,description,com.twitter"

# Content hash
curl "https://api.resolvio.xyz/ens/v2/contenthash/vitalik.eth"

# Reverse resolve
curl "https://api.resolvio.xyz/ens/v2/reverse/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

# Bulk reverse resolve (up to 20 addresses)
curl "https://api.resolvio.xyz/ens/v2/reverse/bulk?addresses=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045,0x225f137127d9067788314bc7fcc1f36746a3c3B5"

All endpoints accept ?noCache=true to bypass the in-memory cache.

---

Deployment

Production: https://api.resolvio.xyz

docker build -t resolvio .
docker run -p 3000:3000 --env-file .env resolvio

---

AI agent skill

The file .agent/skills/resolvio/SKILL.md is an LLM-readable reference for this API — endpoints, parameters, response shapes, and key behaviours. Load it into any AI agent or MCP context to give it full Resolvio awareness.

---

Tests

E2E tests make real network calls against ENS — no mocks.

npm run test:e2e

---

Author

Built by @nenadmitt · Namespace

Telegram · Twitter