@mimicry/kaleidoscope

Kaleidoscope Node SDK

Maintained by Mimicry

Kaleidoscope is an NPM package that conveniently aggregates responses from multiple NFT data providers. The intended audience is application developers who wish to integrate fraud-resistant price data into their apps. The main benefit of Kaleidoscope is that it drastically reduces the risks related to price manipulation by closed-source data providers, and data provider down-time.

Supported Data Providers

NFT Collection Data Providers

	Floor	Market Cap	Metadata	Candles	Historic Sales
DIA	✔️	❌	❌	❌	✔️
NFTBank	✔️	❌	❌	❌	❌
NFTGo	✔️	✔️	❌	❌	❌
Reservoir	✔️	❌	✔️	❌	❌
CoinGecko	✔️	❌	✔️	❌	❌
CoinGecko Pro	✔️	❌	✔️	✔️	❌

Supported Chains

	Floor	Market Cap	Metadata	Candles	Historic Sales
Ethereum	✔️	✔️	✔️	✔️	✔️
Polygon	✔️	❌	✔️	✔️	❌
Binance Smart Chain	✔️	❌	✔️	✔️	❌
Arbitrum	✔️	❌	✔️	✔️	❌
Optimism	✔️	❌	✔️	✔️	❌
Klaytn	✔️	❌	❌	✔️	❌
Avalanche	✔️	❌	❌	✔️	❌
Solana	🔜	🔜	🔜	🔜	🔜

Installation

Run yarn add @mimicry/kaleidoscope@latest to install the module.

Setup

The module allows developers to instantiate an instance in a few lines of code. For example:

import { Kaleidoscope } from "@mimicry/kaleidoscope";
import 'dotenv/config';

const config = {
  dataProviders: {
    nonFungibleTokens: {
      dia: process.env.DIA_KEY
    }
  }
};
const kaleidoscope = new Kaleidoscope(config);

Usage

Kaleidoscope provides a number of methods to interact with the providers. See ./example/ for a full example.

Here is a summary of the methods available:

const floorInfo: bigint = await kaleidoscope.nftCollection.getFloor({
    address: '0x4b15a9c28034dC83db40CD810001427d3BD7163D',
});
console.log(floorInfo);

// {
//   currencyInfo: { symbol: 'ETH', name: 'Ethereum', decimals: 18 },
//   amount: { atomic: 510000000000000000n, decimal: 0.51 }
// }

For Contributors

To run TSDX, use:

yarn start

This builds to /dist and runs the project in watch mode so any edits you save inside src causes a rebuild to /dist.

• Use yarn build to do a one-off build.
• Use yarn analyize to fix linting issues, run tests, and check distribution size.
• Use yarn publish to publish to NPM. Note there is a weird quirk where you need to commit and sync the package.json version number at the start of the process, before entering the NPM 2FA code. Otherwise, the version number will be out of sync with the published package.

Adding a New Provider

To add a new provider, you need to do the following:

1. Clone a worker of the same type as the provider you wish to add. For example, if you wish to add a new NFT Collection Data Provider, clone ./src/lib/kaleidoscope/vendors/dataProviders/nftCollection/workers/NftBank.ts.
2. Rename the cloned file and Class name to match the name of the provider you wish to add.
3. Update the docs comment and the apiHost at the top of the file.
4. Update the comments above each function to match the provider's API.
5. Update the uri and options within each method to match the provider's API.
6. Update the response parsing logic within each method to match the provider's API.
7. Update the getBlockchain method as needed to match the provider's API.
8. Update the getName() function to return the human-readable name of the provider.
9. Add the provider's API_KEY to ./example/.env.example.
10. Add the provider's API_KEY to .example/index.js, along with a new key
11. Add the new key to the addDataProvider method in the appropriate Factory class.
12. Test the provider by running node index.js in the ./example directory.
13. Update the README.md to include the new provider in the list of supported providers.

Implemented Features

• [x] support Metric: Floor Price
• [x] support Metric: Market Cap
• [x] support Consensus Filter: None
• [x] support Consensus Filter: Mean Absolute Deviation
• [x] support Consensus Method: Median
• [x] support Consensus Method: Mean
• [x] support Consensus Method: Random
• [x] APIs called with exponential-backoff retry strategy
• [x] support for providers failing to return a response
• [x] support getCandles() method with multiple timeframes
• [x] support getHistoricSales() with start and end timestamps

Backlog

Features

• [ ] support Solana via collection title search
• [ ] support normalizing all output to USD
• [ ] support getPrice for fungible tokens

Providers

• [ ] support Provider: NFTScan
• [ ] support Provider: HelloMoon
• [ ] support Provider: Center
• [ ] support Provider: Zash
• [ ] support Provider: Gallop
• [ ] support Provider: Nefertiti