Get filtered subnames

Retrieve subnames using filters like label search, owner, metadata, and pagination.

Usage

const page = await client.getFilteredSubnames({
  parentName: 'example.eth',
  metadata: { source: 'onboarding' },
  page: 1,
  size: 25,
});

console.log(page.items);

Request Parameters

export interface QuerySubnamesRequest {
  parentName?: string;
  parentNames?: string[];
  labelSearch?: string;
  page?: number;
  size?: number;
  metadata?: Record<string, string>;
  owner?: string;
}

parentName or parentNames: ENS name or names to search under
labelSearch: Substring to match subname labels (optional)
page: Page number for pagination (default: 1)
size: Number of items per page (optional)
metadata: Metadata key-value filters (optional)
owner: Filter by Ethereum address (optional)

Use parentName for one parent or parentNames for several parents.

Response

object

Show properties

number

Current page number.

number

Number of items per page.

number

Total number of items matching the query.

SubnameResponse[]

Array of subname objects.

Show SubnameResponse

string

Unique identifier for the subname record.

string

Fully-qualified ENS name (e.g., alice.example.eth).

string

Parent ENS name.

string

Label portion of the subname (e.g., alice).

Record<string, string>

Text records associated with the subname.

Record<string, string>

Address records keyed by chain name or coin type.

Record<string, string>

Custom metadata key-value pairs.

string

Content hash if set.

string

ENS namehash of the subname.

string

Ethereum address of the owner, if present.

Example

{
  "page": 1,
  "size": 2,
  "totalItems": 42,
  "items": [
    {
      "id": "01J9Q3TF3C2Z2S2X9K0V3Q6Y2B",
      "fullName": "ns.myensname.eth",
      "parentName": "myensname.eth",
      "label": "ns",
      "texts": { "name": "Namespace" },
      "addresses": { "60": "0x1234567890abcdef1234567890abcdef12345678" },
      "metadata": { "sender": "0x1234567890abcdef1234567890abcdef12345678" },
      "contenthash": null,
      "namehash": "0x5f16f2e6b2b3d1e7c3a91e8f27f5b9c3c2b7f6e2a1c0d9e8f6a5b4c3d2e1f0a9",
      "owner": "0x1234567890abcdef1234567890abcdef12345678"
    },
    {
      "id": "01J9Q3TH3D4A5B6C7D8E9F0G1H",
      "fullName": "blog.myensname.eth",
      "parentName": "myensname.eth",
      "label": "blog",
      "texts": { "url": "https://example.com" },
      "addresses": {},
      "metadata": {},
      "contenthash": "ipfs://bafybeigdyrztxotk3kxne",
      "namehash": "0xa9f0e1d2c3b4a5f6e8d9c0a1e2f6b7c2c3b9f5f7e8a1c3d7e1b2b3e6f2f6155f",
      "owner": null
    }
  ]
}

Start building

How to guides

Starter kits

Concepts

Reference

AI tooling

Troubleshooting

Get filtered subnames

Usage

Request Parameters

Response

Example

​Usage

​Request Parameters

​Response

​Example

Usage

Request Parameters

Response

Example