ZDK 2.0
If you're looking for 1.0 branch use v1-archive
Getting started
yarn add @zoralabs/zdk
import { ZDK, ZDKChain, ZDKNetwork } from '@zoralabs/zdk';
// assuming you set API_ENDPOINT to https://api.zora.co/graphql
const API_ENDPOINT = process.env.API_ENDPOINT;
const zdk = new ZDK({
endpoint: API_ENDPOINT,
networks: [
{
chain: ZDKChain.Mainnet,
network: ZDKNetwork.Ethereum,
},
],
apiKey: API_KEY // optional!
);ZDK
ZDK Main Interface class
Kind: global class
-
ZDK
- .tokens(where, filter, pagination, networks, sort, includeFullDetails, includeSalesDetails) ⇒
-
.token(args) ⇒
Promise.<TokenQuery>
zdk.tokens(where, filter, pagination, networks, sort, includeFullDetails, includeSalesDetails) ⇒
Gets data on a group of tokens based on query parameters.
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 |
| networks | Networks to query on |
| sort | Sorting information for tokens |
| includeFullDetails | include entire token details (full uris, history etc.) |
| includeSalesDetails | include full token sale details for the last 10 sales |
zdk.token(args) ⇒ Promise.<TokenQuery>
Gets data on a single NFT give a contract address and tokenId.
Returns: Promise.<TokenQuery> - Token graphql response
| Param | Type | Description |
|---|---|---|
| args | arguemnts for query object | |
| args.token | Token parameters | |
| args.token.address | string |
address of the token (req'd) |
| args.token.tokenId | string |
string ID of the token (req'd) |
| args.network | the network to use to retrieve the token | |
| args.network.chain | Chain |
Chain to use (default ETHEREUM) |
| args.network.network | Network |
Network on the given chain to use (default MAINNET) |
| args.includeFullDetails | bool |
should full details be added to the response |
zdk.events(where, filter, pagination, networks, sort) ⇒
Gets all the events associated with a collection, token, or owner address e.g. Transfers, Mints, Sales, Approvals
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 | |
| networks | Network info to query on as an array of enums | |
| networks.chain | Chain to query on (currently only MAINNET) | |
| networks.network | Network to query on (currently only ETHEREUM) | |
| 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 |
zdk.markets(where, filter, pagination, networks, sort, includeFullDetails) ⇒
Gets NFTs that are active on the Zora markets e.g. Buy Now, Offers, Auctions
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 |
| networks | Argument for chain to query as an array of enums | |
| networks.chain | Chain to query on (currently only MAINNET) | |
| networks.network | Network to query on (currently only ETHEREUM) | |
| includeFullDetails | include entire token details (full uris, history etc.) |
zdk.mints(where, filter, pagination, networks, sort, includeFullDetails, includeMarkets) ⇒
Gets historic minting data for any NFT or any group of NFTs.
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 date string specifying when to stop collecting mint data | |
| timeFilter.lookbackHours | A string specifying how many hours to look back from an end date | |
| timeFilter.startDate | A date string specifying when to start collecting mint data | |
| 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 |
| networks | Argument for chain to query as an array of enums | |
| networks.chain | Chain to query on (currently only MAINNET) | |
| networks.network | Network to query on (currently only ETHEREUM) | |
| includeFullDetails | include entire token details (full uris, history etc.) | |
| includeMarkets | include entire market details for these contracts |
zdk.sales(where, filter, pagination, networks, sort, includeFullDetails) ⇒
Gets sales data for any NFT or collection across multiple marketplaces e.g. Zora, OpenSea, LooksRare, Foundation, etc.
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.timeFilter | An input of type TimeFilter for time partitioned event responses. | |
| timeFilter.endDate | A date string specifying when to stop collecting mint data | |
| timeFilter.lookbackHours | A string specifying how many hours to look back from an end date | |
| timeFilter.startDate | A date string specifying when to start collecting mint data | |
| 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 |
| networks | Argument for chain to query as an array of enums | |
| networks.chain | Chain to query on (currently only MAINNET) | |
| networks.network | Network to query on (currently only ETHEREUM) | |
| includeFullDetails | include entire token details (full uris, history etc.) | |
| includeMarkets | include entire market details for these contracts |
zdk.collections(where, pagination, networks, sort, includeFullDetails) ⇒
Gets data for a group of NFT collections.
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 | |
| networks | Argument for chain to query as an array of enums | |
| networks.chain | Chain to query on (currently only MAINNET) | |
| networks.network | Network to query on (currently only ETHEREUM) | |
| 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.) |
zdk.collectionStatsAggregate(collectionAddress, network) ⇒
Gets statistics for a specific collection such as the total supply, number of owners and sales volume.
Returns: Promise.<CollectionStatsAggregateQuery> - Collection stats graphql response
| Param | Description | Type |
|---|---|---|
| collectionAddresses | List of collection addresses to filter by | |
| network | Argument for chain to query as an array of enums | |
| network.chain | Chain to query on (currently only MAINNET) | |
| network.network | Network to query on (currently only ETHEREUM) |
zdk.collection(address, network) ⇒
Gets data for a specific NFT collection based on an address.
Returns: Promise.<CollectionQuery> - Collection graphql response
| Param | Description | Type |
|---|---|---|
| address | String of collection address to filter by | |
| network | Argument for chain to query as an array of enums | |
| network.chain | Chain to query on (currently only MAINNET) | |
| network.network | Network to query on (currently only ETHEREUM) |
zdk.ownersByCount(where, pagination, networks) ⇒
Gets the number of NFTs held be certain owner addresses e.g. Top holders of a collection.
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 | |
| networks | Argument for chain to query as an array of enums | |
| network.chains | Chain to query on (currently only MAINNET) | |
| network.networks | Network to query on (currently only ETHEREUM) |
zdk.aggregateAttributes(where, networks) ⇒
Gets statistics on all the attributes for a collection.
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 | |
| networks | Argument for chain to query as an array of enums | |
| network.chain | Chain to query on (currently only MAINNET) | |
| network.network | Network to query on (currently only ETHEREUM) |
zdk.salesVolume(where, networks, timeFilter) ⇒
Gets the total sales volume for a collection across all marketplaces.
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 | |
| networks | Argument for chain to query as an array of enums | |
| network.chains | Chain to query on (currently only MAINNET) | |
| network.networks | Network to query on (currently only ETHEREUM) | |
| timeFilter | Network to query on (currently only ETHEREUM) | |
| timeFilter.endDate | A string array of addresses that have bid for this NFT | |
| timeFilter.lookbackHours | An enum specifying the version of Zora the order is made on | V1Ask, V1BidShare, V1Offer, V2Auction, V3Ask |
| timeFilter.startDate | An enum specifying status of orders being returned | Active, Canceled, Completed |
zdk.ownerCount(where, networks) ⇒
Gets the number of NFTs held be certain owner addresses e.g. Top holders of a collection.
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 | |
| networks | Argument for chain to query as an array of enums | |
| network.chains | Chain to query on (currently only MAINNET) | |
| network.networks | Network to query on (currently only ETHEREUM) |
zdk.floorPrice(where, networks) ⇒
Gets data on the cheapest available NFT across all Zora marketplaces.
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 | |
| networks | Argument for chain to query as an array of enums | |
| network.chains | Chain to query on (currently only MAINNET) | |
| network.networks | Network to query on (currently only ETHEREUM) |
zdk.nftCount(where, networks) ⇒
Gets data on the total supply of NFTs in a collection.
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 | |
| networks | Argument for chain to query as an array of enums | |
| network.chains | Chain to query on (currently only MAINNET) | |
| network.networks | Network to query on (currently only ETHEREUM) |
zdk.search(pagination, query, filter) ⇒
Searchs for an NFT or collection based on a string input.
Returns: Promise.<SearchQuery> - Search query graphql response
| Param | Description | Type |
|---|---|---|
| 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 | |
| query | A text string to query with | |
| 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 |