Resolving an Algorand address to an NFD name / avatar

The API used for reverse address lookup is quite simple.

1. For any given address, return the preferred verified linked address associated with that account.

2. If there are no verified addresses, there is exactly 1 unverified address and allowUnverified=true is passed to the lookup endpoint, then return that. Integrators ideally should have some indicator to show the address is unverified !

   If more than 1 unverified match is found and only unverified, return nothing - it will be treated as if nothing was found.

The /nfd/lookup endpoint returns a single NFD match PER provided Address. The 'tiny' view is used by default - with the information returned per match. Use other views like thumbnail to also include basic avatar info. See VIEWS in GET requestsfor information on the view parameter.

If nothing is matched, a 404 (Not Found) is returned. This is a valid return status, and also helps performance due to CDN negative caching.

Up to 20 addresses can be batched per GET request.

Results are cached by the CDN for up to 2 minutes so changes to linked NFDs may appear delayed.

In NFD V1: If multiple NFDs are linked to the same address, the 'most recently changed' NFD is what's used. In NFD v2: The 'primary NFD' chosen by the user in the manage account dropdown is what is used for the specified address.

REST API Call

Reverse Address lookup with results returned per address

get

Get the primary NFD for an address. Must be verified address, or if allowUnverified is set, it may match against an unverified address

Query parameters

addressstring[] · min: 1 · max: 20Required

one or more addresses (algo or otherwise) to look up, maximum of 20 can be defined. Specify the same query parameter multiple times for each address, ie: address=xxx&address=yyy&address=zzz

Example: ["abc123","abc123"]

viewstring · enumOptional

View of data to return, tiny (name, owner, caAlgo, unverifiedCaAlgo only [default]), thumbnail (tiny + avatar), brief, or full

Default: tinyPossible values:

allowUnverifiedbooleanOptional

Whether to allow unverified addresses to match (and only if its only match). Defaults to false

Default: falseExample: false

Header parameters

if-none-matchstringOptional

etag

Responses

200

OK response.

application/json

304

ETag not changed

400

invalidAddress: invalidAddress is returned for an Algorand address that doesn't appear to be valid

application/vnd.goa.error

404

notFound: Not Found response.

429

rateLimited: Too Many Requests response.

application/json

get

HTTPcURLJavaScriptPython

GET /nfd/lookup HTTP/1.1
Host: api.nf.domains
Accept: */*

{
  "abc123": {
    "appID": 1000000,
    "asaID": 1,
    "avatarOutdated": false,
    "caAlgo": [
      "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU"
    ],
    "cache-control": "abc123",
    "category": "abc123",
    "currentAsOfBlock": 1,
    "depositAccount": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
    "etag": "abc123",
    "expired": false,
    "match-check": "abc123",
    "metaTags": [
      "abc123"
    ],
    "name": "abc123",
    "nfdAccount": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
    "owner": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
    "parentAppID": 1000000,
    "properties": {
      "internal": {
        "abc123": "abc123"
      },
      "userDefined": {
        "ca:b": "abc123"
      },
      "verified": {
        "caAlgo": "abc123"
      }
    },
    "reservedFor": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
    "saleType": "abc123",
    "sellAmount": 1,
    "seller": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
    "sigNameAddress": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
    "state": "abc123",
    "tags": [
      "abc123"
    ],
    "timeChanged": "1970-01-01T00:00:01Z",
    "timeCreated": "1970-01-01T00:00:01Z",
    "timeExpires": "1970-01-01T00:00:01Z",
    "timePurchased": "1970-01-01T00:00:01Z",
    "unverifiedCa": {
      "btc": [
        "12KKDt4Mj7N5UAkQMN7LtPZMayenXHa8KL"
      ]
    },
    "unverifiedCaAlgo": [
      "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU"
    ]
  }
}

Example request: https://api.nf.domains/nfd/lookup?address=2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4&address=D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA&address=T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY

Example response

{
    "2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4": {
        "appID": 764594795,
        "caAlgo": [
            "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
            "2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4",
            "AW3ZJNEVJKKICLA6JQ6ME64J2BOJORTYLJ7EOOAVF4ROY2QLBCZWLZOHFM"
        ],
        "depositAccount": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
        "name": "goanna.algo",
        "owner": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
        "properties": {},
        "state": "owned",
        "timeChanged": "2023-01-18T00:00:30Z"
    },
    "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA": {
        "appID": 764594795,
        "caAlgo": [
            "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
            "2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4",
            "AW3ZJNEVJKKICLA6JQ6ME64J2BOJORTYLJ7EOOAVF4ROY2QLBCZWLZOHFM"
        ],
        "depositAccount": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
        "name": "goanna.algo",
        "owner": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
        "properties": {},
        "state": "owned",
        "timeChanged": "2023-01-18T00:00:30Z"
    },
    "T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY": {
        "appID": 764582734,
        "caAlgo": [
            "T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY",
            "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
            "DGOANM6JL4VNSBJW737T24V4WVQINFWELRE3OKHQQFZ2JFMVKUF52D4AY4",
            "JHZUJ66WV2IN2MN7L2L6OSJ6IE3ITOTUQNKVJELYZY4IPEECPVH2KOWSRE"
        ],
        "depositAccount": "T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY",
        "name": "artgoanna.algo",
        "owner": "D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA",
        "properties": {},
        "state": "owned",
        "timeChanged": "2022-11-26T23:17:11Z"
    }
}

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. The ASA ID is also a property for verified avatars if you have your own caching by ID.

Block explorers / Transaction histories

For block explorers such as algoexplorer, goalseeker, algoscan or dApps showing transaction histories for themselves, simply use the lookup endpoint batching up to 20 addresses per request. If your site can easily show avatars, then use the thumbnail view to get the asaid and root url of the ASA assigned as the NFDs avatar.

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

If an NFD is returned for the connected account, show the NFD name instead of or in addition to the account.

Here's a portion of the screenshot for the NFDomains wallet dropdown demonstrating this.

NFT Marketplaces / Trackers

For Algorand NFTs (ASAs), sites should 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).