NFT Ownership API

The NFT Ownership API can be used to retrieve information about the ownership of a specific NFT ( Non-Fungible Token ) on the supported blockchain. For instance using this we can access the owners of an NFT including their addresses and associated metadata and also we can retrieve a list of the top holders of a particular NFT.

Get NFT Owners

This query fetches the most recent owner of the NFT. It reads the latest transfer of token ID 9996 from the Transfers cube; the Receiver of that transfer is the current owner.

query MyQuery {
  EVM(dataset: combined, network: eth) {
    Transfers(
      orderBy: { descending: Block_Time }
      limit: { count: 1 }
      where: {
        Transfer: {
          Id: { eq: "9996" }
          Currency: {
            Fungible: false
            SmartContract: { is: "0x8a90cab2b38dba80c64b7734e58ee1db38b8992e" }
          }
        }
      }
    ) {
      Transfer {
        Receiver
        Amount
        Id
        Currency {
          Name
          SmartContract
        }
      }
      Block {
        Number
        Date
      }
    }
  }
}

Parameters

• network : This specifies the Ethereum network to use.
• dataset : This specifies the dataset to use. In this case, the dataset is combined.
• limit : Specifies the maximum results to return. In this query, the limit is 1.
• orderBy : Results are in descending order by Block_Time.
• where : This parameter allows you to filter the results based on specific conditions. In this case, the token ID is "9996" and the Currency is non-fungible, with the Smart Contract being 0x8a90cab2b38dba80c64b7734e58ee1db38b8992e.

Returned Data

• Transfer : Receiver is the current owner of the NFT. It also has the amount, token ID and the NFT currency (Name, SmartContract).
• Block : Includes the block number and date of the latest transfer.

Top Holders of an NFT

Let's see an example showcasing the retrieval of the top 10 holders for a particular NFT, with their balances.

query MyQuery {
  EVM(dataset: combined, network: eth) {
    Balances(
      orderBy: { descending: Balance_Amount }
      limit: { count: 10 }
      where: {
        Currency: {
          SmartContract: { is: "0x7dD4F223D9155F412790D696Fa30923489d4Ad34" }
        }
      }
    ) {
      Balance {
        Address
        Amount(selectWhere: { gt: "0" })
      }
    }
  }
}

In this query, you'll need to replace 0x7dD4F223D9155F412790D696Fa30923489d4Ad34 with the contract address of the NFT you'd like to retrieve top holders for.

Parameters

• dataset : Specifies combined dataset that includes both realtime & archive data.
• network : Specifies that the Ethereum network is being queried.
• orderBy : Orders the results based on the "Balance" field in descending order, meaning the holder with highest balance will appear first.
• limit : Limits the number of results returned to 10.
• where : It filters the query results based on the NFT smart contract address 0x7dD4F223D9155F412790D696Fa30923489d4Ad34 . Currency: {SmartContract: {is: ""}} specifies the filter for the smart contract address.

Returned Data

• Balance : Address is the holder of the NFT and Amount is how many tokens of the collection it holds.

Find NFT Creator Address

The creator of the NFT can be inferred from the sender of the first transfer. By setting, Transfers(limit: {count: 1} orderBy: {ascending: Block_Time}) we fetch the earliest (first) transfer record based on block time.

You can run the query here

query MyQuery {
  EVM(dataset: archive) {
    Transfers(
      limit: {count: 1}
      orderBy: {ascending: Block_Time}
      where: {Transfer: {Currency: {SmartContract: {is: "0xa7d8d9ef8D8Ce8992Df33D8b8CF4Aebabd5bD270"}}, Id: {eq: "78000725"}}}
    ) {
      Block {
        Time
      }
      Transfer {
        Amount
        Currency {
          Symbol
          SmartContract
          ProtocolName
          Native
          Name
          HasURI
          Fungible
          DelegatedTo
          Delegated
          Decimals
        }
        Data
        Id
        Receiver
        Success
        Type
      }
    }
  }
}

Past (churned) holders of tokens

Check past (churned) holders of an NFT collection. The Balances cube returns every address that has held the token; Amount(selectWhere: {le: "0"}) keeps only those whose balance is now zero. FirstChangeTime and LastChangeTime show when each address started and stopped holding.

{
  EVM(dataset: combined) {
    Balances(
      limit: {count: 10}
      where: {Currency: {Fungible: false, SmartContract: {is: "0x364c828ee171616a39897688a831c2499ad972ec"}}}
    ) {
      Balance {
        Address
        Amount(selectWhere: {le: "0"})
        FirstChangeTime
        LastChangeTime
      }
    }
  }
}