Quick Start

For local testing, we highly recommend something like HTTPIE. It's much nicer to use than CURL, provides clean json body creation and automatically displays json responses in a clean format.

See: https://httpie.io/cli

The examples will reference using httpie via the 'http' command.

VIEWS in GET requests

First, a quick note about the 'view' property in many of the APIs. For efficiency, many API requests have a default 'view' that returns a focused amount of data more appropriate for certain requestors. This view is what will be returned if no view parameter is explicitly set. Typically this is the 'brief' view. Some queries return a special 'thumbnail' view that is meant to to be very simple - often used for interactive 'search by name' types of queries. Thumbnail is basically 'tiny' + avatar links and is only available via some endpoints.

Example views differences for an NFD (nfdomains.algo in this example):

{
    "caAlgo": [
        "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I"
    ],
    "depositAccount": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
    "name": "nfdomains.algo",
    "owner": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
    "properties": {},
    "unverifiedCaAlgo": [
        "ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ"
    ]
}

 {
        "name": "nfdomains.algo",
        "depositAccount": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
        "properties": {
            "userDefined": {
                "avatar": "https://images.nf.domains/avatar/9f1940b9-2cf5-43cb-96e5-f3b36385fc90"
            }
        },
        "unverifiedCaAlgo": [
            "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
            "ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ",
            "OMXLQTI5ZSMWTCIZA3O3YBW74BTCOI67SZTOEDHK3ZEDZ34Z3DEOQD4PW4"
        ]
    }

{
    "appID": 763844423,
    "asaID": 763844429,
    "caAlgo": [
        "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I"
    ],
    "category": "common",
    "depositAccount": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
    "metaTags": [
        "9_letters",
        "pristine"
    ],
    "name": "nfdomains.algo",
    "nfdAccount": "FQDCZYHSK6CHLESEN76AGMSZ4JMT2H5BKWSV6NN2YAKDF22NUAJAOZ4ZIY",
    "owner": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
    "properties": {
        "userDefined": {
            "avatar": "https://images.nf.domains/avatar/9f1940b9-2cf5-43cb-96e5-f3b36385fc90"
        }
    },
    "saleType": "buyItNow",
    "state": "owned",
    "unverifiedCaAlgo": [
        "ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ"
    ]
}

{
    "appID": 763844423,
    "asaID": 763844429,
    "caAlgo": [
        "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I"
    ],
    "category": "common",
    "currentAsOfBlock": 22754901,
    "depositAccount": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
    "metaTags": [
        "9_letters",
        "pristine"
    ],
    "name": "nfdomains.algo",
    "nfdAccount": "FQDCZYHSK6CHLESEN76AGMSZ4JMT2H5BKWSV6NN2YAKDF22NUAJAOZ4ZIY",
    "owner": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
    "properties": {
        "internal": {
            "asaid": "763844429",
            "category": "common",
            "commission1": "50",
            "commission1Agent": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
            "contractLocked": "0",
            "highestSoldAmt": "1000000",
            "name": "nfdomains.algo",
            "owner": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
            "saleType": "buyItNow",
            "seller": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
            "timeChanged": "1660161129",
            "timeCreated": "1654229863",
            "timePurchased": "1654233465",
            "ver": "1.08"
        },
        "userDefined": {
            "avatar": "https://images.nf.domains/avatar/9f1940b9-2cf5-43cb-96e5-f3b36385fc90",
            "banner": "https://images.nf.domains/banner/da11c55f-8b85-416d-9361-612082d26f03",
            "bio": "Discord: https://discord.gg/7XcuMTfeZP",
            "caalgo": "ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ",
            "github": "https://github.com/TxnLab",
            "name": "NFDomains",
            "website": "https://app.nf.domains"
        },
        "verified": {
            "caAlgo": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
            "twitter": "@nfdomains"
        }
    },
    "saleType": "buyItNow",
    "seller": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
    "state": "owned",
    "timeChanged": "2022-08-10T19:52:09Z",
    "timeCreated": "2022-06-03T04:17:43Z",
    "timePurchased": "2022-06-03T05:17:45Z",
    "unverifiedCaAlgo": [
        "ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ"
    ]
}

GET an NFD by NAME

To fetch an NFD by explicit name, make an HTTP GET call to the /nfd/{name} endpoint.

No parameters are required. Fetching a name will return the 'brief' view by default which is sufficient for most fetches a wallet would use for example.

Get a specific NFD by name or by its application ID

GEThttps://api.nf.domains/nfd/{nameOrID}

Path parameters

nameOrID*string

Name of a NFD (alphanumeric only or emojis/alphanumeric), or an NFD Application ID

Example: "silvio.algo"

Pattern: ^(.+\.algo)|(\d+)$

Query parameters

Header parameters

Response

OK response.

Headers

Body

appIDinteger (int64)

NFD Application ID

Example: 1000000

asaIDinteger (int64)

NFD ASA ID

Example: 1

avatarOutdatedboolean

Whether the verified Avatar set in this NFD is newer (arc19) then is set into the NFD. This will only be present on direct NFD fetch and if true

Example: false

caAlgoarray of string

Verified Algorand addresses for this NFD

categoryenum

Example: "premium"

curatedpremiumcommon

currentAsOfBlockinteger (int64)

Round this data was last fetched from

Example: 1

depositAccountstring

account wallets should send funds to - precedence is: caAlgo[0], unverifiedCaAlgo[0], owner

Example: "333333333333333333333333333333333333333333333333333333333A"

Pattern: ^[A-Z2-7]{57}[AEIMQUY4]$

expiredboolean

Example: false

match-checkstring

Not returned, used in tagging for response to indicate if-none-match etag matched

Example: "abc123"

metaTagsarray of string

Tags set by the system for tracking/analytics

name*string

Example: "abc123"

nfdAccountstring

Example: "333333333333333333333333333333333333333333333333333333333A"

Pattern: ^[A-Z2-7]{57}[AEIMQUY4]$

ownerstring

Owner of NFD

Example: "333333333333333333333333333333333333333333333333333333333A"

Pattern: ^[A-Z2-7]{57}[AEIMQUY4]$

parentAppIDinteger (int64)

NFD Application ID of Parent if this is a segment

Example: 1000000

propertiesNFDProperties (object)

NFDProperties contains the expanded metadata stored within an NFD contracts' global-state

reservedForstring

Reserved owner of NFD

Example: "333333333333333333333333333333333333333333333333333333333A"

Pattern: ^[A-Z2-7]{57}[AEIMQUY4]$

saleTypeenum

Example: "buyItNow"

auctionbuyItNow

sellAmountinteger (int64)

amount NFD is being sold for (microAlgos)

Example: 1

sellerstring

RecipientUid of NFD sales

Example: "333333333333333333333333333333333333333333333333333333333A"

Pattern: ^[A-Z2-7]{57}[AEIMQUY4]$

sigNameAddressstring

Example: "333333333333333333333333333333333333333333333333333333333A"

Pattern: ^[A-Z2-7]{57}[AEIMQUY4]$

stateenum

Example: "minting"

availablemintingreservedforSaleownedexpired

tagsarray of string

Tags assigned to this NFD

timeChangedstring (date-time)

Example: "1970-01-01T00:00:01Z"

timeCreatedstring (date-time)

Example: "1970-01-01T00:00:01Z"

timeExpiresstring (date-time)

Example: "1970-01-01T00:00:01Z"

timePurchasedstring (date-time)

Example: "1970-01-01T00:00:01Z"

unverifiedCaobject

Unverified (non-algo) Crypto addresses for this NFD

unverifiedCaAlgoarray of string

Unverified Algorand addresses for this NFD

Request

const response = await fetch('https://api.nf.domains/nfd/{nameOrID}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "appID": 1000000,
  "asaID": 1,
  "avatarOutdated": false,
  "caAlgo": [
    "333333333333333333333333333333333333333333333333333333333A"
  ],
  "category": "premium",
  "currentAsOfBlock": 1,
  "depositAccount": "333333333333333333333333333333333333333333333333333333333A",
  "expired": false,
  "match-check": "abc123",
  "metaTags": [
    "abc123"
  ],
  "name": "abc123",
  "nfdAccount": "333333333333333333333333333333333333333333333333333333333A",
  "owner": "333333333333333333333333333333333333333333333333333333333A",
  "parentAppID": 1000000,
  "properties": {
    "internal": {
      "abc123": "abc123"
    },
    "userDefined": {
      "ca:b": "abc123"
    },
    "verified": {
      "caAlgo": "abc123"
    }
  },
  "reservedFor": "333333333333333333333333333333333333333333333333333333333A",
  "saleType": "buyItNow",
  "sellAmount": 1,
  "seller": "333333333333333333333333333333333333333333333333333333333A",
  "sigNameAddress": "333333333333333333333333333333333333333333333333333333333A",
  "state": "minting",
  "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": [
    "333333333333333333333333333333333333333333333333333333333A"
  ]
}

Please don't use the 'poll' or 'nocache' query parameters, except for specific UI/UX transitions as part of a minting process. Ask in the dev channels for details.

Get examples

Get name using defaults (brief view)

http https://api.nf.domains/nfd/nfdomains.algo
{
    "appID": 763844423,
    "category": "common",
    "metaTags": [
        "9_letters"
    ],
    "name": "nfdomains.algo",
    "depositAccount": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
    "nfdAccount": "FQDCZYHSK6CHLESEN76AGMSZ4JMT2H5BKWSV6NN2YAKDF22NUAJAOZ4ZIY",
    "owner": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
    "properties": {
        "userDefined": {
            "avatar": "https://images.nf.domains/avatar/9f1940b9-2cf5-43cb-96e5-f3b36385fc90"
        }
    },
    "saleType": "buyItNow",
    "state": "owned",
    "unverifiedCaAlgo": [
        "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
        "ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ",
        "OMXLQTI5ZSMWTCIZA3O3YBW74BTCOI67SZTOEDHK3ZEDZ34Z3DEOQD4PW4"
    ]
}

Get name using "full" view

http 'https://api.nf.domains/nfd/nfdomains.algo?view=full'
{
    "appID": 763844423,
    "asaID": 763844429,
    "category": "common",
    "currentAsOfBlock": 21686682,
    "metaTags": [
        "9_letters"
    ],
    "name": "nfdomains.algo",
    "depositAccount": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
    "nfdAccount": "FQDCZYHSK6CHLESEN76AGMSZ4JMT2H5BKWSV6NN2YAKDF22NUAJAOZ4ZIY",
    "owner": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
    "properties": {
        "internal": {
            "asaid": "763844429",
            "category": "common",
            "commission1": "50",
            "commission1Agent": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
            "contractLocked": "0",
            "highestSoldAmt": "1000000",
            "name": "nfdomains.algo",
            "owner": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
            "saleType": "buyItNow",
            "seller": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
            "timeChanged": "1655530642",
            "timeCreated": "1654229863",
            "timePurchased": "1654233465",
            "ver": "1.08"
        },
        "userDefined": {
            "avatar": "https://images.nf.domains/avatar/9f1940b9-2cf5-43cb-96e5-f3b36385fc90",
            "banner": "https://images.nf.domains/banner/da11c55f-8b85-416d-9361-612082d26f03",
            "bio": "Discord: https://discord.gg/7XcuMTfeZP",
            "caalgo": "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I,ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ,OMXLQTI5ZSMWTCIZA3O3YBW74BTCOI67SZTOEDHK3ZEDZ34Z3DEOQD4PW4",
            "github": "https://github.com/TxnLab",
            "website": "https://app.nf.domains"
        },
        "verified": {
            "twitter": "@nfdomains"
        }
    },
    "saleType": "buyItNow",
    "seller": "NRLA7VZ2YV6WOS2LBS3UK25DB463XRSNG63BYNQI6CSGGROFWVQ2EKBQSI",
    "state": "owned",
    "timeChanged": "2022-06-18T05:37:22Z",
    "timeCreated": "2022-06-03T04:17:43Z",
    "timePurchased": "2022-06-03T05:17:45Z",
    "unverifiedCaAlgo": [
        "RSV2YCHXA7MWGFTX3WYI7TVGAS5W5XH5M7ZQVXPPRQ7DNTNW36OW2TRR6I",
        "ABHE544MXL2CWMIZONAIUBNVELWYMKYKWBDNRLOEFQJN3LNF2ZWSMDEKBQ",
        "OMXLQTI5ZSMWTCIZA3O3YBW74BTCOI67SZTOEDHK3ZEDZ34Z3DEOQD4PW4"
    ]
}

GET NFDs for an Algorand Account Address (reverse lookup)

To fetch NFDs that an an address points to, make an HTTP GET call to the /nfd/lookup?address=xxxxx[&address=yyyyy] endpoint.

Multiple addresses can be passed to the endpoint, with each address specified as an additional address=xxx query 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.

For more detailed information on this endpoint, please see some of the details described in Resolving an Algorand address to an NFD name / avatar

Reverse Address lookup with results returned per address

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

GEThttps://api.nf.domains/nfd/lookup

Query parameters

Header parameters

Response

OK response.

Headers

Body

Other propertiesNfdRecordinaddress (object)

NFD contains all known information about an NFD record

Request

const response = await fetch('https://api.nf.domains/nfd/lookup?address=abc123', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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"
    ]
  }
}

PreviousNFDomains API NextOn-Chain Reference

Last updated 3 months ago