NFD API
  • NFDomains API
  • Quick Start
  • Reference
    • On-Chain Reference
      • On-Chain Diagram V3+
        • On-Chain Diagram V2+
        • V1 On-Chain Diagram
      • Registry Application IDs
      • Contract methods
      • Name & Address Lookup
        • V1 Resolution example (go)
          • Example PyTeal name/ID validity check
      • NFDs owned by Address
      • Reading of NFD metadata
      • Properties
      • Contract Changelog
    • NFDomains REST API Reference
    • Integrators Guide
      • Using an NFD for sending assets to Algorand accounts
      • Using an NFD to sending to non-Algorand chains.
      • Resolving an Algorand address to an NFD name / avatar
      • Interactive NFD lookup
      • Discord / Telegram bots
      • Linking an Application to an NFD
      • Using Vaults (2.x+)
      • Expirations / MBR liquidation
    • API Changelog
    • Status Page
  • Community
Powered by GitBook
On this page

Quick Start

PreviousNFDomains APINextOn-Chain Reference

Last updated 8 months ago

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:

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.

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

https://httpie.io/cli

Get a specific NFD by name or by its application ID

get

Get a specific NFD by name or by its application ID

Path parameters
nameOrIDstring · min: 1 · max: 120Required

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

Example: silvio.algoPattern: ^(.+\.algo)|(\d+)$
Query parameters
viewstring · enumOptional

View of data to return, tiny, brief (default), or full

Default: briefPossible values:
pollbooleanOptional

Use if polling waiting for state change - causes notFound to return as 204 instead of 404. Should only be used when waiting for an NFD to transition from not-existing to being reserved for user to claim

Default: false
nocachebooleanOptional

Set to true to return a never-cached result. Use sparingly and only during certain 'NFD already exists' UX state transitions.

Default: false
Header parameters
if-none-matchstringOptional

etag

Responses
200
OK response.
application/json
204
Polling, NFD not found
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.
application/vnd.goa.error
429
rateLimited: Too Many Requests response.
application/json
get
GET /nfd/{nameOrID} HTTP/1.1
Host: api.nf.domains
Accept: */*
{
  "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"
  ]
}

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
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"
    ]
  }
}
  • VIEWS in GET requests
  • GET an NFD by NAME
  • GETGet a specific NFD by name or by its application ID
  • Get examples
  • GET NFDs for an Algorand Account Address (reverse lookup)
  • GETReverse Address lookup with results returned per address