NFD API
Search
⌃K

Resolving an Algorand address to an NFD name / avatar

The API used for reverse address lookup is the same in all cases. The distinctions come in levels of trust that the caller expects.
The /nfd/v2/address endpoint returns a list of NFD matches PER provided Address. The 'tiny' view is used by default - with minimal information returned per match.

REST API Call

get
https://api.nf.domains
/nfd/v2/address
Reverse Address lookup with results returned per address
Example response
{
"2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4": [
{
"appID": 764594795,
"caAlgo": [
"D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4",
"AW3ZJNEVJKKICLA6JQ6ME64J2BOJORTYLJ7EOOAVF4ROY2QLBCZWLZOHFM"
],
"depositAccount": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"name": "goanna.algo",
"owner": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"properties": {},
"state": "owned",
"timeChanged": "2022-09-21T06:19:11Z"
}
],
"D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA": [
{
"appID": 764594795,
"caAlgo": [
"D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4",
"AW3ZJNEVJKKICLA6JQ6ME64J2BOJORTYLJ7EOOAVF4ROY2QLBCZWLZOHFM"
],
"depositAccount": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"name": "goanna.algo",
"owner": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"properties": {},
"state": "owned",
"timeChanged": "2022-09-21T06:19:11Z"
}
],
"T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY": [
{
"appID": 764582734,
"caAlgo": [
"T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY",
"D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"DGOANM6JL4VNSBJW737T24V4WVQINFWELRE3OKHQQFZ2JFMVKUF52D4AY4"
],
"depositAccount": "T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY",
"name": "artgoanna.algo",
"owner": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
"properties": {},
"state": "owned",
"timeChanged": "2022-07-15T10:58:49Z"
}
]
}

Block explorers / Transaction histories

For block explorers such as algoexplorer, goalseeker, algoscan or dApps showing transaction histories for themselves, the trust requirements aren't quite as stringent. There's no overt 'trust' requirement of the name being presented.
Recommendation:
  • Use /nfd/v2/address?address=XXX[&address=yyy...][&limit=##] passing in groups of addresses (up to 20 at a time). For pages where you have multiple addresses to resolve at once, using this 'bulk' fetch will be more efficient, providing the results in one HTTP GET call.
  • For any address with matches, the result will contain an entry for the address with an array of NFD results linked to that address.
  • The limit option applies to the number of NFDs returned *per* address. If you don't care about showing multiple NFDs per address (ie: a transaction list) - just use limit=1.
  • NFD results are first sorted by most recent change.
  • The results per address are then added by matches against:
    • caAlgo[*] - These are the verified addresses and take precedence over anything else.
    • unverifiedCaAlgo[*] - These will often be accounts the owner can't directly sign for (custodial accounts for eg). By being added last, these automatically get a lower priority. Any NFD with a verified address will take precedence in the order returned. The NFD owner still has to set it, so you can trust it from name->address perspective, but since independent NFD owners can reference the same address, you can't necessarily trust the reverse as authoritative. If there's only one match though it's a reasonable use. NFDomains will over time set exchange addresses into names like coinbase.algo, binance.algo, etc. via this method (which the exchanges can claim from us if they can prove their identity).

General dApps, showing a 'name' for a connected Wallet.

The recommendation is to ONLY match against caAlgo[*]. If the user is able to connect with a particular account via pera/walletconnect, myalgo, algosigner, etc. then it's an account they can link against and will always be in the 'linked' caAlgo array.
Recommendation:
  • Use /nfd/v2/address?address=XXX&limit=1&view=thumbnail passing in the connected account.
  • If an NFD is returned, verify the address is found in caAlgo[*] and if found - use that name.
  • If you have the ability, use the image link provided in properties.userDefined.avatar, or properties.verified.avatar (special badging for 'verified' avatars is preferable but not required). The image links may often be ipfs://xxxxxx[/...] links so platforms that regularly deal with ipfs links [nft marketplaces for eg] are likely better equipped to handle this improved UX.

NFT Marketplaces / Trackers

For Algorand NFTs (ASAs), sites can use the creator address to look up the NFD associated with that creators account. Because NFDs allow numerous verifications, they provide the means for users to see the creator of an NFT as an NFD name they recognize and if not, click through to that NFD name, and see all the additional information the creator added to their NFD to prove they are the real project creator/owner.
As this becomes prevalent, users can easily know that a particular NFT is a fraud, because the image from a known collection isn't shown as being created by that well known NFD, but instead a random address (or possibly some 'lookalike' NFD name, with nothing in it matching the twitter / website / discord etc of the creator).
Recommendation:
  • For a single NFT creator address, use /nfd/v2/address?address=XXX&limit=1&view=thumbnail
  • If displaying groups, use the batch method, ie: /nfd/v2/address?address=XXX[&address=yyy...] (up to 20 at a time) and a much higher limit (as the limit specifies how many NFDs can be returned in total). If 20 addresses are passed, the current recommendation is limit=150.
  • For the NFDs returned, for each address you're trying to match against, iterate the addresses in each NFD.
    • Verify the address being looked up is found in caAlgo[*] and if found - use the first match.
  • If you have the ability, use the image link provided in properties.userDefined.avatar, or properties.verified.avatar (special badging for 'verified' avatars is preferable but not required). The image links may often be ipfs://xxxxxx[/...] links so platforms that regularly deal with ipfs links [nft marketplaces for eg] are likely better equipped to handle this improved UX. Use the avatarasaid property if you track images by ASA ID instead. The thumbnail view at a minimum is required for this property to be returned.