List Subnames

List all registered subnames under a parent ENS domain with pagination support.

Endpoint

GET /api/subnames/{parent}

Authentication

None required — This is a public read endpoint.

Parameters

Parameter	Type	Location	Required	Description
parent	string	path	✅	Parent ENS name (e.g., aboutme.eth)
limit	integer	query	❌	Max results to return (default: 100, max: 500)
offset	integer	query	❌	Number of results to skip (default: 0)

Response

{
  "parent": "aboutme.eth",
  "subnames": [
    {
      "name": "alice.aboutme.eth",
      "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
      "created_at": "2024-02-09T18:30:00.000Z",
      "expires_at": "2025-02-09T18:30:00.000Z"
    },
    {
      "name": "bob.aboutme.eth",
      "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "created_at": "2024-02-08T12:00:00.000Z",
      "expires_at": "2025-02-08T12:00:00.000Z"
    }
  ],
  "count": 2,
  "total": 156,
  "limit": 100,
  "offset": 0,
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

# List first 10 subnames
curl "https://api.web3identity.com/api/subnames/aboutme.eth?limit=10"

# Paginate through results
curl "https://api.web3identity.com/api/subnames/aboutme.eth?limit=50&offset=50"

JavaScript

// List subnames with pagination
async function listSubnames(parent, limit = 100, offset = 0) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}?limit=${limit}&offset=${offset}`
  );
  return response.json();
}

// Get all subnames (paginated)
const result = await listSubnames('aboutme.eth', 50, 0);
console.log(`Found ${result.total} total subnames`);

Python

import requests

def list_subnames(parent: str, limit: int = 100, offset: int = 0):
    response = requests.get(
        f"https://api.web3identity.com/api/subnames/{parent}",
        params={"limit": limit, "offset": offset}
    )
    return response.json()

result = list_subnames("aboutme.eth", limit=50)
print(f"Found {result['total']} total subnames")

Error Responses

Status	Code	Description
400	BAD_REQUEST	Invalid parent name format
429	RATE_LIMITED	Rate limit exceeded
500	SUBNAME_ERROR	Internal server error

Rate Limits

Tier	Daily Limit
Anonymous	100 requests
SIWE	200 requests
x402	Unlimited

Related Endpoints

• List All (Detailed) — Full details with links
• Search — Search by name or owner
• Stats — Global statistics