API Changelog

The features or responses in the API may change regularly. This will not be exhaustive or include every change, but as there are notable changes made they will be listed here.

Versions referenced are part of /info/version endpoint.

2024/10/11

• added expiresDesc sort option to v2/search

2024/10/08

• Added 'expiresBefore' query parameter to v2/search endpoint. Allows returning filtered list based on NFDs expiring at or before the specified timestamp.

2024/09/25

• Removed rejectNft option from purchase endpoint. The NFT is always rejected now starting w/ V3.

2024/09/24

• Removed reLockAt argument to vault opt-in lock. Supported in 2.x but nothing used it and it wasn't exposed in the UI, so removed in 3.x and API.

2024/09

• A new state value of 'expired' will be set for NFDs which have expired. They should be treated like they are for sale. The depositAccount property will not be returned for NFDs in this state. Wallets should not send to an NFD in this state (the missing depositAccount property is the clear sign - just like when for sale)

• NFD v3 contains changes to many endpoints - although mostly those used by the app only as part of minting or pricing.

• The /nfd/vault/sendFrom/{name} and /nfd/vault/sendTo/{name} endpoints have a new amountStr property so that JS clients can pass integers larger than the Number type allows (bigint). Passing the amounts as a string instead of integer is only way to support broken implementations like this.

• Minting an NFD is now through the the /nfd/mint endpoint and /nfd/kickoff has been removed. Because of AVM limitations the linkOnMint option can't be used yet.

2024/01/03

• The brief view for NFDs will now return the internal ver(sion) and vaultOptInLocked state to help determine vault availability in NFD prior to making vault contract calls.

2023/06

• Added new /nfd/lookup endpoint for reverse lookups. For almost all reverse-lookup scenarios this is what should be used. The address endpoints (original and v2/) will have more aggressive rate-limits imposed to discourage their use.

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

200304400404429

OK response.

Headers

Body

application/json

Other propertiesNfdRecordinaddress (object)

NFD contains all known information about an NFD record

Request

JavaScriptCurlPython

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

Response

200429

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

2023/04 - 2023/09

2.x(+) Contract updates

• All contracts older than 2.x will be forced to be upgraded to 2.x to be edited through the API/UI. This is to provide a clean migration path from 1.x to 2.x contract storage. Upgrading the contract migrates registration of the name and linked addresses to box storage in the registry from LSIGs as well as all user-defined/verified fields from state to boxes. The system will still handle reading V1 and V2 NFDs.

• All user-defined and verified properties are now stored using Boxes in the NFD contract. The transactions returned from the API will automatically include payments to the registry contract account or the NFD contract account (its vault) to pay fo the box storage. Box storage is basically 'pay as you go' per box and per byte.

New API endpoints for Vault operations

• Added /nfd/vault/lock/{name} for locking or unlocking the vault of an NFD. The NFD vault defaults to locked.

• Added /nfd/vault/sendTo/{name} for sending ALGO or an ASA to an NFD vault, sending .1 for the MBR if necessary, having the vault opt-in, and transfer the asset. If the vault is already opted-in, then it will just be a simple payment/asset transfer. Sending to your own vault is always allowed. Other users can only send to a vault if it is unlocked by the owner.

• Added /nfd/vault/sendFrom/{name} for sending ALGO or an ASA from an NFDs vault to another account, or NFD vault. Only the NFD owner can send from the vault.

2023/02/07

• Added /nfd/consensus/metrics endpoint with ranked list of proposers up to 74% threshold for basic nakamoto coefficient (by proposing account)

2023/02/03

• Add optional requireNFD parameter to /nfd/consensus/leaders to specify whether to require the proposing account to be linked to an NFD.

2023/01/25

• Added a consensus leaderboard endpoint at /nfd/consensus/leaders utilizing data from new internal consensus tracking service.

2023/01/17

• Added segment totals to /nfd/totals endpoint return.

2023/01/16

• As part of Segments roll-out, all the features updated/added that were previously only on betanet/testnet will be live (All of the changes since #2022-09 changes)

• Modified GET /nfd/{name} which is now /nfd/{nameOrID}. You can fetch an NFD now by its full name, or by its application ID.

• Modified /nfd/purchase/{name} API to have new parameter, rejectNFT. Setting this 'opts out' of receiving the NFD's NFT upon claiming. This is mainly for large projects, who may mint a significant number of segments in a central account and not wanting the extra MBR requirements on the owning account.

2023/01/13

• Added new participation return to /nfd/badges endpoint if an NFD's related account is participating in consensus (an 'online' account). "online":"true" is included in the participation object if so.

2022/12/xx

• Added /nfd/v2/donations/list endpoint which simply returns list of NFDs (brief view) that are considered donation targets.

• Added /nfd/v2/donations/leaders/{name} endpoint which accepts an NFD name as donation target to get donors for instead of a single address.

• Added segmentLocked parameter as additional available filter on the /nfd/v2/search endpoint. Allows getting only locked (not particularly useful), or unlocked NFDs.

• Added segmentRoot parameter as additional available filter on the /nfd/v2/search endpoint. Allows getting just roots, or just segments.

• Added /nfd/segment/leaders endpoint which returns the top 50 root NFDs, ordered by number of minted segments.

2022/11/04

• Added /nfd/v2/address - This is a new version of the /nfd/address reverse-lookup endpoint, but which returns the results as a map. Each address [if found] is the key, with an array of any NFDs referenced by that address. The limit parameter is no longer a total limit, but a limit PER address.

• Deprecated /nfd/address - This endpoint will remain for a significant period of time but its awkwardness encourages its deprecation.

• Example /nfd/v2/address use and results:

https://api.nf.domains/nfd/v2/address?address=D5J7H7PIYKLY2U6A5OFUAC7GQHTHSXXNX65DSD3CJYPBV2MVK6NTNW44CA&address=2MQZFP7LNZNQDMJO5F3SZDFVEEHOFH6G3NXSLASIJIB7OLDPVLSCX67QZ4&address=T3UL3YBJZILL2WGJ5HG3EAVAR6H4ETVZ4RKFGDFBWAFZSG7PEXSQRN2NGY&limit=1

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

2022/11/04

• Added /nfd/segment/price/{name}?buyer={address} - This endpoint will provide a price breakdown (if possible) of minting the specified named segment.

• Updated /nfd/suggest/{name} to support optional buyer={address} parameter. Will return an error if the specified buyer can't mint any of the suggested names, such as a segment.

2022/10/23

• Added (Changed)** ** a parameter in the /nfd/analytics endpoint

  • Added includeOwner parameter. Specifies whether to add a currentOwner property to each event with the current owner of the NFD referenced by that event. Should only be used rarely. Added to help a UI feature.

  • This was originally includeState - but changed to includeOwner.

2022/09/28

• Added new top-level property in API returns called unverifiedCa. (unverified Crypto Address)

  • Returns as an object with members for userDefined.ca.XXX properties. ie: u.ca.btc on-chain is exposed in the api as unverifiedCa.btc: ["xxxx"]

  • The addresses will be returned as an array for future-proofing. Initially there will be only one address the user can enter for other chains, but editing of lists could be added later.

  • Example 'brief' view return for patrick.algo w/ dummy BTC / ETH values

{
    "appID": 763843612,
    "asaID": 763843618,
    "caAlgo": [
        "MQ2QJHZSZ6A7ZXPFE2EPIWLYUMRRDO3DQBEO6NIQ2B5A5OJ4VMWOOI2AX4"
    ],
    "category": "premium",
    "depositAccount": "MQ2QJHZSZ6A7ZXPFE2EPIWLYUMRRDO3DQBEO6NIQ2B5A5OJ4VMWOOI2AX4",
    "metaTags": [
        "7_letters"
    ],
    "name": "patrick.algo",
    "nfdAccount": "LTWWWD52TRSUIM2RIPNFYEX4YL2GM2YQBRTYEGT54UPJM4RATVW7UWSWSY",
    "owner": "MQ2QJHZSZ6A7ZXPFE2EPIWLYUMRRDO3DQBEO6NIQ2B5A5OJ4VMWOOI2AX4",
    "properties": {
        "verified": {
            "avatar": "ipfs://bafkreifu5fbvnxfptgj6nisk4m2lc557dgs7soumr3nxxirrrv7zp4qivm",
            "avatarasaid": "847757707"
        }
    },
    "saleType": "buyItNow",
    "state": "owned",
    "unverifiedCa": {
        "btc": ["xxxxxxxxxxxxxxxx"],
        "eth": ["xxxxxxxxxxxxxxxx"]
    }
}

2022/09

• "search" endpoint at /nfd?[query params] is now deprecated. It will continue to be supported for some time.

  • The v1 endpoint will no longer allow combining owner and reservedFor for a dual-search - and it will also cap results to 240 [total]. Previously it would return ALL NFDs owned by X for eg.

• Added a new 'v2' search endpoint at /nfd/v2/search?[query params]

  • Added offset parameter. The v2 endpoint supports offset / limit params like some of the other endpoints for paging through the results, but will also return a 'total' value like the analytics endpoint.

  • removed requireAddresses param.

  • added optional state parameter - can specify: forSale, owned, or reserved to filter results.

2022/09/06

• "c842b5c:main [2022-09-06T18:18:39Z]

• Removed the 'state' parameter from /nfd/analytics (wasn't ever used)

• Updated the options in the 'state' parameter in /nfd/browse to include reserved

• Reserved NFDs will no longer be filtered from results returned by the browse endpoint. This was originally done to prevent confusion in the marketplace, showing names users couldn't do anything with if it wasn't reserved for them. Additional data is always shown for all names now so it makes sense to show them again. At least one integrator was also using this endpoint for tracking changes over time and reserved nfds being excluded was creating gaps in their caches.

• A new invalidCA error code can be returned from the PATCH/PUT (updatePartial / updateAll) calls to update an NFD. This is returned if user-defined caalgo addresses that have been specified aren't valid Algorand addresses.

2022/09/01

• c52a8cd:main [2022-09-01T03:56:08Z]

• The caAlgo property could have had an undefined ordering if more than 3 linked addresses were defined.

• The asaID property will now be returned in all 'brief' view returns of NFDs.

2022/08/25

Changed allowed pattern for userDefined fields

• ca.[a-z]{1,5} is now allowed as a field name pattern for user defined fields. This will be used for specifying other token deposit addresses. ie: ca.btc, ca.eth...

2022/08/12

• "appVersion": "c54f842:main [2022-08-12T17:49:39Z]"

Added POST /nfd/escrowOffer/{name} endpoint

• Make escrowed bid for a new 'floor' price of an ongoing auction. Higher bidder refunds you, if price drops to your escrow, you win auction with it being reserved for you.

• See API spec for body requirements. Effectively same as normal purchase call.

Enhanced /nfd/activity endpoint

• Added timeAsc as a new sort option.

NFDAnalyticEvent has new event type

• Added event type: escrowedOffer

Enhanced /nfd/auction endpoint

• newEndTime, and newFloorPrice will be added to auction return data if an escrowed floor has been set.

2022/07/27

Enhanced '/nfd/browse' endpoint

• "appVersion": "bd23fab:main [2022-07-27T21:39:06Z]"

• Added changedAfter as new query param on browse endpoint allowing filtering on NFDs that changed after that timestamp.

• Added timeChangedDesc as a new sort option.

Added avatarasaid / avatarOutdated properties to NFD returns

• "appVersion": "1bc1198:main [2022-07-27T19:58:47Z]"

• "appVersion": "2340c69:main [2022-07-28T01:30:07Z]" (small fix for prefix endpoiint not including the avatarasaid)

• NFD returns will now contain properties.verified.avatarasaid in thumbnail, brief, and full views.

  • The avatarasaid property (on-chain as well) contains the ASA ID of the NFT the owner set as their avatar. Some integrators may cache based on asset id, so this is an easier way for them to display thumbnails than the IPFS link in the avatar property.

• GET calls on an NFD (/nfd/silvio.algo) in brief or full view will now return an optional property titled 'avatarOutdated'. If true, this means the PFP set into this NFD has a newer image on-chain that the owner can switch to. Currently this means their PFP Avatar is an ARC19 NFT and an update has bee made since they set its image as their avatar.

2022/07/26 - excludeNFDAsSeller param on analytics

• Added query parameter: excludeNFDAsSeller (bool) to the /nfd/analytics endpoint:

  • "Whether to exclude events where NFDomains is the seller. If set to true, and filtering on 'sold' event for eg, returned items will will be secondary sales only.