Skip to main content

Using the ZDK

Learn how to use the Zora Development Kit to retrieve NFT data.


This guide will walk you through how to retrieve different data for Blitmaps.

Initial Setup#

We can begin by installing and importing the @zoralabs/zdk package. Note, an API key is not required if you are making less than 30 requests per minute.

yarn add @zoralabs/zdk or npm install @zoralabs/zdk

Blitmap Contract Address: 0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63

import { ZDK } from "@zoralabs/zdk";
const API_ENDPOINT = "https://api.zora.co/graphql";const zdk = new ZDK({ endpoint: API_ENDPOINT }); // Defaults to Ethereum Mainnet

Getting Data for a Specific NFT#

Now that we have an instance of the ZDK set up we can start calling functions on it. First, let's get data for a specific NFT by looking at Blitmap tokenId: 314 then call zdk.token by passing in the contractAddress and tokenId.

const args = {  token: {    address: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63",    tokenId: "314"  },  includeFullDetails: false // Optional, provides more data on the NFT such as all historical events}
const response = await zdk.token(args)

We can see in the response tab that we are getting back data specific to that tokenId including mint information, the current owner, as well as the media URIs. Note, that if we wanted to see all the historical events (Transfers, Sales, Approvals, etc) for this NFT we would need to set includeFullDetails to true.


NFT Balance for an Address#

It is also possible to get data for specific owner addresses. Let's get started by looking at dom.eth. We can use zdk.tokens to get all the NFTs in their address, however, we can be even more specific by setting collectionAddresses to the Blitmap address to filter for Blitmaps held by the owner.

const args = {   where: {     collectionAddresses: ["0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63"],     ownerAddresses: ["dom.eth"]   },   sort: { // Optional, sorts the response by ascending tokenIds    direct: "ASC",     sortKey: "TokenId"  },   pagination: {limit: 3}, // Optional, limits the response size to 3 NFTs  includeFullDetails: false, // Optional, provides more data on the NFTs such as events  includeSalesHistory: false // Optional, provides sales data on the NFTs};
const response = await zdk.tokens(args);

Looking at the response, we can see that only 3 Blitmap NFTs were returned because the limit was set 3 and they are ordered in descending order of tokenId based on the sort argument.


Preview Collections#

Next, we can get a preview of a few collections by calling zdk.collections with an array of collectionAddresses.

const args = {  where: {collectionAddresses: [      "0xE169c2ED585e62B1d32615BF2591093A629549b6",      "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63",      "0x82262bFba3E25816b4C720F1070A71C7c16A8fc4"    ]  },  includeFullDetails: false}
const response = await zdk.collections(args)

In the response we can see that we are getting back the collection name, total supply, and a few other details. If we set includeFullDetails to true then we would also get back all the attributes and their statistics.


Collection Stats#

We can also get detailed statistics for a collection by calling zdk.collectionStatsAggregate with the Blitmap collectionAddress.

const args = {  collectionAddress: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63",};
const response = await zdk.collectionStatsAggregate(args);

We can see this returns the ownerCount (how many addresses own an NFT from that collection), the nftCount (total supply), and detailed sales data.


Collection Attribute Stats#

Diving deeper into Collection data, we can now look at the attribute stats. These stats tell the amount of NFTs that have a certain attribute and the percent of how many NFTs in the collection have that attribute. Attribute stats can be retrieved by calling zdk.aggregateAttributes with the collectionAddress.

const args = {   where: {     collectionAddresses: ["0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63"]   }, };
const response = await zdk.aggregateAttributes(args);

We can see that we're getting back all the attributes for Blitmaps as well as their rarities and counts. For example, there are 100 Blitmaps that have the Type of Original which is only possessed by 5.88% of all Blitmaps


Searching By Keyword#

Searching for an NFT or collection with a specific keyword has never been easier. Here we are calling zdk.search and passing in the query "flow". We're also filtering by the Blitmap collectionAddress and the entityType TOKEN with a limit of 3 NFTs.

const args = {  query: "flow",  filter: {     collectionAddresses: ["0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63"],     entityType: 'TOKEN'   },  pagination: { limit: 3 } // Optional, caps the limit of the response to 3 NFTs};
const response = await zdk.search(args);

Looking at the response tab, we can see that the three different Blitmaps all have the word "flow" associated with their metadata.

  • #98 - Chaos Flow
  • #805 - Chaos Flow Dunce
  • #819 - Chaos Flow Chessbirdy

Sales Volume Across All Markets#

Lastly, we can get sales data for all the Blitmaps that have ever been sold on multiple marketplaces including:

  • Zora
  • OpenSea
  • LooksRare
  • and many more

We can retrieve this data by calling zdk.salesVolume with the Blitmap address.

const args = {  where: {     collectionAddresses: ["0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63"]  }};
const response = await zdk.salesVolume(args);

Looking at the response, we get back usdcPrice, chainTokenPrice, and totalCount. usdcPrice is the volume in USDC at the time of the sales, while chainTokenPrice is the volume measured in the chain's gas token e.g. Ethereum = ETH. totalCount is the number of sales that have happened across all marketplaces.