List Subnames by Owner

Retrieve all subnames owned by a specific Ethereum address under a parent domain.

Endpoint

GET /api/subnames/{parent}/by-owner/{address}

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)
address	string	path	✅	Ethereum address (0x format)

Response

{
  "parent": "aboutme.eth",
  "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
  "count": 2,
  "subnames": [
    {
      "name": "alice",
      "fullName": "alice.aboutme.eth",
      "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
      "created_at": "2024-02-09T18:30:00.000Z",
      "expires_at": "2025-02-09T18:30:00.000Z",
      "links": {
        "profile": "https://alice.aboutme.eth.limo",
        "ens_app": "https://app.ens.domains/alice.aboutme.eth",
        "api": "https://api.web3identity.com/api/subnames/aboutme.eth/alice",
        "qr": "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=https://alice.aboutme.eth.limo"
      }
    },
    {
      "name": "mycompany",
      "fullName": "mycompany.aboutme.eth",
      "owner": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
      "created_at": "2024-02-08T12:00:00.000Z",
      "expires_at": "2025-02-08T12:00:00.000Z",
      "links": {
        "profile": "https://mycompany.aboutme.eth.limo",
        "ens_app": "https://app.ens.domains/mycompany.aboutme.eth",
        "api": "https://api.web3identity.com/api/subnames/aboutme.eth/mycompany",
        "qr": "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=https://mycompany.aboutme.eth.limo"
      }
    }
  ],
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

# List all subnames owned by an address
curl "https://api.web3identity.com/api/subnames/aboutme.eth/by-owner/0x701B4937e6c943789ffA74CC8601813b2D87B454"

JavaScript

async function getSubnamesByOwner(parent, address) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/by-owner/${address}`
  );
  return response.json();
}

// Get all names owned by an address
const myNames = await getSubnamesByOwner(
  'aboutme.eth',
  '0x701B4937e6c943789ffA74CC8601813b2D87B454'
);

console.log(`You own ${myNames.count} subnames:`);
myNames.subnames.forEach(s => console.log(`- ${s.fullName}`));

Python

import requests

def get_subnames_by_owner(parent: str, address: str):
    response = requests.get(
        f"https://api.web3identity.com/api/subnames/{parent}/by-owner/{address}"
    )
    return response.json()

my_names = get_subnames_by_owner(
    "aboutme.eth",
    "0x701B4937e6c943789ffA74CC8601813b2D87B454"
)

print(f"You own {my_names['count']} subnames")
for name in my_names['subnames']:
    print(f"- {name['fullName']}")

Use Cases

• Portfolio Display: Show all ENS subnames owned by a connected wallet
• User Dashboard: Display user's registered names with management links
• Verification: Confirm ownership of a subname before allowing edits

Error Responses

Status	Code	Description
400	INVALID_ADDRESS	Address is not valid Ethereum format
429	RATE_LIMITED	Rate limit exceeded
500	LOOKUP_ERROR	Internal server error

Related Endpoints

• Get Subname Details — Get single subname info
• Get Profile — Full profile with records
• Search — Search by owner address