zdk.mdx

id	title
zdk	Zora Dev Kit (ZDK)

import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem'

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

<Tabs defaultValue="yarn" values={[ { label: 'Yarn', value: 'yarn', }, { label: 'NPM', value: 'npm', } ] }>

yarn add @zoralabs/zdk

npm install @zoralabs/zdk --save

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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.collectionAddresses	List of collection addresses to filter by
where.ownerAddresses	List of owner addresses to filter by
where.tokens:	Tuple of token and id to filter by an exact match as a list
tokens.address	A string for the contract address to return a token for
tokens.tokenId	A 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

Param	Description	Type
address	String 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.collectionAddresses	List of collection addresses to filter by
pagination	Settings for pagination
pagination.after	A string specifying which record to begin pagination
pagination.limit	An int setting the number of event records per page
sort	Sorting information for tokens
sort.sortDirection	An enum value specifying the direction of results	ASC, DESC
sort.sortKey	An enum value specifying the value to sort results by	ChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetails	include 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

Param	Description	Type
collectionAddresses	List 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.collectionAddresses	List of collection addresses to filter by
where.tokens:	Tuple of token and id to filter by an exact match as a list
filter	Filter query parameters after the where query
filter.bidderAddresses	A string array of addresses that have bid on this NFT
filter.eventTypes	An array of EventTypes
filter.recipientAddresses	A string array of addresses that have received this NFT
filter.sellerAddresses	A string array of addresses that have sold this NFT
filter.senderAddresses	A string array of addresses that have sent this NFT
filter.timeFilter	An input of type TimeFilter for time partitioned event responses.
pagination	Settings for pagination
pagination.after	A string specifying which record to begin pagination
pagination.limit	An int setting the number of event records per page
sort	Sorting information for tokens
sort.direction	An enum value specifying the direction of results	ASC, DESC
sort.sortKey	An enum value specifying the value to sort results by	ChainTokenPrice, 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.attributes	An array of the CollectionAttributes
attributes.traitType	A string to set the trait type to return by
attributes.value	A string of a trait's possible value(s) to return by
where.collectionAddresses	List 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.collectionAddresses	List of collection addresses to filter by
where.tokens:	Tuple of token and id to filter by an exact match as a list
filter	Filter query parameters after the where query
filter.marketQueryFilter	Arguments for filtering market info expectations
marketQueryFilter.bidderAddresses	A string array of addresses that have bid for this NFT
marketQueryFilter.marketType	An enum specifying the version of Zora the order is made on	V1Ask, V1BidShare, V1Offer, V2Auction, V3Ask
marketQueryFilter.statuses	An enum specifying status of orders being returned	Active, Canceled, Completed
filter.priceFilter	Arguments for filtering price ranges
priceFilter.currencyAddress	A string specifying the currency being used for the market transaction to be returned
priceFilter.maximumChainTokenPrice	A string specifying the maximum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.maximumNativePrice	A string specifying the minimum price of the native chain token (ETH in our case) to return
priceFilter.minimumChainTokenPrice	A string specifying the minimum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.minimumNativePrice	A string specifying the minimum price of the native chain token (ETH in our case) to return
sort	Sorting information for tokens
sort.sortDirection	An enum value specifying the direction of results	ASC, DESC
sort.sortKey	An enum value specifying the value to sort results by	ChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetails	include 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.collectionAddresses	List of collection addresses to filter by
where.minterAddresses:	List of minter addresses to filter by
where.recipientAddresses	List of receiver addresses to filter by
where.tokens:	Tuple of token and id to filter by an exact match as a list
filter	Filter query parameters after the where query
filter.timeFilter	An input of type TimeFilter for time partitioned event responses.
timeFilter.endDate	A string in ISO format to state the end range
timeFilter.lookbackHours	An int used to look back a certain number of hours
timeFilter.startDate	A string in ISO format to state the start range
filter.priceFilter	Arguments for filtering price ranges
priceFilter.currencyAddress	A string specifying the currency being used for the market transaction to be returned
priceFilter.maximumChainTokenPrice	A string specifying the maximum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.maximumNativePrice	A string specifying the minimum price of the native chain token (ETH in our case) to return
priceFilter.minimumChainTokenPrice	A string specifying the minimum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.minimumNativePrice	A string specifying the minimum price of the native chain token (ETH in our case) to return
pagination	Settings for pagination
pagination.after	A string specifying which record to begin pagination
pagination.limit	An int setting the number of event records per page
sort	Sorting information for tokens
sort.sortDirection	An enum value specifying the direction of results	ASC, DESC
sort.sortKey	An enum value specifying the value to sort results by	ChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetails	include entire token details (full uris, history etc.)
includeMarkets	include 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.attributes	An array of the CollectionAttributes
attributes.traitType	A string to set the trait type to return by
attributes.value	A string of a trait's possible value(s) to return by
where.collectionAddresses	List of collection addresses to filter by
where.ownerAddresses	List 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.attributes	An array of the CollectionAttributes
attributes.traitType	A string to set the trait type to return by
attributes.value	A string of a trait's possible value(s) to return by
where.collectionAddresses	List 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.attributes	An array of the CollectionAttributes
attributes.traitType	A string to set the trait type to return by
attributes.value	A string of a trait's possible value(s) to return by
where.collectionAddresses	List of collection addresses to filter by
pagination	Settings for pagination
pagination.after	A string specifying which record to begin pagination
pagination.limit	An 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.buyerAddresses:	List of minter addresses to filter by
where.collectionAddresses	List of collection addresses to filter by
where.sellerAddresses	List of receiver addresses to filter by
where.tokens:	Tuple of token and id to filter by an exact match as a list
filter	Filter query parameters after the where query
filter.timeFilter	An input of type TimeFilter for time partitioned event responses.
timeFilter.endDate	A string in ISO format to state the end range
timeFilter.lookbackHours	An int used to look back a certain number of hours
timeFilter.startDate	A string in ISO format to state the end range
filter.priceFilter	Arguments for filtering price ranges
priceFilter.currencyAddress	A string specifying the currency being used for the market transaction to be returned
priceFilter.maximumChainTokenPrice	A string specifying the maximum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.maximumNativePrice	A string specifying the minimum price of the native chain token (ETH in our case) to return
priceFilter.minimumChainTokenPrice	A string specifying the minimum price of the native chain token (ETH, MATIC, etc) to return
priceFilter.minimumNativePrice	A string specifying the minimum price of the native chain token (ETH in our case) to return
sort	Sorting information for tokens
sort.sortDirection	An enum value specifying the direction of results	ASC, DESC
sort.sortKey	An enum value specifying the value to sort results by	ChainTokenPrice, Created, NativePrice, None, TimeSaleEnding
includeFullDetails	include entire token details (full uris, history etc.)
includeMarkets	include 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

Param	Description	Type
where	Arguments to filter tokens by, required.
where.attributes	An array of the CollectionAttributes
attributes.traitType	A string to set the trait type to return by
attributes.value	A string of a trait's possible value(s) to return by
where.collectionAddresses	List of collection addresses to filter by
timeFilter	An input of type TimeFilter for time partitioned event responses.
timeFilter.endDate	A string in ISO format to state the end range
timeFilter.lookbackHours	An int used to look back a certain number of hours
timeFilter.startDate	A 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

Param	Description	Type
query	A text string to query with
pagination	Settings for pagination
pagination.after	A string specifying which record to begin pagination
pagination.limit	An int setting the number of event records per page
filter	Parameters for setting query filter
filter.collectionAddresses	An array of string addresses to query with
filter.entityType	An enum specifying the entity type being queried	COLLECTION, TOKEN

---

token

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

zdK.token(
  {
    token,
    includeFullDetails
  }
)

Returns: Promise.<TokenQuery> - Token graphql response

Param	Type	Description
token		Token parameters
token.address	string	address of the token (req'd)
token.tokenId	string	string ID of the token (req'd)
includeFullDetails	bool	should 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

Param	Description
where	Arguments to filter tokens by, required.
where.collectionAddresses	List of collection addresses to filter by
where.ownerAddresses	List of owner addresses to filter by
where.tokens:	Tuple of token and id to filter by an exact match as a list
filter	Filter query parameters after the where query
pagination	Settings for pagination
sort	Sorting information for tokens
includeFullDetails	include entire token details (full uris, history etc.)
includeSalesHistory	include full token sale details for the last 10 sales

---