Skip to main content

Getting NFTs for an Address

Learn how to retrieve NFT data for a specific wallet address#

This guide will cover how to retrieve NFT data for an ownerAddress and then dive deeper into how to get details for specific NFTs. The following are starter examples, but there are many different possibilities with the API.

note

GraphiQL Playground: https://api.zora.co/graphql

Demo Address: jacob.eth or 0x17cd072cBd45031EFc21Da538c783E0ed3b25DCc

*The API is ENS compatible, meaning that ownerAddress can be an ENS name.

NFT Balance#

Let's get started by looking at jacob.eth as our example address. We can use the tokens query and set the ownerAddress.

query JacobsNFTs {  tokens(networks: [{network: ETHEREUM, chain: MAINNET}],         pagination: {limit: 3},         where: {ownerAddresses: "jacob.eth"}) {    nodes {      token {        collectionAddress        tokenId        name        owner        image {          url        }        metadata      }    }  }}

In this example, we have set the limit to 3 NFTs, but the max size of the response can be up to 500. However, recommend using the pagination parameters to meter the size of your responses.

Note, that it is possible to grab all the events with each NFT by specifying it in the query.

Total Sales Volume#

Now we can look at the total sales volume for this specific address by using aggregateStat. We can see that it has sold 42 NFTs for a total of 90 ETH.

query TotalAddressSales {  aggregateStat {    salesVolume(where: {ownerAddresses: "jacob.eth"}) {      totalCount      chainTokenPrice    }  }}

Largest Purchase#

Lastly, we can get the largest on-chain ETH purchase this address has made using the sales query and sorting by descending NATIVE_PRICE. Native price is sales price in the currency that was used in the sale transaction. Running the query, we can see that 5 ETH was paid for a LilNoun on May 16th, 2022.

query TopPurchaseForAnAddress {  sales(where: {buyerAddresses: "jacob.eth"},         sort: {sortKey: NATIVE_PRICE, sortDirection: DESC},         pagination: {limit: 1}) {    nodes {      sale {        price {          nativePrice {            decimal          }        }        saleType        sellerAddress        transactionInfo {          transactionHash          blockTimestamp        }      }      token {        collectionAddress        tokenId        name        description      }    }  }}

Getting Data for a Specific NFT#

Now that you have a sense of how to get data for an address, this section will cover how to get detailed data on a specific NFT. However, this same data can be retrieved in the first tokens query used in the first example above.

note

Collection Name: Monarchs

Contract Address: 0xc729Ce9bF1030fbb639849a96fA8BBD013680B64

TokenID: 246

Token Events#

Every time a transaction interacts with an NFT on the blockchain it creates an event. This query will help you view all the historical events for this NFT including:

  • Mints
  • Transfers
  • Approvals
  • Sales
  • Zora Markets
query TokenEvents {  token(token: {address: "0xc729Ce9bF1030fbb639849a96fA8BBD013680B64", tokenId: "246"}) {    events(sort: {sortKey: CREATED, sortDirection: ASC}) {      eventType      transactionInfo {        blockTimestamp        transactionHash      }    }  }}

Token Sales#

This query will help you get specific data for all sales pertaining to this NFT across all markets:

  • Zora
  • OpenSea
  • LooksRare
  • Nouns Auctions
  • Foundation
  • and more
query TokenSale {  token(token: {address: "0xc729Ce9bF1030fbb639849a96fA8BBD013680B64", tokenId: "246"}) {    sales {      saleType      saleContractAddress      sellerAddress      buyerAddress      transactionInfo {        blockTimestamp        transactionHash      }      price {        nativePrice {          decimal          currency {            name          }        }      }    }  }}

Questions?

Get help in the #developers channel on Discord.

Stay updated

Follow us on Twitter for release updates.

Found a Bug

Learn more here.