Identity API

The Identity API provides unified access to decentralized identity protocols — ENS, Farcaster, and Lens — through simple HTTP endpoints. No API keys required for basic usage.

Overview

Resolve web3 identities across multiple protocols:

• ENS (Ethereum Name Service) — The original decentralized naming system
• Farcaster — Decentralized social protocol built on Optimism
• Lens Protocol — Decentralized social graph on Polygon

Why Use This API?

Simplicity: One HTTP request replaces complex RPC queries and graph indexing.

Reliability: 9-way fallback routing ensures high availability:

• Primary RPC → Backup RPC → The Graph → Alchemy → Infura → Etherscan → ...

Performance: Intelligent caching with stale-while-revalidate pattern.

Cost: Free tier covers most use cases (100 requests/day).

Core Endpoints

ENS (Ethereum Name Service)

Method	Path	Description
GET	/api/ens/{name}	Complete ENS profile (address, avatar, records)
GET	/api/ens/resolve/{name}	Resolve ENS name → Ethereum address
GET	/api/ens/avatar/{name}	Get avatar URL (IPFS, HTTP, or NFT)
GET	/api/ens/available/{name}	Check if ENS name is available
GET	/api/reverse/{address}	Address → ENS name (reverse resolution)
POST	/api/batch/ens	Batch resolve multiple names

Farcaster

Method	Path	Description
GET	/api/farcaster/{identifier}	Get Farcaster profile (by username, FID, or address)

Identifier Types:

• Username: alice or @alice
• FID: Farcaster ID number (e.g., 12345)
• Address: Ethereum address (e.g., 0x123...)

Lens Protocol

Method	Path	Description
GET	/api/lens/\{handle\}	Get Lens profile (by handle or address)

Use Cases

For Developers:

• Display ENS names in your dApp instead of 0x123...
• Show user avatars from ENS/NFT metadata
• Validate name availability before registration
• Build social features using Farcaster/Lens data

For Agents:

• Resolve identities autonomously
• Verify on-chain reputation
• Discover social connections
• Build trust networks

For Researchers:

• Analyze ENS adoption patterns
• Track Farcaster/Lens growth
• Study identity overlap across protocols

Quick Examples

Resolve ENS Name

curl "https://api.web3identity.com/api/ens/vitalik.eth"

Response:

{
  "name": "vitalik.eth",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "avatar": "https://ipfs.io/ipfs/Qm...",
  "records": {
    "description": "Founder of Ethereum",
    "url": "https://vitalik.ca",
    "twitter": "@VitalikButerin",
    "github": "vbuterin"
  }
}

Get Farcaster Profile

curl "https://api.web3identity.com/api/farcaster/vitalik.eth"

Response:

{
  "fid": 5650,
  "username": "vitalik.eth",
  "displayName": "Vitalik Buterin",
  "bio": "Ethereum co-founder",
  "followers": 185000,
  "following": 450,
  "pfp": "https://...",
  "verifications": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]
}

Batch Resolution (Multiple Names)

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

Reverse Resolution (Address → Name)

curl "https://api.web3identity.com/api/reverse/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Response:

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "name": "vitalik.eth"
}

Authentication & Rate Limits

Tier	Daily Limit	Auth Method	Cost
Anonymous	100 requests	None	Free
SIWE	200 requests	Sign-In with Ethereum	Free
API Key	250 requests	API key header	Free
x402	Unlimited	Pay-per-call	$0.005-0.01/call

Upgrade to higher tiers:

• SIWE Guide
• API Keys
• x402 Micropayments

Error Handling

{
  "error": "Name not found",
  "code": "ENS_NOT_FOUND",
  "message": "The ENS name 'doesnotexist.eth' does not resolve to an address"
}

Common Status Codes:

• 200 — Success
• 400 — Invalid input (malformed name/address)
• 404 — Name/profile not found
• 429 — Rate limit exceeded
• 500 — Server error (fallback failed)

Data Freshness

ENS Data:

• Cache TTL: 5 minutes (mainnet) / 1 minute (testnets)
• Source: Direct RPC → The Graph → Alchemy → Infura

Farcaster Data:

• Cache TTL: 1 minute
• Source: Neynar API v2

Lens Data:

• Cache TTL: 1 minute
• Source: Lens GraphQL API

Advanced Features

Multi-Chain Address Resolution

# Get Bitcoin address from ENS
curl "https://api.web3identity.com/api/ens/vitalik.eth?coinType=0"
# Ethereum = 60, Bitcoin = 0, Dogecoin = 3

ENS Text Records

All ENS endpoints return available text records:

• description — Profile bio
• url — Personal website
• avatar — Profile picture
• email, twitter, github, discord, etc.

IPFS Avatar Resolution

Automatically resolves IPFS avatars via public gateways:

• ipfs://Qm... → https://ipfs.io/ipfs/Qm...
• NFT avatars (ERC-721/1155) resolved to image URLs

Related Documentation

• ENS Records Guide
• Multi-Chain Addresses
• Batch Operations
• CCIP-Read (ENS L2)

Interactive Tool

Try our Web3 Identity Lookup tool:

• URL: https://web3identity.com/lookup
• Search by ENS name, address, Farcaster username
• Visual profile display with copy buttons

---

Need help? support@web3identity.com