Interactive NFD lookup

'Looking up' an NFD interactively (debounce)

If you want to provide interactive search features for an NFD. You can use the NFD 'search' endpoint using the prefix query parameter.

The endpoint is the /nfd/v2/search endpoint. It takes many query parameters but only certain types should be specified at one time.

ie: prefix, but not owner or reservedFor.

Search NFDs via various filters

Search NFDs via various filters

get

/nfd/v2/search

Query parameters

namestring

name or partial match of NFD name to filter on

categorystring · enum[]

saleTypestring · enum[]

statestring · enum[]

parentAppIDinteger · int64

The parent NFD Application ID to find. Used for fetching segments of an NFD

Example: 1000000

lengthstring · enum[]

Length of NFD

traitsstring · enum[]

Traits of NFD

ownerstring

An Algorand Account address

Example: 4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU

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

reservedForstring

An Algorand Account address

Example: 4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU

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

excludeUserReservedboolean

Should NFDs reserved for an account (transfers for example or unclaimed winning auctions) be excluded

prefixstring · min: 1 · max: 32

The start of an NFD name, fetching multiple NFDs that have that prefix

substringstring · min: 3 · max: 32

Part of an NFD name, fetching multiple NFDs that have that substring (minimum 3 characters)

vpropertystring · enum

Verified property name to search on - specify value with vvalue

Example: telegram

Options: discord, telegram, twitter, github, email, domain, nostrpubkey

vvaluestring

Value to find in the vproperty field specified with the vproperty parameter

Example: abc123

segmentLockedboolean

Whether to explicitly filter on segments being locked or unlocked. Typically only valuable when filtering on unlocked

Example: false

segmentRootboolean

Whether to explicitly filter on NFD roots or segments. True to only see roots, False to only see segments.

Example: false

minPriceinteger · int64

Minimum price of NFD

maxPriceinteger · int64

Maximum price of NFD

minPriceUsdinteger · int64

Minimum price of NFD Segment in USD (cents)

maxPriceUsdinteger · int64

Maximum price of NFD Segment in USD (cents)

changedAfterstring · date-time

Fetch NFDs that changed after the specified timestamp

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

expiresBeforestring · date-time

Return only NFDs with an expiration time at or before the specified timestamp

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

limitinteger · int64 · min: 1 · max: 200 · default: 50

Limit the number of results returned - max 200

offsetinteger · int64

Starting document in large list. Fetch 1-100 [limit 100], pass offset 100 to fetch 100-200

sortstring · enum · default: createdDesc

What to sort on

Options: createdDesc, timeChangedDesc, soldDesc, priceAsc, priceDesc, highestSaleDesc, saleTypeAsc, nameAsc, expiresAsc, expiresDesc

viewstring · enum · default: brief

View of data to return, tiny (name, owner, caAlgo, unverifiedCaAlgo only), brief (default), or full

Options: tiny, thumbnail, brief, full

Header parameters

if-none-matchstring

etag

Responses

application/json

application/vnd.goa.error

application/vnd.goa.error

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.nf.domains/nfd/v2/search'

200

304

400

404

429

200

{
  "match-check": "abc123",
  "total": 1,
  "nfds": [
    {
      "appID": 1000000,
      "asaID": 1,
      "avatarOutdated": false,
      "cache-control": "abc123",
      "category": "abc123",
      "currentAsOfBlock": 1,
      "depositAccount": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
      "etag": "abc123",
      "expired": false,
      "match-check": "abc123",
      "name": "abc123",
      "nfdAccount": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
      "owner": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
      "parentAppID": 1000000,
      "reservedFor": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
      "saleType": "abc123",
      "sellAmount": 1,
      "seller": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
      "sigNameAddress": "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU",
      "state": "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",
      "caAlgo": [
        "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU"
      ],
      "metaTags": [
        "abc123"
      ],
      "tags": [
        "abc123"
      ],
      "unverifiedCaAlgo": [
        "4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZU"
      ],
      "unverifiedCa": {
        "btc": [
          "12KKDt4Mj7N5UAkQMN7LtPZMayenXHa8KL"
        ]
      },
      "properties": {
        "internal": {
          "abc123": "abc123"
        },
        "userDefined": {
          "ca:b": "abc123"
        },
        "verified": {
          "caAlgo": "abc123"
        }
      }
    }
  ]
}

OK response.

Example

Get first 4 matching names by prefix (forced 'thumbnail' view)

http https://api.nf.domains/nfd/v2/search?prefix=patric&view=thumbnail&limit=4

{
    "nfds": [
        {
            "appID": 1184583458,
            "depositAccount": "MQ2QJHZSZ6A7ZXPFE2EPIWLYUMRRDO3DQBEO6NIQ2B5A5OJ4VMWOOI2AX4",
            "name": "patrick.voi.algo",
            "owner": "MQ2QJHZSZ6A7ZXPFE2EPIWLYUMRRDO3DQBEO6NIQ2B5A5OJ4VMWOOI2AX4",
            "parentAppID": 984682143,
            "properties": {},
            "state": "owned"
        },
        {
            "appID": 1016975892,
            "depositAccount": "SAC732VSDG3J7ZVDOIV7I5Y3REVCYB2EPMNU6PRLJY67L37YOARYSD2PDM",
            "name": "patricia.eth.algo",
            "owner": "SAC732VSDG3J7ZVDOIV7I5Y3REVCYB2EPMNU6PRLJY67L37YOARYSD2PDM",
            "parentAppID": 1016578024,
            "properties": {},
            "state": "owned"
        },
        {
            "appID": 1016975648,
            "depositAccount": "SAC732VSDG3J7ZVDOIV7I5Y3REVCYB2EPMNU6PRLJY67L37YOARYSD2PDM",
            "name": "patricia.btc.algo",
            "owner": "SAC732VSDG3J7ZVDOIV7I5Y3REVCYB2EPMNU6PRLJY67L37YOARYSD2PDM",
            "parentAppID": 1016575127,
            "properties": {},
            "state": "owned"
        },
        {
            "appID": 1016602998,
            "depositAccount": "MQ2QJHZSZ6A7ZXPFE2EPIWLYUMRRDO3DQBEO6NIQ2B5A5OJ4VMWOOI2AX4",
            "name": "patrick.btc.algo",
            "owner": "MQ2QJHZSZ6A7ZXPFE2EPIWLYUMRRDO3DQBEO6NIQ2B5A5OJ4VMWOOI2AX4",
            "parentAppID": 1016575127,
            "properties": {},
            "state": "owned"
        }
    ],
    "total": 10
}

The thumbnail view will return verified and userDefined avatars for names. This way, the UI can show avatars with choices as well, as seen here in this NFDomains search UI example:

Note the verified.avatarasaid property in this example (same exists for banner, bannerasaid when fetching with other views). For integrations that manage their own ASA caching, this may make it easier to reference already cached versions of the NFT image if the ASA id is used instead of IPFS CID references.