This documentation is using @aptos-labs/ts-sdk v6.0.0

Getting Names

Learn how to retrieve names from the Aptos Name Service, including domains, subdomains, and custom queries.

Getting a Name by Domain

Fetch a name by its domain:

export async function getNameByDomain() {
  // Fetch a name by domain (e.g., "example.apt")
  const name = await aptos.getName({ name: "example.apt" });

  if (name) {
    console.log("Name found:", name.domain);
    console.log("Owner:", name.owner_address);
    console.log("Expiration:", name.expiration);
  } else {
    console.log("Name not found or unclaimed");
  }

  return name;
}

Getting a Name with Subdomain

Fetch a subdomain name:

export async function getNameWithSubdomain() {
  // Fetch a subdomain name (e.g., "subdomain.example.apt")
  const name = await aptos.getName({ name: "subdomain.example.apt" });

  if (name) {
    console.log("Subdomain found:", name);
    console.log("Domain:", name.domain);
    console.log("Subdomain:", name.subdomain);
    console.log("Owner:", name.owner_address);
  } else {
    console.log("Subdomain not found or unclaimed");
  }

  return name;
}

Getting Primary Name by Address

The primary name is the name that an address has set as their primary identifier. An address can have at most one primary name.

export async function getPrimaryNameByAddress() {
  const address = "0x1234567890abcdef1234567890abcdef12345678";

  // Get the primary name for an address
  const primaryName = await aptos.getPrimaryName({ address });

  if (primaryName) {
    console.log("Primary name:", primaryName);
    console.log("Full name:", `${primaryName}.apt`);
  } else {
    console.log("No primary name set for this address");
  }

  return primaryName;
}

Getting All Names for an Address

To get all names owned by an address (including primary and non-primary names):

export async function getAllNamesForAddress() {
  const accountAddress = "0x1234567890abcdef1234567890abcdef12345678";

  // Get all names for an address
  const result = await aptos.getAccountNames({ accountAddress });

  console.log(`Found ${result.names.length} name(s) for address ${accountAddress}`);

  result.names.forEach((name) => {
    const nameString = name.subdomain
      ? `${name.subdomain}.${name.domain}.apt`
      : `${name.domain}.apt`;
    console.log(`- ${nameString} (Primary: ${name.is_primary})`);
  });

  return result;
}

Getting Domains for an Account

Get all domains owned by an account with pagination support:

export async function getAccountDomains() {
  const accountAddress = "0x1234567890abcdef1234567890abcdef12345678";

  // Get domains with pagination
  const result = await aptos.getAccountDomains({
    accountAddress,
    options: {
      offset: 0,
      limit: 10,
    },
  });

  console.log(`Total domains: ${result.total}`);
  console.log(`Found ${result.names.length} domain(s)`);

  result.names.forEach((name) => {
    console.log(`- ${name.domain}.apt`);
    console.log(`  Owner: ${name.owner_address}`);
    console.log(`  Expiration: ${name.expiration.toLocaleDateString()}`);
  });

  return result;
}

Getting Subdomains for a Domain

Get all subdomains for a specific domain:

export async function getDomainSubdomains() {
  const domain = "example";

  // Get subdomains with pagination
  const result = await aptos.getDomainSubdomains({
    domain,
    options: {
      offset: 0,
      limit: 10,
    },
  });

  console.log(`Total subdomains: ${result.total}`);
  console.log(`Found ${result.names.length} subdomain(s)`);

  result.names.forEach((name) => {
    console.log(`- ${name.subdomain}.${name.domain}.apt`);
    console.log(`  Owner: ${name.owner_address}`);
    console.log(`  Expiration: ${name.expiration.toLocaleDateString()}`);
  });

  return result;
}

Getting Orphaned Subdomains (Custom Query)

Get subdomains owned by an account that are not owned by the domain owner. This is useful for finding subdomains that were transferred, for example, Petra Free Names. A subdomain name you receive when you register a new wallet with Petra:

export async function getOrphanedSubdomains() {
  const accountAddress = "0x1234567890abcdef1234567890abcdef12345678";

  // Get orphaned subdomains using a custom query
  const result = await aptos.ans.getAccountSubdomains({
    accountAddress,
    options: {
      offset: 0,
      limit: 10,
      where: {
        _not: { is_domain_owner: {} },
      },
    },
  });

  console.log(`Total orphaned subdomains: ${result.total}`);
  console.log(`Found ${result.names.length} orphaned subdomain(s)`);

  result.names.forEach((name) => {
    console.log(`- ${name.subdomain}.${name.domain}.apt`);
    console.log(`  Owner: ${name.owner_address}`);
  });

  return result;
}

Working with Pagination

Many queries support pagination. Here's how to handle paginated results:

export async function getAllDomains(accountAddress: string) {
  const limit = 10;
  let offset = 0;
  const allDomains: Awaited<ReturnType<typeof aptos.getAccountDomains>>["names"] = [];
  let hasMore = true;

  while (hasMore) {
    const result = await aptos.getAccountDomains({
      accountAddress,
      options: { offset, limit },
    });

    allDomains.push(...result.names);
    hasMore = offset + limit < result.total;
    offset += limit;
  }

  return allDomains;
}

Filtering and Querying

You can filter results using query options:

export async function filterAndQueryNames() {
  const accountAddress = "0x1234567890abcdef1234567890abcdef12345678";

  // Get all names and filter for primary names
  const result = await aptos.getAccountNames({ accountAddress });
  const allNames = result.names;

  // Filter primary names
  const primaryNames = allNames.filter((name) => name.is_primary);

  // Filter non-primary names
  const nonPrimaryNames = allNames.filter((name) => !name.is_primary);

  // Filter by expiration status
  const activeNames = allNames.filter((name) => name.expiration_status === "active");

  return {
    allNames,
    primaryNames,
    nonPrimaryNames,
    activeNames,
  };
}

Complete Example

Here's a comprehensive example that demonstrates multiple ways to get names:

export async function comprehensiveNameQueries() {
  const accountAddress = "0x1234567890abcdef1234567890abcdef12345678";

  // 1. Get a specific name
  const name = await aptos.getName({ name: "example.apt" });
  if (name) {
    console.log("Name found:", name.domain);
  }

  // 2. Get primary name
  const primaryName = await aptos.getPrimaryName({ address: accountAddress });
  if (primaryName) {
    console.log("Primary name:", primaryName);
  }

  // 3. Get all names for address
  const allNamesResult = await aptos.getAccountNames({ accountAddress });
  console.log(`Total names: ${allNamesResult.names.length}`);

  // 4. Get domains with pagination
  const domains = await aptos.getAccountDomains({
    accountAddress,
    options: { offset: 0, limit: 10 },
  });
  console.log(`Total domains: ${domains.total}`);

  // 5. Get subdomains for a domain
  const subdomains = await aptos.getDomainSubdomains({
    domain: "example",
    options: { offset: 0, limit: 10 },
  });
  console.log(`Total subdomains: ${subdomains.total}`);

  // 6. Get orphaned subdomains
  const orphaned = await aptos.ans.getAccountSubdomains({
    accountAddress,
    options: {
      offset: 0,
      limit: 10,
      where: {
        _not: { is_domain_owner: {} },
      },
    },
  });
  console.log(`Orphaned subdomains: ${orphaned.total}`);

  return {
    name,
    primaryName,
    allNames: allNamesResult,
    domains,
    subdomains,
    orphaned,
  };
}

Documentation