Skip to main content

Zora Dev Kit (ZDK)

Get started building with the Zora Development Kit (ZDK)


The ZDK makes it easy to access the Zora API without having to know GraphQL.

Check out the ZDK intro guide to see it in action.

note

It is possible to make up to 30 requests per minute without needing an API Key. Please reach out to @ZORAEngineering on Twitter if would like to request a key.

The max response size for all requests is 200 except for zdk.search which is capped at a max size of 50.

NFT Hooks is a tool that makes it even easier to fetch NFT data than the ZDK.


Installing#

View the source code for the ZDK: GH Repository

yarn add @zoralabs/zdk

Instantiating#

import { ZDK, ZDKNetwork, ZDKChain } from "@zoralabs/zdk";
const networkInfo = {    network: ZDKNetwork.Ethereum,    chain: ZDKChain.Mainnet,  }
const API_ENDPOINT = "https://api.zora.co/graphql";const args = {               endPoint:API_ENDPOINT,               networks:[networkInfo],               apiKey: process.env.API_KEY             } 
const zdk = new ZDK(args) // All arguments are optional

API Key (Optional)#

The API has a limit of 30 requests per minute without an API key. If more than 30 requests per minute are necessary then an API is required.

Direct message @ZORAEngineering on Twitter for an API Key.

Network Details (Optional)#

The API currently only supports and defaults to Ethereum Mainnet, but once other chains are available it will be possible to query specific networks by passing an array of different network options.


Argument Definitions#

  • where: Parameters that grab a specific set of NFT data, e.g. collectionAddress
  • filter: Filters down the results from the where parameters into a smaller data set
  • networks: The network and chain to grab NFT data from
  • pagination: A way to set the limit and starting point of the response
  • sort: Sorts the order of the returned data
  • token: An object with a contractAddress and tokenId of a token to look up
  • includeFullDetails: An optional bool to get the full token history and information
  • includeMarkets: An optional bool to get the on-chain market data for the NFTs

Methods#

Note 🚨: All the inputs for the ZDK are objects.

aggregateAttributes#

Gets statistics on all the attributes for a collection.

zdK.aggregateAttributes(  { where })

Returns: Promise.<AggregateAttributesQuery> - Aggregate attributes graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.collectionAddressesList of collection addresses to filter by
where.ownerAddressesList of owner addresses to filter by
where.tokens:Tuple of token and id to filter by an exact match as a list
tokens.addressA string for the contract address to return a token for
tokens.tokenIdA string for the tokenId to return a token for

collection#

Gets data for a specific NFT collection based on an address.

zdK.collection(  { address })

Returns: Promise.<CollectionQuery> - Collection graphql response

ParamDescriptionType
addressString of collection address to filter by

collections#

Gets data for a group of NFT collections.

zdK.collections(  {    where,     pagination,     sort,     includeFullDetails  })

Returns: Promise.<CollectionsQuery> - Collections graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.collectionAddressesList of collection addresses to filter by
paginationSettings for pagination
pagination.afterA string specifying which record to begin pagination
pagination.limitAn int setting the number of event records per page
sortSorting information for tokens
sort.sortDirectionAn enum value specifying the direction of resultsASC, DESC
sort.sortKeyAn enum value specifying the value to sort results byChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetailsinclude entire token details (full uris, history etc.)

collectionStatsAggregate#

Gets statistics for a specific collection such as total supply, number of owners, and sales volume.

zdK.collectionStatsAggregate(  { collectionAddress })

Returns: Promise.<CollectionStatsAggregateQuery> - Collection stats graphql response

ParamDescriptionType
collectionAddressesList of collection addresses to filter by

events#

Gets all the events associated with a collection, token, or owner address e.g. Transfers, Mints, Sales, Approvals.

zdK.events(  {    where,     filter,     pagination,     sort  })

Returns: Promise.<EventsQuery> - Events graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.collectionAddressesList of collection addresses to filter by
where.tokens:Tuple of token and id to filter by an exact match as a list
filterFilter query parameters after the where query
filter.bidderAddressesA string array of addresses that have bid on this NFT
filter.eventTypesAn array of EventTypes
filter.recipientAddressesA string array of addresses that have received this NFT
filter.sellerAddressesA string array of addresses that have sold this NFT
filter.senderAddressesA string array of addresses that have sent this NFT
filter.timeFilterAn input of type TimeFilter for time partitioned event responses.
paginationSettings for pagination
pagination.afterA string specifying which record to begin pagination
pagination.limitAn int setting the number of event records per page
sortSorting information for tokens
sort.directionAn enum value specifying the direction of resultsASC, DESC
sort.sortKeyAn enum value specifying the value to sort results byChainTokenPrice, Created, NativePrice, None, TimeSaleEnding

floorPrice#

Gets data on the cheapest available NFT across all Zora marketplaces.

zdK.floorPrice(  { where })

Returns: Promise.<FloorPriceQuery> - Floor price graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.attributesAn array of the CollectionAttributes
attributes.traitTypeA string to set the trait type to return by
attributes.valueA string of a trait's possible value(s) to return by
where.collectionAddressesList of collection addresses to filter by

markets#

Gets NFTs that are active on the Zora markets e.g. Buy Now, Offers, Auctions.

zdK.markets(  {    where,     filter,     pagination,     sort,     includeFullDetails  })

Returns: Promise.<MarketsQuery> - Markets graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.collectionAddressesList of collection addresses to filter by
where.tokens:Tuple of token and id to filter by an exact match as a list
filterFilter query parameters after the where query
filter.marketQueryFilterArguments for filtering market info expectations
marketQueryFilter.bidderAddressesA string array of addresses that have bid for this NFT
marketQueryFilter.marketTypeAn enum specifying the version of Zora the order is made onV1Ask, V1BidShare, V1Offer, V2Auction, V3Ask
marketQueryFilter.statusesAn enum specifying status of orders being returnedActive, Canceled, Completed
filter.priceFilterArguments for filtering price ranges
priceFilter.currencyAddressA string specifying the currency being used for the market transaction to be returned
priceFilter.maximumChainTokenPriceA string specifying the maximum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.maximumNativePriceA string specifying the minimum price of the native chain token (ETH in our case) to return
priceFilter.minimumChainTokenPriceA string specifying the minimum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.minimumNativePriceA string specifying the minimum price of the native chain token (ETH in our case) to return
sortSorting information for tokens
sort.sortDirectionAn enum value specifying the direction of resultsASC, DESC
sort.sortKeyAn enum value specifying the value to sort results byChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetailsinclude entire token details (full uris, history etc.)

mints#

Gets historic minting data for any NFT or any group of NFTs.

zdK.mints(  {    where,     filter,     pagination,     sort,     includeFullDetails,     includeMarkets  })

Returns: Promise.<MintsQuery> - Mints graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.collectionAddressesList of collection addresses to filter by
where.minterAddresses:List of minter addresses to filter by
where.recipientAddressesList of receiver addresses to filter by
where.tokens:Tuple of token and id to filter by an exact match as a list
filterFilter query parameters after the where query
filter.timeFilterAn input of type TimeFilter for time partitioned event responses.
timeFilter.endDateA string in ISO format to state the end range
timeFilter.lookbackHoursAn int used to look back a certain number of hours
timeFilter.startDateA string in ISO format to state the start range
filter.priceFilterArguments for filtering price ranges
priceFilter.currencyAddressA string specifying the currency being used for the market transaction to be returned
priceFilter.maximumChainTokenPriceA string specifying the maximum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.maximumNativePriceA string specifying the minimum price of the native chain token (ETH in our case) to return
priceFilter.minimumChainTokenPriceA string specifying the minimum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.minimumNativePriceA string specifying the minimum price of the native chain token (ETH in our case) to return
paginationSettings for pagination
pagination.afterA string specifying which record to begin pagination
pagination.limitAn int setting the number of event records per page
sortSorting information for tokens
sort.sortDirectionAn enum value specifying the direction of resultsASC, DESC
sort.sortKeyAn enum value specifying the value to sort results byChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetailsinclude entire token details (full uris, history etc.)
includeMarketsinclude entire market details for these contracts

nftCount#

Gets data on the total supply of NFTs in a collection.

zdK.nftCount(  { where })

Returns: Promise.<NftCountQuery> - NFT count graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.attributesAn array of the CollectionAttributes
attributes.traitTypeA string to set the trait type to return by
attributes.valueA string of a trait's possible value(s) to return by
where.collectionAddressesList of collection addresses to filter by
where.ownerAddressesList of owner addresses to filter by

ownerCount#

Gets the number of unique addresses that own an NFT from a collection.

zdK.ownerCount(  { where })

Returns: Promise.<OwnerCountQuery> - Owner count graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.attributesAn array of the CollectionAttributes
attributes.traitTypeA string to set the trait type to return by
attributes.valueA string of a trait's possible value(s) to return by
where.collectionAddressesList of collection addresses to filter by

ownersByCount#

Gets the number of NFTs held by certain owner addresses e.g. Top holders of a collection.

zdK.ownersByCount(  {    where,     pagination  })

Returns: Promise.<OwnersByCountQuery> - Owners by count graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.attributesAn array of the CollectionAttributes
attributes.traitTypeA string to set the trait type to return by
attributes.valueA string of a trait's possible value(s) to return by
where.collectionAddressesList of collection addresses to filter by
paginationSettings for pagination
pagination.afterA string specifying which record to begin pagination
pagination.limitAn int setting the number of event records per page

sales#

Gets sales data for any NFT across multiple marketplaces e.g. Zora, OpenSea, LooksRare, Foundation, etc.

zdK.sales(   {    where,     filter,     pagination,     sort,     includeFullDetails  })

Returns: Promise.<SalesQuery> - Sales graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.buyerAddresses:List of minter addresses to filter by
where.collectionAddressesList of collection addresses to filter by
where.sellerAddressesList of receiver addresses to filter by
where.tokens:Tuple of token and id to filter by an exact match as a list
filterFilter query parameters after the where query
filter.timeFilterAn input of type TimeFilter for time partitioned event responses.
timeFilter.endDateA string in ISO format to state the end range
timeFilter.lookbackHoursAn int used to look back a certain number of hours
timeFilter.startDateA string in ISO format to state the end range
filter.priceFilterArguments for filtering price ranges
priceFilter.currencyAddressA string specifying the currency being used for the market transaction to be returned
priceFilter.maximumChainTokenPriceA string specifying the maximum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.maximumNativePriceA string specifying the minimum price of the native chain token (ETH in our case) to return
priceFilter.minimumChainTokenPriceA string specifying the minimum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.minimumNativePriceA string specifying the minimum price of the native chain token (ETH in our case) to return
sortSorting information for tokens
sort.sortDirectionAn enum value specifying the direction of resultsASC, DESC
sort.sortKeyAn enum value specifying the value to sort results byChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetailsinclude entire token details (full uris, history etc.)
includeMarketsinclude entire market details for these contracts

salesVolume#

Gets the total sales volume for a collection across all marketplaces.

zdK.salesVolume(  {    where,     timeFilter  })

Returns: Promise.<SalesVolumeQuery> - Sales volume graphql response

ParamDescriptionType
whereArguments to filter tokens by, required.
where.attributesAn array of the CollectionAttributes
attributes.traitTypeA string to set the trait type to return by
attributes.valueA string of a trait's possible value(s) to return by
where.collectionAddressesList of collection addresses to filter by
timeFilterAn input of type TimeFilter for time partitioned event responses.
timeFilter.endDateA string in ISO format to state the end range
timeFilter.lookbackHoursAn int used to look back a certain number of hours
timeFilter.startDateA string in ISO format to state the end range

search#

Search for an NFT or collection based on a string input.

zdK.search(  {    query,     pagination,     filter  })

Returns: Promise.<SearchQuery> - Search query graphql response

ParamDescriptionType
queryA text string to query with
paginationSettings for pagination
pagination.afterA string specifying which record to begin pagination
pagination.limitAn int setting the number of event records per page
filterParameters for setting query filter
filter.collectionAddressesAn array of string addresses to query with
filter.entityTypeAn enum specifying the entity type being queriedCOLLECTION, TOKEN

token#

Gets data on a single NFT given a contract address and tokenId.

zdK.token(  {    token,    includeFullDetails  })

Returns: Promise.<TokenQuery> - Token graphql response

ParamTypeDescription
tokenToken parameters
token.addressstringaddress of the token (req'd)
token.tokenIdstringstring ID of the token (req'd)
includeFullDetailsboolshould full details be added to the response

tokens#

Gets data on a group of tokens based on query parameters.

zdK.tokens(  {    where,     filter,     pagination,     sort,     includeFullDetails,     includeSalesHistory  })

Returns: Promise of response from tokens of type TokensQuery

ParamDescription
whereArguments to filter tokens by, required.
where.collectionAddressesList of collection addresses to filter by
where.ownerAddressesList of owner addresses to filter by
where.tokens:Tuple of token and id to filter by an exact match as a list
filterFilter query parameters after the where query
paginationSettings for pagination
sortSorting information for tokens
includeFullDetailsinclude entire token details (full uris, history etc.)
includeSalesHistoryinclude full token sale details for the last 10 sales