custom-name-resolution.md

description	sidebar_position
Resolve names to addresses and vice versa.	3

Custom name resolution

You can implement custom domain resolution and reverse resolution using the following steps.

Steps

1. Request permission to provide name resolution

Request the endowment:name-lookup permission.

For example, to resolve Ethereum Mainnet domains, add the following to your Snap's manifest file:

"initialPermissions": {
  "endowment:name-lookup": {
    "chains": ["eip155:1"]
  }
}

If you're only targeting specific TLDs or schemes, you can use the matchers property to reduce overhead by specifying the TLDs and schemes you support. To target specific TLDs (for example, my-domain.crypto), use the tlds property. To target specific schemes (for example, farcaster:my-user), use the schemes property. At least one of these properties must be specified if matchers is specified.

"initialPermissions": {
  "endowment:name-lookup": {
    "chains": ["eip155:1"],
    "matchers": { "tlds": ["crypto"], "schemes": ["farcaster"] }
  }
}

2. Implement custom name resolution

Expose an onNameLookup entry point, which receives a chainId and either a domain or an address. The following example implements a basic resolution from Unstoppable Domains domain names to Ethereum addresses in onNameLookup:

import type { OnNameLookupHandler } from "@metamask/snaps-sdk"

const UNSTOPPABLE_API_KEY = "xxx"

export const onNameLookup: OnNameLookupHandler = async (request) => {
  const { chainId, domain } = request

  if (domain && chainId === "eip155:1") {
    const response = await fetch(
      `https://api.unstoppabledomains.com/resolve/domains/${domain}`,
      {
        headers: {
          accept: "application/json",
          authorization: `Bearer ${UNSTOPPABLE_API_KEY}`,
        },
      }
    )
    const data = await response.json()
    const resolvedAddress = data.records["crypto.ETH.address"]
    if (resolvedAddress) {
      return {
        resolvedAddresses: [
          { resolvedAddress, protocol: "Unstoppable Domains", domainName: domain },
        ],
      }
    }
  }

  return null
}

:::note

The onNameLookup handler response includes a domainName property. You can use this property to perform fuzzy matching on domain names, by having the handler return the resolved domain rather than the one provided in the request.

:::

Example

See the @metamask/name-lookup-example-snap package for a full example of implementing custom name resolution.