Merge pull request #16 from nftscan-official/release

Release
nftscan-official · Aug 8, 2023 · 01318e3 · 01318e3
2 parents 2a6c566 + 5cb93c5
commit 01318e3
Show file tree

Hide file tree

Showing 9 changed files with 116 additions and 31 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,19 @@
 # Changelog
+## [1.9.0](https://github.com/nftscan-official/nftscan-api-js-sdk/compare/v1.8.1...v1.9.0) (2023-08-08)
+
+
+### 🐛 Bug Fixes | Bug 修复
+
+* Modify the return data type of `getMultiChainAssets` interface to array ([d86aa9b](https://github.com/nftscan-official/nftscan-api-js-sdk/commit/d86aa9b553c7345bbfe4f7fc3d9541920b036181))
+
+
+### ✨ Features | 新功能
+
+* add input params `sort_direction`, `sort_field` to `queryAssetsByAttributes` interface ([eec8456](https://github.com/nftscan-official/nftscan-api-js-sdk/commit/eec845629536f5bb8ef306e58be35acc32290981))
+* add interface `getCollectionTopHolder` ([a4e66fc](https://github.com/nftscan-official/nftscan-api-js-sdk/commit/a4e66fc9a5bc72eec5b587a6cb9078f0b75fc6df))
+* The response data of the interface `getAccountOverview` adds a new attribute `collection_count` ([6ccbc92](https://github.com/nftscan-official/nftscan-api-js-sdk/commit/6ccbc920602794a2562e88246df8b170d61a970d))
+* added support the EVM-like chain `zkSync Era` & `Linea` ([0a3d1df](https://github.com/nftscan-official/nftscan-api-js-sdk/commit/0a3d1df8b5558e12ab8738392260ef59db209232))
+
 ### [1.8.1](https://github.com/nftscan-official/nftscan-api-js-sdk/compare/v1.8.0...v1.8.1) (2023-06-27)
 
 

diff --git a/README.md b/README.md
@@ -5,20 +5,22 @@ To use our APIs, You need to register an account on NFTScan open platform [OpenA
 
 The SDK currently supports the following chains:
 
-| Blockchain | Domain name             | Short name |
-| ---------- | ----------------------- | ---------- |
-| Ethereum   | restapi.nftscan.com     | eth        |
-| BNB chain  | bnbapi.nftscan.com      | bnb        |
-| Polygon    | polygonapi.nftscan.com  | polygon    |
-| Moonbeam   | moonbeamapi.nftscan.com | moonbeam   |
-| Arbitrum   | arbitrumapi.nftscan.com | arbitrum   |
-| Optimism   | optimismapi.nftscan.com | optimism   |
-| PlatON     | platonapi.nftscan.com   | platon     |
-| Avalanche  | avaxapi.nftscan.com     | avalanche  |
-| Cronos     | cronosapi.nftscan.com   | cronos     |
-| Fantom     | fantomapi.nftscan.com   | fantom     |
-| Gnosis     | gnosisapi.nftscan.com   | gnosis     |
-| Solana     | solanaapi.nftscan.com   | solana     |
+| Blockchain   | Domain name             | Short name |
+| ------------ | ----------------------- | ---------- |
+| Ethereum     | restapi.nftscan.com     | eth        |
+| BNB chain    | bnbapi.nftscan.com      | bnb        |
+| Polygon      | polygonapi.nftscan.com  | polygon    |
+| Moonbeam     | moonbeamapi.nftscan.com | moonbeam   |
+| Arbitrum One | arbitrumapi.nftscan.com | arbitrum   |
+| OP Mainnet   | optimismapi.nftscan.com | optimism   |
+| zkSync Era   | zksyncapi.nftscan.com   | zksync     |
+| Linea        | lineaapi.nftscan.com    | linea      |
+| PlatON       | platonapi.nftscan.com   | platon     |
+| Avalanche-C  | avaxapi.nftscan.com     | avalanche  |
+| Cronos       | cronosapi.nftscan.com   | cronos     |
+| Fantom       | fantomapi.nftscan.com   | fantom     |
+| Gnosis       | gnosisapi.nftscan.com   | gnosis     |
+| Solana       | solanaapi.nftscan.com   | solana     |
 
 *The value of **Short name** is used in the SDK as an initialization configuration parameter.*
 
@@ -55,15 +57,17 @@ The complete enumeration value of `EvmChain` includes the following:
 export enum EvmChain {
   ETH = 'eth',
   BNB = 'bnb',
-  ARBITRUM = 'arbitrum',
-  MOONBEAM = 'moonbeam',
   POLYGON = 'polygon',
+  ARBITRUM = 'arbitrum',
   OPTIMISM = 'optimism',
-  PLATON = 'platon',
+  ZKSYNC = 'zksync',
+  LINEA = 'linea',
   AVALANCHE = 'avalanche',
+  MOONBEAM = 'moonbeam',
+  PLATON = 'platon',
   CRONOS = 'cronos',
   FANTOM = 'fantom',
-  Gnosis = 'gnosis',
+  GNOSIS = 'gnosis',
 }
 ```
 
@@ -167,6 +171,7 @@ As follows:
     - `getCollectionHoldingPeriodDistribution()`: [Collection Holding Period Distribution](https://docs.nftscan.com/reference/evm/collection-holding-period-distribution)
     - `getCollectionBlueChipList()`: [Collection Blue Chip List](https://docs.nftscan.com/reference/evm/collection-blue-chip-list)
     - `getAccountHoldingDistribution()`: [Account Holding Distribution](https://docs.nftscan.com/reference/evm/account-holding-distribution)
+    - `getCollectionTopHolder()`: [Collection Top Holder](https://docs.nftscan.com/reference/evm/collection-top-holder)
   - ##### Refresh (`new NftscanEvm().refresh.*`)
      - `refreshAsset()`: [Refresh an asset](https://docs.nftscan.com/reference/evm/refresh-nft-metadata)
      - `refreshContract()`:[Refresh a contract](https://docs.nftscan.com/reference/evm/refresh-nft-metadata-by-contract)

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "nftscan-api",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "js/ts SDK for NFTScan APIs",
   "main": "dist/cjs/index.js",
   "main-es": "dist/es/index.js",

diff --git a/src/api/evm/asset/index.ts b/src/api/evm/asset/index.ts
@@ -5,7 +5,6 @@ import {
   AssetsByContractParams,
   BatchQueryAssetsListItemParams,
   BatchQueryAssetsParams,
-  CommonAssetParams,
   QueryAssetsByAttributesParams,
   QueryAssetsByFiltersParams,
 } from '../../../types/evm/asset/request-params';
@@ -257,13 +256,14 @@ export default class NftscanEvmAsset extends BaseApi<NftscanConfig> {
    * @param accountAddress The address of the owner of the assets
    * @param chain The short name of chain(eth, bnb, polygon, moonbeam, arbitrum, optimism, platon, avalanche). Using ';' to separate multiple chains
    * @param ercType Can be erc721 or erc1155.
-   * @returns Promise<{@link QueryMultiChainAssets}>
+   * @returns Promise<Array<{@link QueryMultiChainAssets}>>
+   *
    */
   getMultiChainAssets(
     accountAddress: string,
     chain: Array<EvmChain>,
     ercType?: ErcType,
-  ): Promise<QueryMultiChainAssets> {
+  ): Promise<Array<QueryMultiChainAssets>> {
     if (isEmpty(accountAddress)) {
       return missingParamError('accountAddress');
     }
@@ -274,7 +274,7 @@ export default class NftscanEvmAsset extends BaseApi<NftscanConfig> {
 
     const params: NsObject = { chain: chain.join(';'), erc_type: ercType };
 
-    return nftscanGet<NsObject, QueryMultiChainAssets>(
+    return nftscanGet<NsObject, Array<QueryMultiChainAssets>>(
       this.config,
       `${NftscanConst.API.evm.assets.getMultiChainAssets}${accountAddress}`,
       params,

diff --git a/src/api/evm/statistic/index.ts b/src/api/evm/statistic/index.ts
@@ -7,10 +7,15 @@ import {
   QueryWalletRankingParams,
 } from '../../../types/evm/statistic/request-params';
 import {
+  AccountHoldingDistributionResponse,
+  CollectionBlueChipListResponse,
+  CollectionHoldingDistributionResponse,
+  CollectionOverviewResponse,
   QueryAccountOverviewResponse,
   QueryBlueChipStatisticsResponse,
   QueryCollectionRankingResponse,
   QueryCollectionStatisticsResponse,
+  QueryCollectionTopHolderResponse,
   QueryCollectionTradeResponse,
   QueryCollectionTrendingResponse,
   QueryGasRankingResponse,
@@ -20,12 +25,8 @@ import {
   QueryMintRankingResponse,
   QueryTradeRankingResponse,
   QueryTradersRankingResponse,
-  CollectionOverviewResponse,
-  WalletRankingResponse,
   TradeWalletRankingResponse,
-  CollectionHoldingDistributionResponse,
-  CollectionBlueChipListResponse,
-  AccountHoldingDistributionResponse,
+  WalletRankingResponse,
 } from '../../../types/evm/statistic/response-data';
 import { invalidLimitError, missingParamError } from '../../../types/nftscan-error';
 import { NftscanConfig, NsObject, RangeType, SortDirection, TradeType } from '../../../types/nftscan-type';
@@ -139,6 +140,30 @@ export default class NftscanEvmStatistic extends BaseApi<NftscanConfig> {
     );
   }
 
+  /**
+   * Collection Top Holder
+   * - This endpoint returns top holder statistics referring to NFTScan Holders({@link https://www.nftscan.com/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d?module=Holders}).
+   * - details: {@link https://docs.nftscan.com/reference/evm/collection-top-holder}
+   * @param contractAddress The NFT contract address
+   * @param limit Result size. Defaults to 20, capped at 100
+   * @returns Promise<Array<{@link QueryCollectionTopHolderResponse}>>
+   */
+  getCollectionTopHolder(contractAddress: string, limit?: number): Promise<Array<QueryCollectionTopHolderResponse>> {
+    if (isEmpty(contractAddress)) {
+      return missingParamError('contractAddress');
+    }
+
+    if (limit && limit > 100) {
+      return invalidLimitError(100);
+    }
+
+    return nftscanGet<NsObject, Array<QueryCollectionTopHolderResponse>>(
+      this.config,
+      `${NftscanConst.API.evm.statistic.getCollectionTopHolder}${contractAddress}`,
+      { limit: limit || 20 },
+    );
+  }
+
   /**
    * Account overview
    * - This endpoint returns overview statistics for an account address referring to NFTScan Overview({@link https://www.nftscan.com/0xea7a0f1434084b2e99b42f045896e7326fed9dc1}).

diff --git a/src/types/evm/asset/request-params.ts b/src/types/evm/asset/request-params.ts
@@ -140,4 +140,14 @@ export interface QueryAssetsByAttributesParams extends CommonAssetParams {
    * The NFT contract address for the assets
    */
   contract_address: string;
+
+  /**
+   * Can be asc or desc
+   */
+  sort_direction?: SortDirection;
+
+  /**
+   * Note: `rarity_rank` only serve for erc721 NFTs
+   */
+  sort_field: string;
 }
diff --git a/src/types/evm/statistic/response-data.ts b/src/types/evm/statistic/response-data.ts
@@ -418,6 +418,26 @@ export interface QueryCollectionTrendingResponse {
   volume: number;
 }
 
+/**
+ * The response data of EVM API 'getCollectionTopHolder'
+ */
+export interface QueryCollectionTopHolderResponse {
+  /**
+   * The holder
+   */
+  address: string;
+
+  /**
+   * The percentage of the project held by the holder
+   */
+  proportion: string;
+
+  /**
+   * The total number of NFTs held by the holder
+   */
+  value: number;
+}
+
 /**
  * The response data of EVM API 'getAccountOverview'
  */
@@ -442,6 +462,11 @@ export interface QueryAccountOverviewResponse {
    */
   burn_count: number;
 
+  /**
+   * The number of collections for NFT
+   */
+  collection_count: number;
+
   /**
    * The value of operating NFTs gas fee
    */

diff --git a/src/types/nftscan-type.ts b/src/types/nftscan-type.ts
@@ -5,12 +5,14 @@
 export enum EvmChain {
   ETH = 'eth',
   BNB = 'bnb',
-  ARBITRUM = 'arbitrum',
-  MOONBEAM = 'moonbeam',
   POLYGON = 'polygon',
+  ARBITRUM = 'arbitrum',
   OPTIMISM = 'optimism',
-  PLATON = 'platon',
+  ZKSYNC = 'zksync',
+  LINEA = 'linea',
   AVALANCHE = 'avalanche',
+  MOONBEAM = 'moonbeam',
+  PLATON = 'platon',
   CRONOS = 'cronos',
   FANTOM = 'fantom',
   GNOSIS = 'gnosis',

diff --git a/src/util/nftscan.const.ts b/src/util/nftscan.const.ts
@@ -15,6 +15,8 @@ export default class NftscanConst {
     cronos: 'https://cronosapi.nftscan.com/api',
     fantom: 'https://fantomapi.nftscan.com/api',
     gnosis: 'https://gnosisapi.nftscan.com/api',
+    zksync: 'https://zksyncapi.nftscan.com/api',
+    linea: 'https://lineaapi.nftscan.com/api',
   };
 
   /**
@@ -50,6 +52,7 @@ export default class NftscanConst {
         getCollectionRanking: '/v2/statistics/ranking/collection',
         getCollectionTrade: '/v2/statistics/collection/trade/',
         getCollectionTrending: '/v2/statistics/collection/trending/',
+        getCollectionTopHolder: '/v2/statistics/collection/holder/',
         getAccountOverview: '/v2/statistics/overview/',
         getBlueChipStatistics: '/v2/statistics/blue/chip/',
         getMarketplaceRanking: '/v2/statistics/ranking/marketplace',