Reverse lookup of an Ethereum address to a primary name

Performs a reverse lookup of an Ethereum address to a primary name.

Data sources for the primary name lookup include:

1. The Ethereum Provider configured in the NameGuard instance.
2. For ENS names using CCIP-Read: requests to externally defined gateway servers.

Returns display_name to be shown to users and estimates impersonation_status.

cURL

curl --request GET \
  --url https://api.nameguard.io/secure-primary-name/{network_name}/{address}

Path Parameters

address

string

required

network_name

enum<string>

required

Available options:

mainnet,

sepolia

Response

200

application/json

Successful Response

Reverse lookup result.

primary_name_status

enum<string>

required

The status of a secure primary ENS name lookup performed by NameGuard.

• normalized: The ENS primary name was found and it is normalized.
• no_primary_name: The ENS primary name was not found.
• unnormalized: The ENS primary name was found, but it is not normalized.

Available options:

normalized,

no_primary_name,

unnormalized

impersonation_status

enum<string> | null

required

Impersonation status of the primary_name.

• null if primary_name is null

Available options:

unlikely,

potential

primary_name

string | null

required

Primary ENS name for the Ethereum address.

• null if primary_name_status is any value except normalized

Example:

"vitalik.eth"

display_name

string

required

ENS beautified version of primary_name.

• if primary_name is null then provides a fallback display_name of "Unnamed [first four hex digits of Ethereum address]", e.g. "Unnamed c2a6"

Example:

"vitalik.eth"

nameguard_result

object | null

required

NameGuard report for the primary_name.

• null if primary_name_status is no_primary_name (primary name is not found)

Show child attributes

nameguard_result.rating

enum<integer>

required

The rating of a name/label/grapheme based on multiple conducted checks.

• pass: All checks passed.
• warn: At least one check failed with a WARN status but no check failed with an ALERT status.
• alert: At least one check failed with an ALERT status.

Available options:

2,

3,

4

Example:

3

nameguard_result.risk_count

integer

required

The number of checks that have a status of alert or warn.

Example:

2

nameguard_result.highest_risk

object | null

required

The check considered to be the highest risk. If no check has a status of alert or warn, this field is null.

Show child attributes

nameguard_result.highest_risk.check

enum<string>

required

The type of a check.

Common:

• normalized: A name/label/grapheme is ENSIP-15 normalized.

Grapheme:

• confusables: A grapheme is visually confusable.
• invisible: A grapheme is invisible.
• typing_difficulty: A grapheme is difficult to type.
• font_support: A grapheme is not supported by common fonts.

Label:

• mixed_scripts: A label contains multiple scripts.
• namewrapper_compatible: TODO
• punycode_compatible_label: A label is compatible with Punycode.
• unknown_label: A label is unknown.

Name:

• impersonation_risk: A name might be used for impersonation.
• punycode_compatible_name: A name is compatible with Punycode.
• namewrapper_fuses: The NameWrapper configuration of a name is safe.
• decentralized_name: A name is decentralized.

Available options:

normalized,

confusables,

invisible,

typing_difficulty,

font_support,

mixed_scripts,

namewrapper_compatible,

punycode_compatible_label,

unknown_label,

impersonation_risk,

punycode_compatible_name,

namewrapper_fuses,

decentralized_name

Example:

"confusables"

nameguard_result.highest_risk.status

enum<integer>

required

The status of a conducted check.

• skip: This check was skipped because it was not applicable.
• info: This check is informational only.
• pass: This check passed.
• warn: This check failed, this is a minor issue.
• alert: This check failed, this is a major issue.

Available options:

0,

1,

2,

3,

4

Example:

3

nameguard_result.highest_risk.message

string

required

A message describing the result of the check.

nameguard_result.highest_risk.check_name

string

required

The human-readable name of the check.

nameguard_result.name

string

required

The analyzed name. Can contain labelhashes when some labels are unknown.

Example:

"vitalìk.eth"

nameguard_result.namehash

string

required

The namehash of the name in hex format prefixed with 0x.

Example:

"0xd48fd5598e605861cbd8e45419b41b83739bff52eaef0e283181bbe0a43a5b32"

nameguard_result.normalization

enum<string>

required

The ENSIP-15 normalization status of a name or label.

• normalized: The name or label is normalized.
• unnormalized: The name or label is not normalized.
• unknown: The name or label is unknown because it cannot be looked up from its hash.

Available options:

normalized,

unnormalized,

unknown

nameguard_result.checks

object[]

required

A list of checks that were performed on the name.

The result of a conducted check.

Show child attributes

nameguard_result.checks.check

enum<string>

required

The type of a check.

Common:

• normalized: A name/label/grapheme is ENSIP-15 normalized.

Grapheme:

• confusables: A grapheme is visually confusable.
• invisible: A grapheme is invisible.
• typing_difficulty: A grapheme is difficult to type.
• font_support: A grapheme is not supported by common fonts.

Label:

• mixed_scripts: A label contains multiple scripts.
• namewrapper_compatible: TODO
• punycode_compatible_label: A label is compatible with Punycode.
• unknown_label: A label is unknown.

Name:

• impersonation_risk: A name might be used for impersonation.
• punycode_compatible_name: A name is compatible with Punycode.
• namewrapper_fuses: The NameWrapper configuration of a name is safe.
• decentralized_name: A name is decentralized.

Available options:

normalized,

confusables,

invisible,

typing_difficulty,

font_support,

mixed_scripts,

namewrapper_compatible,

punycode_compatible_label,

unknown_label,

impersonation_risk,

punycode_compatible_name,

namewrapper_fuses,

decentralized_name

Example:

"confusables"

nameguard_result.checks.status

enum<integer>

required

The status of a conducted check.

• skip: This check was skipped because it was not applicable.
• info: This check is informational only.
• pass: This check passed.
• warn: This check failed, this is a minor issue.
• alert: This check failed, this is a major issue.

Available options:

0,

1,

2,

3,

4

Example:

3

nameguard_result.checks.message

string

required

A message describing the result of the check.

nameguard_result.checks.check_name

string

required

The human-readable name of the check.

nameguard_result.labels

object[]

required

The analyzed labels of the name.

Label analysis result.

Show child attributes

nameguard_result.labels.rating

enum<integer>

required

The rating of a name/label/grapheme based on multiple conducted checks.

• pass: All checks passed.
• warn: At least one check failed with a WARN status but no check failed with an ALERT status.
• alert: At least one check failed with an ALERT status.

Available options:

2,

3,

4

Example:

3

nameguard_result.labels.risk_count

integer

required

The number of checks that have a status of alert or warn.

Example:

2

nameguard_result.labels.highest_risk

object | null

required

The check considered to be the highest risk. If no check has a status of alert or warn, this field is null.

Show child attributes

nameguard_result.labels.highest_risk.check

enum<string>

required

The type of a check.

Common:

• normalized: A name/label/grapheme is ENSIP-15 normalized.

Grapheme:

• confusables: A grapheme is visually confusable.
• invisible: A grapheme is invisible.
• typing_difficulty: A grapheme is difficult to type.
• font_support: A grapheme is not supported by common fonts.

Label:

• mixed_scripts: A label contains multiple scripts.
• namewrapper_compatible: TODO
• punycode_compatible_label: A label is compatible with Punycode.
• unknown_label: A label is unknown.

Name:

• impersonation_risk: A name might be used for impersonation.
• punycode_compatible_name: A name is compatible with Punycode.
• namewrapper_fuses: The NameWrapper configuration of a name is safe.
• decentralized_name: A name is decentralized.

Available options:

normalized,

confusables,

invisible,

typing_difficulty,

font_support,

mixed_scripts,

namewrapper_compatible,

punycode_compatible_label,

unknown_label,

impersonation_risk,

punycode_compatible_name,

namewrapper_fuses,

decentralized_name

Example:

"confusables"

nameguard_result.labels.highest_risk.status

enum<integer>

required

The status of a conducted check.

• skip: This check was skipped because it was not applicable.
• info: This check is informational only.
• pass: This check passed.
• warn: This check failed, this is a minor issue.
• alert: This check failed, this is a major issue.

Available options:

0,

1,

2,

3,

4

Example:

3

nameguard_result.labels.highest_risk.message

string

required

A message describing the result of the check.

nameguard_result.labels.highest_risk.check_name

string

required

The human-readable name of the check.

nameguard_result.labels.label

string

required

The analyzed label. If the label is unknown, this field is [labelhash].

Example:

"vitalìk"

nameguard_result.labels.labelhash

string

required

The labelhash of the label in hex format prefixed with 0x.

Example:

"0x41459971a5b847d0eef67bc11e2845f1074a2aed1ac6a357378b18fba50816e4"

nameguard_result.labels.normalization

enum<string>

required

The ENSIP-15 normalization status of a name or label.

• normalized: The name or label is normalized.
• unnormalized: The name or label is not normalized.
• unknown: The name or label is unknown because it cannot be looked up from its hash.

Available options:

normalized,

unnormalized,

unknown

nameguard_result.labels.checks

object[]

required

A list of checks that were performed on the label.

The result of a conducted check.

Show child attributes

nameguard_result.labels.checks.check

enum<string>

required

The type of a check.

Common:

• normalized: A name/label/grapheme is ENSIP-15 normalized.

Grapheme:

• confusables: A grapheme is visually confusable.
• invisible: A grapheme is invisible.
• typing_difficulty: A grapheme is difficult to type.
• font_support: A grapheme is not supported by common fonts.

Label:

• mixed_scripts: A label contains multiple scripts.
• namewrapper_compatible: TODO
• punycode_compatible_label: A label is compatible with Punycode.
• unknown_label: A label is unknown.

Name:

• impersonation_risk: A name might be used for impersonation.
• punycode_compatible_name: A name is compatible with Punycode.
• namewrapper_fuses: The NameWrapper configuration of a name is safe.
• decentralized_name: A name is decentralized.

Available options:

normalized,

confusables,

invisible,

typing_difficulty,

font_support,

mixed_scripts,

namewrapper_compatible,

punycode_compatible_label,

unknown_label,

impersonation_risk,

punycode_compatible_name,

namewrapper_fuses,

decentralized_name

Example:

"confusables"

nameguard_result.labels.checks.status

enum<integer>

required

The status of a conducted check.

• skip: This check was skipped because it was not applicable.
• info: This check is informational only.
• pass: This check passed.
• warn: This check failed, this is a minor issue.
• alert: This check failed, this is a major issue.

Available options:

0,

1,

2,

3,

4

Example:

3

nameguard_result.labels.checks.message

string

required

A message describing the result of the check.

nameguard_result.labels.checks.check_name

string

required

The human-readable name of the check.

nameguard_result.labels.graphemes

object[] | null

required

A list of graphemes that were analyzed in the label. If the label is unknown, this field is null.

Grapheme analysis result.

Show child attributes

nameguard_result.labels.graphemes.rating

enum<integer>

required

The rating of a name/label/grapheme based on multiple conducted checks.

• pass: All checks passed.
• warn: At least one check failed with a WARN status but no check failed with an ALERT status.
• alert: At least one check failed with an ALERT status.

Available options:

2,

3,

4

Example:

3

nameguard_result.labels.graphemes.risk_count

integer

required

The number of checks that have a status of alert or warn.

Example:

2

nameguard_result.labels.graphemes.highest_risk

object | null

required

The check considered to be the highest risk. If no check has a status of alert or warn, this field is null.

Show child attributes

nameguard_result.labels.graphemes.highest_risk.check

enum<string>

required

The type of a check.

Common:

• normalized: A name/label/grapheme is ENSIP-15 normalized.

Grapheme:

• confusables: A grapheme is visually confusable.
• invisible: A grapheme is invisible.
• typing_difficulty: A grapheme is difficult to type.
• font_support: A grapheme is not supported by common fonts.

Label:

• mixed_scripts: A label contains multiple scripts.
• namewrapper_compatible: TODO
• punycode_compatible_label: A label is compatible with Punycode.
• unknown_label: A label is unknown.

Name:

• impersonation_risk: A name might be used for impersonation.
• punycode_compatible_name: A name is compatible with Punycode.
• namewrapper_fuses: The NameWrapper configuration of a name is safe.
• decentralized_name: A name is decentralized.

Available options:

normalized,

confusables,

invisible,

typing_difficulty,

font_support,

mixed_scripts,

namewrapper_compatible,

punycode_compatible_label,

unknown_label,

impersonation_risk,

punycode_compatible_name,

namewrapper_fuses,

decentralized_name

Example:

"confusables"

nameguard_result.labels.graphemes.highest_risk.status

enum<integer>

required

The status of a conducted check.

• skip: This check was skipped because it was not applicable.
• info: This check is informational only.
• pass: This check passed.
• warn: This check failed, this is a minor issue.
• alert: This check failed, this is a major issue.

Available options:

0,

1,

2,

3,

4

Example:

3

nameguard_result.labels.graphemes.highest_risk.message

string

required

A message describing the result of the check.

nameguard_result.labels.graphemes.highest_risk.check_name

string

required

The human-readable name of the check.

nameguard_result.labels.graphemes.normalization

enum<string>

required

The ENSIP-15 normalization status of a grapheme. This check does not consider the context of the grapheme and is not equivalent to ens_normalize(grapheme). A normalized grapheme can be combined with other normalized graphemes to form an unnormalized label. The position of a grapheme in a label can also affect the normalization status of the label.

• normalized: The grapheme is normalized.
• unnormalized: The grapheme is not normalized.

Available options:

normalized,

unnormalized

nameguard_result.labels.graphemes.grapheme

string

required

The analyzed grapheme.

Example:

"v"

nameguard_result.labels.graphemes.grapheme_name

string

required

The name of the grapheme.

Example:

"Latin Small Letter V"

nameguard_result.labels.graphemes.grapheme_type

string

required

The type of the grapheme. If all characters in the grapheme have the same type, that type is returned. Otherwise, special is returned.

• simple_letter - [a-z]
• simple_number - [0-9]
• other_letter - a letter (single-char grapheme) in any script that is not simple; LC class http://www.unicode.org/reports/tr44/#GC_Values_Table
• other_number - a digit (single-char grapheme) in any script that is not simple; N class http://www.unicode.org/reports/tr44/#GC_Values_Table
• hyphen - a hyphen
• dollarsign - a dollar sign
• underscore - an underscore
• emoji - an emoji or emoji ZWJ sequence
• invisible - zero width joiner or non-joiner
• special - for any grapheme that doesn't match one of the other classifications or if characters have different types

Example:

"simple_letter"

nameguard_result.labels.graphemes.grapheme_script

string

required

Script name of the grapheme computed from the script names of its characters.

Example:

"Latin"

nameguard_result.labels.graphemes.grapheme_description

string

required

Description of the grapheme type.

Example:

"A-Z letter"

nameguard_result.labels.graphemes.title

string

required

A human-readable title based on the rating.

nameguard_result.labels.graphemes.subtitle

string

required

A human-readable subtitle based on the rating.

nameguard_result.labels.canonical_label

string | null

required

The canonical form of the analyzed label.

• null if the canonical form of any grapheme is not known
• null if the result would be unnormalized, even if the canonical form of all graphemes is known
• [labelhash] if the label is unknown

Example:

"vitalik"

nameguard_result.labels.title

string

required

A human-readable title based on the rating.

nameguard_result.labels.subtitle

string

required

A human-readable subtitle based on the rating.

nameguard_result.labels.beautiful_label

string | null

required

Beautified version of label.

nameguard_result.canonical_name

string | null

required

The canonical form of the analyzed name.

• null if the canonical form of any label is not known
• can contain labelhashes when some labels are unknown

Example:

"vitalik.eth"

nameguard_result.title

string

required

A human-readable title based on the rating.

nameguard_result.subtitle

string

required

A human-readable subtitle based on the rating.

nameguard_result.beautiful_name

string | null

required

Beautified version of name.