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 | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: |
| NFTBank | :heavy_check_mark: | :x: | :x: | :x: | :x: |
| NFTGo | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | :x: |
| Reservoir | :heavy_check_mark: | :x: | :heavy_check_mark: | :x: | :x: |
| CoinGecko | :heavy_check_mark: | :x: | :heavy_check_mark: | :x: | :x: |
| CoinGecko Pro | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
### Supported Chains
| | `Floor` | `Market Cap` | `Metadata` | `Candles` | `Historic Sales` |
|---------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|
| Ethereum | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| Polygon | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| Binance Smart Chain | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| Arbitrum | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| Optimism | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| Klaytn | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | :x: |
| Avalanche | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | :x: |
| Solana | :soon: | :soon: | :soon: | :soon: | :soon: |
## 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:
```typescript
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/`](https://github.com/Mimicry-Protocol/kaleidoscope/blob/main/example/) for a full example.
Here is a summary of the methods available:
```typescript
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:
```bash
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
