Discord / Telegram bots

If you have a project using Discord or Telegram for verification features (ie: possession of specific NFTs / or permission tokens) then NFDs are an excellent way to let users get access without having to do anything other than provide their NFD name !

Users can verify their Discord and Telegram accounts via NFDs. If users perform this verification, their ID will be stored as a 'verified' property in their NFD and provide a trivial way of sign on w/ proven on-chain metadata.

Verifying a Discord handle

Once a user has verified their Discord ID, their Discord 'snowflake' ID will be set in properties.verified.discord in the 'full' view of an NFD fetch.

To use NFDs for verification, a bot simply needs to use the users' snowflake ID and find all NFDs that have that ID as a verified discord handle. You will be able to know the Algorand accounts are all theirs, no webpage has to be popped, nor transactions to sign.

The bot should query the API (See NFDomains REST API Reference), the /nfd/v2/search?vproperty=discord&vvalue={snowflakeid} endpoint specifically (with the 'full' view), for the id of the user.

Search NFDs via various filters

get

Search NFDs via various filters

Query parameters

namestringOptional

name or partial match of NFD name to filter on

parentAppIDinteger · int64Optional

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

Example: 1000000

ownerstringOptional

An Algorand Account address

Example: 4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZUPattern: ^[A-Z2-7]{57}[AEIMQUY4]$

reservedForstringOptional

An Algorand Account address

Example: 4F5OA5OQC5TBHMCUDJWGKMUZAQE7BGWCKSJJSJEMJO5PURIFT5RW3VHNZUPattern: ^[A-Z2-7]{57}[AEIMQUY4]$

excludeUserReservedbooleanOptional

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

prefixstring · min: 1 · max: 32Optional

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

substringstring · min: 3 · max: 32Optional

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

vpropertystring · enumOptional

Verified property name to search on - specify value with vvalue

Example: telegramPossible values:

vvaluestringOptional

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

Example: abc123

segmentLockedbooleanOptional

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

Example: false

segmentRootbooleanOptional

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

Example: false

minPriceinteger · int64Optional

Minimum price of NFD

maxPriceinteger · int64Optional

Maximum price of NFD

minPriceUsdinteger · int64Optional

Minimum price of NFD Segment in USD (cents)

maxPriceUsdinteger · int64Optional

Maximum price of NFD Segment in USD (cents)

changedAfterstring · date-timeOptional

Fetch NFDs that changed after the specified timestamp

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

expiresBeforestring · date-timeOptional

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

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

limitinteger · int64 · min: 1 · max: 200Optional

Limit the number of results returned - max 200

Default: 50

offsetinteger · int64Optional

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

Default: 0

sortstring · enumOptional

What to sort on

Default: createdDescPossible values:

viewstring · enumOptional

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

Default: briefPossible values:

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.

application/vnd.goa.error

429

rateLimited: Too Many Requests response.

application/json

get

HTTPcURLJavaScriptPython

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

{
  "match-check": "abc123",
  "nfds": [
    {
      "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"
      ]
    }
  ],
  "total": 1
}

If NFD(s) are returned for that discord ID, then all the 'related' accounts of those NFDs can be examined.

These are:

• Owner - the owner of the account is guaranteed and can't be impersonated.

• nfdAccount - this is the account address of the NFD itself. NFDs can contain assets and this will come into play more in the future.

• caAlgo[*] - the list of accounts in the caAlgo array are the accounts the user has explicitly linked to their NFD and all are accounts the user can sign for.

All of these accounts can be searched by the bot to check for ownership of membership assets (like owning a particular NFT or other membership token). If found in any of these accounts, then the discord user (which owns that NFD) can be assigned specific roles which require proof of ownership.

Because users can either sell their NFDs, or the assets which gave them access, it is suggested that bots store the discord id and periodically reassert the above search/account checks. If the user either sells their asset or perhaps links additional accounts that grant additional rights, the bot should remove or add roles as appropriate.