Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/ourzora/zdk

Last synced: 3 months ago
JSON representation
Host: GitHub
URL: https://github.com/ourzora/zdk
Owner: ourzora
License: mit
Created: 2020-12-16T22:30:59.000Z (almost 4 years ago)
Default Branch: main
Last Pushed: 2024-06-28T15:22:11.000Z (5 months ago)
Last Synced: 2024-07-30T03:39:20.366Z (4 months ago)
Language: TypeScript
Size: 4.01 MB
Stars: 107
Watchers: 10
Forks: 42
Open Issues: 9
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project

README

        # ZDK 2.0

If you're looking for 1.0 branch use [v1-archive](https://github.com/ourzora/zdk/tree/v1-archive)

### Getting started

```

yarn add @zoralabs/zdk

```

```ts

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](#ZDK)

    * [.tokens(where, filter, pagination, networks, sort, includeFullDetails, includeSalesDetails)](#ZDK+tokens) ⇒

    * [.token(args)](#ZDK+token) ⇒ Promise.<TokenQuery>

[Examples Here](https://replit.com/@iainzora/ZDK-Examples?v=1)



### 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