Bulk Lookups

Efficiently resolve hundreds or thousands of identities in a single request.

Endpoints

Endpoint	Description	Price
POST /api/bulk/ens	Bulk ENS resolution	$0.005/name
POST /api/bulk/reverse	Bulk reverse resolution	$0.005/addr
POST /api/bulk/profiles	Bulk full profiles	$0.01/name
GET /api/bulk/status/{jobId}	Check job status	Free

---

POST /api/bulk/ens

Resolve many ENS names to addresses.

Request

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

Response (Synchronous)

For ≤100 names, results are returned immediately:

{
  "results": [
    { "name": "vitalik.eth", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
    { "name": "nick.eth", "address": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5" },
    { "name": "brantly.eth", "address": "0x983110309620D911731Ac0932219af06091b6744" },
    { "name": "gregskril.eth", "address": "0x179A862703a4adfb29896552DF9e307980D19285" },
    { "name": "slobo.eth", "address": "0x7F27b0F7D6c6C7E8479E7b0d3F8C7A7b4A5C6D2E" }
  ],
  "resolved": 5,
  "failed": 0,
  "errors": []
}

SDK

const results = await client.bulkResolve([
  'vitalik.eth',
  'nick.eth',
  'brantly.eth'
]);

---

Async Mode (Large Batches)

For >100 names, use async mode:

Request

curl -X POST https://api.web3identity.com/api/bulk/ens \
  -H "Content-Type: application/json" \
  -d '{
    "names": ["name1.eth", "name2.eth", ... ],
    "async": true,
    "webhook": "https://yourserver.com/webhook"
  }'

Response

{
  "jobId": "bulk_abc123xyz",
  "status": "processing",
  "total": 5000,
  "estimatedSeconds": 45,
  "statusUrl": "https://api.web3identity.com/api/bulk/status/bulk_abc123xyz"
}

Poll Status

curl https://api.web3identity.com/api/bulk/status/bulk_abc123xyz

{
  "jobId": "bulk_abc123xyz",
  "status": "completed",
  "progress": {
    "processed": 5000,
    "total": 5000,
    "percentage": 100
  },
  "results": {
    "resolved": 4823,
    "failed": 177
  },
  "downloadUrl": "https://api.web3identity.com/api/bulk/download/bulk_abc123xyz",
  "expiresAt": "2026-02-09T04:30:00Z"
}

---

POST /api/bulk/reverse

Bulk reverse resolution (addresses to names).

Request

curl -X POST https://api.web3identity.com/api/bulk/reverse \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
      "0x983110309620D911731Ac0932219af06091b6744"
    ]
  }'

Response

{
  "results": [
    { "address": "0xd8dA...", "name": "vitalik.eth" },
    { "address": "0xb8c2...", "name": "nick.eth" },
    { "address": "0x9831...", "name": "brantly.eth" }
  ],
  "resolved": 3,
  "failed": 0
}

SDK

const names = await client.bulkReverse([
  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  '0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5'
]);

---

POST /api/bulk/profiles

Get full profiles for multiple names.

Request

curl -X POST https://api.web3identity.com/api/bulk/profiles \
  -H "Content-Type: application/json" \
  -d '{
    "names": ["vitalik.eth", "nick.eth"],
    "include": ["avatar", "records", "socials"]
  }'

Response

{
  "profiles": [
    {
      "name": "vitalik.eth",
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "avatar": "https://api.web3identity.com/cdn/avatar/vitalik.eth.png",
      "records": {
        "com.twitter": "VitalikButerin",
        "com.github": "vbuterin"
      }
    },
    {
      "name": "nick.eth",
      "address": "0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5",
      "avatar": "https://api.web3identity.com/cdn/avatar/nick.eth.png",
      "records": {
        "com.twitter": "nicksdjohnson",
        "com.github": "arachnid"
      }
    }
  ],
  "count": 2
}

Include Options

Option	Description
avatar	Include avatar URL
records	Include all text records
socials	Include normalized social links
addresses	Include multi-chain addresses
expiration	Include registration expiry

---

Rate Limits & Pricing

Tier	Max per Request	Price per Name
Free	10	$0.01
Basic	100	$0.005
Pro	1,000	$0.003
Enterprise	10,000	$0.001

Cost Examples

Names	Tier	Total Cost
50	Basic	$0.25
500	Pro	$1.50
5,000	Enterprise	$5.00

---

CSV Upload

Upload a CSV file of names:

Request

curl -X POST https://api.web3identity.com/api/bulk/upload \
  -H "Content-Type: multipart/form-data" \
  -F "file=@names.csv" \
  -F "column=ens_name"

CSV Format

ens_name,other_data
vitalik.eth,123
nick.eth,456
brantly.eth,789

Response

{
  "jobId": "upload_xyz789",
  "parsed": 1000,
  "status": "processing"
}

---

Download Results

JSON Format

curl https://api.web3identity.com/api/bulk/download/bulk_abc123xyz

CSV Format

curl "https://api.web3identity.com/api/bulk/download/bulk_abc123xyz?format=csv"

CSV Output

name,address,resolved
vitalik.eth,0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045,true
nick.eth,0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5,true
invalid.eth,,false

---

Webhook Notifications

Receive notification when async job completes:

curl -X POST https://api.web3identity.com/api/bulk/ens \
  -H "Content-Type: application/json" \
  -d '{
    "names": [...],
    "async": true,
    "webhook": "https://yourserver.com/bulk-complete",
    "webhookSecret": "your-secret-key"
  }'

Webhook Payload

{
  "event": "bulk.completed",
  "jobId": "bulk_abc123xyz",
  "status": "completed",
  "results": {
    "resolved": 4823,
    "failed": 177
  },
  "downloadUrl": "https://api.web3identity.com/api/bulk/download/bulk_abc123xyz"
}

The webhook includes an X-Webhook-Signature header for verification.

---

Errors

Code	HTTP	Description
TOO_MANY_NAMES	400	Exceeded max names for tier
INVALID_CSV	400	CSV parsing failed
JOB_NOT_FOUND	404	Job ID doesn't exist
JOB_EXPIRED	410	Results expired (24h)

---

Related Endpoints

• ENS Resolution — Single name lookup
• Text Records — Record queries
• Farcaster — Social profile data