Subname Statistics

Get aggregate statistics for a parent domain including total registrations, unique owners, and top holders.

Endpoint

GET /api/subnames/{parent}/stats

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)

Response

{
  "parent": "aboutme.eth",
  "stats": {
    "total_subnames": 156,
    "unique_owners": 142,
    "first_registration": "2024-01-15T10:00:00.000Z",
    "latest_registration": "2024-02-10T14:00:00.000Z",
    "top_owners": [
      {
        "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
        "count": 5
      },
      {
        "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
        "count": 3
      }
    ]
  },
  "links": {
    "register": "https://aboutme.eth.limo",
    "all_subnames": "https://api.web3identity.com/api/subnames/aboutme.eth/all",
    "api_docs": "https://docs.web3identity.com/api/subnames"
  },
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

curl "https://api.web3identity.com/api/subnames/aboutme.eth/stats"

JavaScript

async function getSubnameStats(parent) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/stats`
  );
  return response.json();
}

const stats = await getSubnameStats('aboutme.eth');
console.log(`Total subnames: ${stats.stats.total_subnames}`);
console.log(`Unique owners: ${stats.stats.unique_owners}`);
console.log(`Latest registration: ${stats.stats.latest_registration}`);

Python

import requests

def get_subname_stats(parent: str):
    response = requests.get(
        f"https://api.web3identity.com/api/subnames/{parent}/stats"
    )
    return response.json()

stats = get_subname_stats("aboutme.eth")
print(f"Total subnames: {stats['stats']['total_subnames']}")
print(f"Unique owners: {stats['stats']['unique_owners']}")

Use Cases

• Analytics Dashboard: Display registration metrics
• Leaderboard: Show top subname holders
• Growth Tracking: Monitor registration trends over time

Response Fields

Field	Type	Description
total_subnames	integer	Total registered subnames
unique_owners	integer	Number of distinct owner addresses
first_registration	string	Timestamp of first registration
latest_registration	string	Timestamp of most recent registration
top_owners	array	Top 5 owners by registration count

Error Responses

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

Related Endpoints

• List All — Browse all subnames
• By Owner — View specific owner's holdings