From d95c691188bfe9bd46e032eed7af937551583954 Mon Sep 17 00:00:00 2001 From: nsmle Date: Fri, 21 Feb 2025 05:52:09 +0700 Subject: [PATCH] feat: decentralized exchange --- README.md | 140 ++- package.json | 2 +- src/enums/cmc-error-code.enum.ts | 2 +- src/index.ts | 2 + src/repositories/dex.repository.ts | 591 +++++++++- src/responses/dex.response.ts | 1646 ++++++++++++++++++++++++++++ src/types/dex.option.ts | 600 ++++++++++ 7 files changed, 2966 insertions(+), 17 deletions(-) create mode 100644 src/responses/dex.response.ts create mode 100644 src/types/dex.option.ts diff --git a/README.md b/README.md index 3479030..319ce70 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # CoinMarketCap NodeJS Api wrapper -The **cmc-api** is an generic api wrapper for [CoinMarketCap](https://coinmarketcap.com). +The **[cmc-api](https://www.npmjs.com/package/cmc-api)** is an generic api wrapper for [CoinMarketCap](https://coinmarketcap.com). Supports endpoints cryptocurrency, exchanges (CEX), decentralized exchange (DEX), global metrics, community content and trends, tools and others. > [!IMPORTANT] @@ -63,7 +63,7 @@ const cmc = new CoinMarketCapApi(CMC_APIKEY); ### Cryptocurrency -#### CoinMarketCap ID map +#### Cryptocurrency ID Map ```typescript const crypto = await cmc.crypto.list('active', 'id', 10, 1, ['BTC', 'ETH']); const btc = crypto.find((crypto): boolean => crypto.symbol === 'BTC'); @@ -92,21 +92,21 @@ const crypto = await cmc.crypto.metadata<'1027'>({ contract: '0xeeeeeeeeeeeeeeee console.log(crypto[1027]); // Ethereum ``` -#### Latest Listings +#### Listings Latest ###### get cryptocurrency latest listings ```typescript const crypto = await cmc.crypto.listing<'USD' | 'EUR'>(10, 1, 'all', 'market_cap', 'desc', 'all', undefined, ['USD', 'EUR']); console.log(crypto.at(0), crypto.at(0).quote.USD, crypto.at(0).quote.EUR); ``` -#### New Listings +#### Listings New ###### get cryptocurrency new listings and convert to BTC and ETH ```typescript const crypto = await cmc.crypto.listingNew<'BTC' | 'ETH'>(10, 1, 'desc', ['BTC', 'ETH']); console.log(crypto, crypto.at(0).quote.BTC, crypto.at(0).quote.ETH); ``` -#### Historical Listings +#### Listings Historical ###### get cryptocurrency historical listings ```typescript const date = new Date() @@ -114,14 +114,14 @@ const crypto = await cmc.crypto.listingHistory<'BTC' | 'ETH' | 'USD'>(date, 10, console.log(crypto, crypto.at(0).quote.BTC, crypto.at(0).quote.ETH, crypto.at(0).quote.USD); ``` -#### Latest Quotes +#### Quotes Latest ###### get cryptocurrency latest quotes by slug coin/token ```typescript const quotes = await cmc.crypto.quotes<'bitcoin' | 'ethereum', 'USD' | 'EUR'>({ slug: ['bitcoin', 'ethereum'] }, ['USD', 'EUR']); console.log({ btc: quotes.bitcoin, eth: quotes.ethereum, btcUsd: quotes.bitcoin.quote.USD, ethEur: quotes.ethereum.quote.EUR }); ``` -#### Historical Quotes +#### Quotes Historical ###### get btc and eth historical quotes in range '2024-12-01' - '2025-01-01' ```typescript const start = new Date('2024-12-01T00:00:00Z'); @@ -133,14 +133,14 @@ console.log({ btcQuotes: btc.quotes, ethQuotes: eth.quotes }); console.log({ btcQuoteFirst: btc.quotes?.at(0)?.quote, ethQuoteFirst: eth.quotes?.at(0)?.quote }); ``` -#### Latest Market Pairs +#### Market Pairs Latest ###### get ethereum market pairs ```typescript const ethereum = await cmc.crypto.marketPairs<'USD' | 'BTC'>({ slug: 'ethereum' }, { symbol: ['USD', 'BTC'] }); console.log({ ethMarketPairs: ethereum.market_pairs }); ``` -#### Latest OHLCV +#### OHLCV Latest ###### get latest btc and eth ohlcv and convert to usd and eur ```typescript const ohlcv = await cmc.crypto.ohlcv<'1' | '1027', 'USD' | 'EUR'>({ id: [1, 1027] }, ['USD', 'EUR']); @@ -151,7 +151,7 @@ console.log({ btcOhlcv, ethOhlcv }); console.log({ btcOhlcvUsd: btcOhlcv.quote.USD, ethOhlcvEur: ethOhlcv.quote.EUR }); ``` -#### Historical OHLCV +#### OHLCV Historical ###### get ohclv history of btc and eth in range date '2024-12-01' - '2025-01-01' ```typescript const start = new Date('2024-12-01T00:00:00Z'); @@ -261,7 +261,7 @@ for (const trending of trendings) { ### Exchanges _(CEX)_ -#### ID Map +#### Exchanges ID Map ###### get a list of all active exchanges ```typescript import type { CexIdMapResponses } from "cmc-api"; @@ -320,7 +320,7 @@ const marketPairs = await cmc.cex.marketPairs<"binance">({ slug: "binance" }); console.log(marketPairs.binance); ``` -#### Latest Quotes +#### Quotes Latest ###### get latest binance quotes by id for BTC and ETH ```typescript const quotes = await cmc.cex.quotes<"3673", "BTC" | "ETH">({ id: 3673 }, ["BTC", "ETH"]); @@ -332,7 +332,7 @@ const quotes = await cmc.cex.quotes<"binance", "BTC" | "ETH">({ slug: "binance" console.log(quotes.binance.quote.BTC.volume_24h, quotes.binance.quote.ETH.volume_24h); ``` -#### Historical Quotes +#### Quotes Historical ###### get binance historical quotes by exchange slug in interval 4h and convert to BTC and ETH ```typescript const start = new Date("2024-12-01T00:00:00Z"); @@ -350,7 +350,119 @@ for (const binanceQuote of quotesHistorical.binance.quotes) { ``` ### Decentralized Exchange _(DEX)_ -**(_soon_)** + +#### DEX ID Map +###### get 500 list of dex networks +```typescript +import type { DexIdMapResponse } from "cmc-api"; +const dexes = await cmc.dex.list(500, 1, "id", "desc", ["alternativeName", "cryptocurrencyId", "cryptocurrenySlug"]); +for (const dex of dexes) { + console.log(dex.id, dex.name, dex.network_slug); +} +``` + +#### Metadata +###### get metadata for a list of DEX +```typescript +import type { DexMetadataResponse } from "cmc-api"; +const metadata = await cmc.dex.metadata([51, 60, 68, 93, 118], ["urls", "logo"]); +console.log(metadata); +``` + +#### Listings +###### get 10 list swap of DEX listings and sorted by volume_24h +```typescript +import type { DexListingQuote, DexListingResponse } from "cmc-api"; +const listings = await cmc.dex.listing("swap", 10, 1, "volume_24h"); +for (const listing of listings) { + console.log(listing); +} +``` + +#### Quotes +###### get quotes of "WETH/USDT" by contract address in ethereum network by id +```typescript +import type { DexQuote, DexSecurityScan } from "cmc-api"; +const quotes = await cmc.dex.quotes("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // "WETH/USDT" +console.log(quotes); +``` +###### get quotes of "SOL/WETH" by contract address in ethereum network by slug +```typescript +import type { DexQuote, DexSecurityScan } from "cmc-api"; +const quotes = await cmc.dex.quotes("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // "SOL/WETH" +console.log(quotes); +``` + +#### Trades +###### get latest trades of "WETH/USDT" by contract address in ethereum network by id +```typescript +const latestTrades = await cmc.dex.trades("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // "WETH/USDT" +for (const token of latestTrades) { + for (const trade of token.trades) console.log(trade); +} +``` +###### get latest trades of "SOL/WETH" by contract address in ethereum network by slug +```typescript +const latestTrades = await cmc.dex.trades("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // "SOL/WETH" +for (const token of latestTrades) { + for (const trade of token.trades) console.log(trade); +} +``` + +#### Pairs Listings +###### importing type of dex pairs response +```typescript +import type { DexPairQuote, DexSecurityScan } from "cmc-api"; +``` +###### get list of all active dex spot pairs by network id +```typescript +const pairs = await cmc.dex.pairs({ id: 1 }); // networkId '1' == slug 'ethereum' +for (const pair of pairs) console.log(pair); +``` +###### get list of all active dex spot pairs by network slug +```typescript +const pairs = await cmc.dex.pairs({ slug: "ethereum" }); // ethereum +for (const pair of pairs) console.log(pair); +``` +###### get list of all active dex spot pairs by network id and dex id +```typescript +const pairs = await cmc.dex.pairs({ id: 1 }, { id: 1348 }); // networkId 1 = ethereum | dexId 1348 = "uniswap-v3" +for (const pair of pairs) console.log(pair); +``` +###### get list of all active dex spot pairs by network slug and dex slug +```typescript +const pairs = await cmc.dex.pairs({ slug: "ethereum" }, { slug: "uniswap-v3" }); // ethereum | uniswap-v3 +for (const pair of pairs) console.log(pair); +``` + +#### OHLCV Latest +###### get the latest OHLCV data by contract address and network id +```typescript +import type { DexOhlcvQuote, DexSecurityScan } from "cmc-api"; +const ohlcvs = await cmc.dex.ohlcv("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // "WETH/USDT" +for (const ohlcv of ohlcvs) console.log(ohlcv); +``` +###### get the latest OHLCV data by contract address and network slug +```typescript +import type { DexOhlcvQuote, DexSecurityScan } from "cmc-api"; +const ohlcvs = await cmc.dex.ohlcv("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // "SOL/WETH" +for (const ohlcv of ohlcvs) console.log(ohlcv); +``` + +#### OHLCV Historical + +###### get historical OHLCV data on daily interval and period by contract address and network id +```typescript +import type { DexOhlcvHistoricalQuotes, DexSecurityScan } from "cmc-api"; +const ohlcvsHistories = await cmc.dex.ohlcvHistory("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // USDT/WETH in uniswap-v3 DEX +for (const ohlcvHistory of ohlcvsHistories) console.log(ohlcvHistory); +``` +###### get historical OHLCV data on daily interval and period by contract address and network slug +```typescript +import type { DexOhlcvHistoricalQuotes, DexSecurityScan } from "cmc-api"; +const ohlcvsHistories = await cmc.dex.ohlcvHistory("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // SOL/WETH in uniswap-v3 DEX +for (const ohlcvHistory of ohlcvsHistories) console.log(ohlcvHistory); +``` ### Global Metrics **(_soon_)** diff --git a/package.json b/package.json index 5d0d48e..d0ca90b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "cmc-api", - "version": "0.6.5", + "version": "0.7.0", "description": "CoinMarketCap RESTful API Wrapper", "keywords": [ "coinmarketcap", diff --git a/src/enums/cmc-error-code.enum.ts b/src/enums/cmc-error-code.enum.ts index b8e3298..24e5a7e 100644 --- a/src/enums/cmc-error-code.enum.ts +++ b/src/enums/cmc-error-code.enum.ts @@ -12,7 +12,7 @@ export enum CmcErrorCode { /** * Your API Key must be activated. - * Please go to {@link pro.coinmarketcap.com/account/plan | account Plan} + * Please go to {@link https://pro.coinmarketcap.com/account/plan | CoinMarketCap Account Plan} */ ApikeyPlanRequiresPayment = 1003, diff --git a/src/index.ts b/src/index.ts index 667df2d..2373bb2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -5,6 +5,7 @@ export * from "@core/api"; export * from "@option/cex.option"; export * from "@option/common.type"; export * from "@option/crypto.options"; +export * from "@option/dex.option"; export * from "@repository/cex.repository"; export * from "@repository/community.repository"; @@ -16,6 +17,7 @@ export * from "@repository/misc.repository"; export * from "@response/cex.response"; export * from "@response/common.response"; export * from "@response/crypto.response"; +export * from "@response/dex.response"; export * from "@response/status.response"; export * from "@error/cmc-apikey-disabled.error"; diff --git a/src/repositories/dex.repository.ts b/src/repositories/dex.repository.ts index a85afaa..a77b172 100644 --- a/src/repositories/dex.repository.ts +++ b/src/repositories/dex.repository.ts @@ -1,3 +1,592 @@ +import endpoints from "@core/endpoints"; import { Repository } from "@core/repository"; +import { dateToUnix } from "@util/date.util"; +import { isNumeric } from "@util/type.util"; +import type { Convert, SortDir } from "@option/common.type"; +import type { + AuxiliaryDexList, + AuxiliaryDexListing, + AuxiliaryDexMetadata, + AuxiliaryDexOhlcv, + AuxiliaryDexOhlcvHistorical, + AuxiliaryDexPairs, + AuxiliaryDexQuotes, + DexBaseAsset, + DexId, + DexListingSort, + DexListingType, + DexListSort, + DexNetwork, + DexOhlcvHistoricalInterval, + DexOhlcvHistoricalTimePeriod, + DexPairsFilter, + DexPairsSort, + DexQuoteAsset, +} from "@option/dex.option"; +import type { + DexIdMapResponse, + DexListingQuote, + DexListingResponse, + DexMetadataResponse, + DexOhlcvHistoricalQuotes, + DexOhlcvHistoricalResponse, + DexOhlcvQuote, + DexOhlcvResponse, + DexPairQuote, + DexPairsResponse, + DexQuote, + DexQuotesResponse, + DexSecurityScan, + DexTrade, + DexTradeQuote, + DexTradesResponse, +} from "@response/dex.response"; -export class DexRepository extends Repository {} +export class DexRepository extends Repository { + /** @private Endpoints are used to interact with CoinMarketCap Decentralized Exchange APIs */ + private endpoints = endpoints.dex; + + /** + * A list of all networks to unique CoinMarketCap ids. \ + * *Recommend utilizing CMC ID instead of network symbols to securely identify networks with CoinMarketCap other endpoints.* \ + * *Each network returned includes typical identifiers such as name, symbol, and token_address for flexible mapping to id.* + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getNetworks | DEX ID Map} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get 500 list of dex networks + * ```typescript + * import type { DexIdMapResponse } from "cmc-api"; + * const dexes = await cmc.dex.list(500, 1, "id", "desc", ["alternativeName", "cryptocurrencyId", "cryptocurrenySlug"]); + * for (const dex of dexes) console.log(dex.id, dex.name, dex.network_slug); + * ``` + * + * @template TResponse - The expected response type. default an array of `DexIdMap` + * + * @param {number} [limit] - Offset the start of the paginated list of items. + * @param {number} [offset] - Determine the maximum number of results. + * @param {DexListSort} [sort="id"] - Field to sort the list of networks by. default `"id"` + * @param {SortDir} [sortDir="desc"] - The direction in which to sort the results. default `"desc"` + * @param {AuxiliaryDexList} [aux=[]] - Additional auxiliary fields to include in the response. + * + * @returns {Promise} A promise that resolves to the response of type TResponse. + */ + public async list( + limit?: number, + offset?: number, + sort: DexListSort = "id", + sortDir: SortDir = "desc", + aux: AuxiliaryDexList = [], + ): Promise { + return await this.cmc.client.req(this.endpoints.map, { + limit: limit, + offset: offset, + sort: sort, + sort_dir: sortDir, + aux: aux, + }); + } + + /** + * Static metadata for one or more decentralised exchanges. \ + * *This information includes details like launch date, logo, official website URL, social links, and market fee documentation URL.* + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getListingsInfo | DEX Metadata} \ + * {@link DexMetadataResponse} + * {@link DexMetadata} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get metadata for a list of DEX + * ```typescript + * import type { DexMetadataResponse } from "cmc-api"; + * const metadata = await cmc.dex.metadata([51, 60, 68, 93, 118], ["urls", "logo"]); + * console.log(metadata); + * ``` + * + * @template TResponse - The expected response type, defaults array of `DexMetadata`. + * + * @param {string | number | (string | number)[]} id - The ID(s) of the CoinMarketCap DEX to fetch metadata for. + * @param {AuxiliaryDexMetadata} [aux] - Optional auxiliary metadata fields to include. + * + * @returns {Promise} A promise that resolves to the metadata of the specified DEX. + */ + public async metadata( + id: string | number | (string | number)[], + aux?: AuxiliaryDexMetadata, + ): Promise { + return await this.cmc.client.req(this.endpoints.metadata, { id: id, aux: aux }); + } + + /** + * A paginated list of all decentralised cryptocurrency exchanges including the latest aggregate market data for each exchange. \ + * *Use the `convert` option to return market values in multiple fiat and cryptocurrency conversions in the same call.* + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getLatestListings | DEX Listings Latest} \ + * {@link DexListingQuote} \ + * {@link DexListingResponse} \ + * {@link DexListing} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get 10 list swap (in page 1) of DEX listings and sorted by volume_24h + * ```typescript + * import type { DexListingQuote, DexListingResponse } from "cmc-api"; + * const listings = await cmc.dex.listing("swap", 10, 1, "volume_24h"); + * for (const listing of listings) console.log(listing); + * ``` + * + * @template TQuote - The type of the quote object. Defaults to `DexListingQuote`. + * @template TResponse - The type of the response object. Defaults to `DexListingResponse`. + * + * @param {DexListingType} [type="all"] - The type of DEX listings to fetch. Defaults to "all". + * @param {number} [limit] - The maximum number of listings to return. + * @param {number} [offset] - Offset the start (1-based index) of the paginated list of items to return. + * @param {DexListingSort} [sort="volume_24h"] - The field by which to sort the listings. Defaults to "volume_24h". + * @param {SortDir} [sortDir="desc"] - The direction in which to sort the listings. Defaults to "desc". + * @param {Convert} [convert] - The currency to convert the listings to. + * @param {AuxiliaryDexListing} [aux] - Additional auxiliary field to include in the listings. + * + * @returns {Promise} A promise that resolves to the response object containing the DEX listings. + */ + public async listing>( + type: DexListingType = "all", + limit?: number, + offset?: number, + sort: DexListingSort = "volume_24h", + sortDir: SortDir = "desc", + convert?: Convert, + aux?: AuxiliaryDexListing, + ): Promise { + return await this.cmc.client.req(this.endpoints.listings, { + ...(isNumeric(convert) ? { convert_id: convert } : { convert }), + type: type, + limit: limit, + offset: offset, + sort: sort, + sort_dir: sortDir, + aux: aux, + }); + } + + /** + * The latest market quote for 1 or more spot pairs. \ + * *Use the `convert` option to return market values in multiple fiat and cryptocurrency conversions in the same call.* + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getLatestPairsQuotes | DEX Quotes Latest} \ + * {@link DexQuote} \ + * {@link DexSecurityScan} \ + * {@link DexQuotesResponse} \ + * {@link DexQuotes} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get quotes of "WETH/USDT" by contract address in ethereum network by id + * ```typescript + * import type { DexQuote, DexSecurityScan } from "cmc-api"; + * const quotes = await cmc.dex.quotes("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // "WETH/USDT" + * console.log(quotes); + * ``` + * + * @example get quotes of "SOL/WETH" by contract address in ethereum network by slug + * ```typescript + * import type { DexQuote, DexSecurityScan } from "cmc-api"; + * const quotes = await cmc.dex.quotes("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // "SOL/WETH" + * console.log(quotes); + * ``` + * + * @template TQuote - The type of the quote object. Defaults to `DexQuote`. + * @template TSecurityScan - The type of the security scan object. Defaults to `DexSecurityScan`. + * @template TResponse - The type of the response object. Defaults to `DexQuotesResponse`. + * + * @param {string | string[]} contract - The contract address or addresses to fetch quotes for. + * @param {DexNetwork} network - The network on which the contract resides. + * @param {Convert} [convert] - The currency to convert the quotes to. + * @param {boolean} [reverseOrder=true] - Whether to reverse the order of the quotes. + * @param {boolean} [skipInvalid=false] - Whether to skip invalid quotes. + * @param {AuxiliaryDexQuotes} [aux] - Auxiliary parameters for the quotes request. + * + * @returns {Promise} A promise that resolves to the response containing the quotes. + */ + public async quotes< + TQuote extends object = DexQuote, + TSecurityScan extends object = DexSecurityScan, + TResponse = DexQuotesResponse, + >( + contract: string | string[], + network: DexNetwork, + convert?: Convert, + reverseOrder: boolean = true, + skipInvalid: boolean = false, + aux?: AuxiliaryDexQuotes, + ): Promise { + return await this.cmc.client.req(this.endpoints.quotes, { + ...(network?.id && { network_id: network.id }), + ...(network?.slug && { network_slug: network.slug }), + ...(isNumeric(convert) ? { convert_id: convert } : { convert }), + contract_address: contract, + reverse_order: reverseOrder, + skip_invalid: skipInvalid, + aux: aux, + }); + } + + /** + * The latest trades. Returns up to the latest 100 trades for 1 spot pair. \ + * *Use the `convert` option to return market values in multiple fiat and cryptocurrency conversions in the same call.* + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getPairLatestTrades | DEX Trades Latest} \ + * {@link DexTrade} \ + * {@link DexTradeQuote} \ + * {@link DexSecurityScan} \ + * {@link DexTradesResponse} \ + * {@link DexTrades} \ + * {@link DexNetwork} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get latest trades of "WETH/USDT" by contract address in ethereum network by id + * ```typescript + * const latestTrades = await cmc.dex.trades("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // "WETH/USDT" + * for (const token of latestTrades) { + * for (const trade of token.trades) console.log(trade); + * } + * ``` + * @example get latest trades of "SOL/WETH" by contract address in ethereum network by slug + * ```typescript + * const latestTrades = await cmc.dex.trades("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // "SOL/WETH" + * for (const token of latestTrades) { + * for (const trade of token.trades) console.log(trade); + * } + * ``` + * + * @template TQuote - The type of the quote object, defaults to `DexTradeQuote`. + * @template TTrade - The type of the trade object, defaults to `DexTrade`. + * @template TSecurityScan - The type of the security scan object, defaults to `DexSecurityScan`. + * @template TResponse - The type of the response object, defaults to `DexTradesResponse`. + * + * @param {string | string[]} contract - The contract address or an array of contract addresses. + * @param {DexNetwork} network - One CoinMarketCap cryptocurrency network id/slug. + * @param {Convert} [convert] - The currency to convert the trades to. + * @param {boolean} [reverseOrder=true] - Whether to reverse the order of the trades. + * @param {boolean} [skipInvalid=false] - Whether to skip invalid trades. + * @param {AuxiliaryDexQuotes} [aux] - Auxiliary fields for the DEX quotes to included in return. + * + * @returns {Promise} - A promise that resolves to the response containing the trades. + */ + public async trades< + TQuote extends object = DexTradeQuote, + TTrade extends object = DexTrade, + TSecurityScan extends object = DexSecurityScan, + TResponse = DexTradesResponse, + >( + contract: string | string[], + network: DexNetwork, + convert?: Convert, + reverseOrder: boolean = true, + skipInvalid: boolean = false, + aux?: AuxiliaryDexQuotes, + ): Promise { + return await this.cmc.client.req(this.endpoints.trades, { + ...(network?.id && { network_id: network.id }), + ...(network?.slug && { network_slug: network.slug }), + ...(isNumeric(convert) ? { convert_id: convert } : { convert }), + contract_address: contract, + reverse_order: reverseOrder, + skip_invalid: skipInvalid, + aux: aux, + }); + } + + /** + * A paginated list of all active dex spot pairs with latest market data. \ + * *Use the `convert` option to return market values in multiple fiat and cryptocurrency conversions in the same call.* + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getSpotPairsLatest | DEX Pairs Listings Latest} \ + * {@link DexPairQuote} \ + * {@link DexSecurityScan} \ + * {@link DexPairsResponse} \ + * {@link DexPairs} \ + * {@link DexNetwork} \ + * {@link DexBaseAsset} \ + * {@link DexQuoteAsset} \ + * {@link DexPairsFilter} \ + * {@link DexPairsSort} \ + * {@link AuxiliaryDexPairs} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get list of all active dex spot pairs by network id + * ```typescript + * import type { DexPairQuote, DexSecurityScan } from "cmc-api"; + * const pairs = await cmc.dex.pairs({ id: 1 }); // networkId '1' == slug 'ethereum' + * for (const pair of pairs) console.log(pair); + * ``` + * + * @example get list of all active dex spot pairs by network slug + * ```typescript + * import type { DexPairQuote, DexSecurityScan } from "cmc-api"; + * const pairs = await cmc.dex.pairs({ slug: "ethereum" }); + * for (const pair of pairs) console.log(pair); + * ``` + * + * @example get list of all active dex spot pairs by network id and dex id + * ```typescript + * import type { DexPairQuote, DexSecurityScan } from "cmc-api"; + * const pairs = await cmc.dex.pairs({ id: 1 }, { id: 1348 }); // networkId 1 = ethereum | dexId 1348 = "uniswap-v3" + * for (const pair of pairs) console.log(pair); + * ``` + * + * @example get list of all active dex spot pairs by network slug and dex slug + * ```typescript + * import type { DexPairQuote, DexSecurityScan } from "cmc-api"; + * const pairs = await cmc.dex.pairs({ slug: "ethereum" }, { slug: "uniswap-v3" }); // ethereum | uniswap-v3 + * for (const pair of pairs) console.log(pair); + * ``` + * + * @template TQuote - The type for the quote object, defaults to `DexPairQuote`. + * @template TSecurityScan - The type for the security scan object, defaults to `DexSecurityScan`. + * @template TResponse - The type for the response, defaults to `DexPairsResponse`. + * + * @param {DexNetwork} network - The network ids/slugs. + * @param {DexId} [id] - The DEX ids/slugs. + * @param {DexBaseAsset} [baseAsset] - The base asset `id`, `ucid`, `symbol`, or `contract`. + * @param {DexQuoteAsset} [quoteAsset] - The quote asset `id`, `ucid`, `symbol`, or `contract`. + * @param {DexPairsFilter} [filters] - The filters to apply to the pairs data. + * @param {DexPairsSort} [sort="volume_24h"] - The sorting criteria for the pairs data. + * @param {SortDir} [sortDir="desc"] - The sorting direction, either `"asc"` or `"desc"`. + * @param {AuxiliaryDexPairs} [aux] - Auxiliary data for the pairs request. + * + * @returns {Promise} A promise that resolves to the pairs data response. + */ + public async pairs< + TQuote extends object = DexPairQuote, + TSecurityScan extends object = DexSecurityScan, + TResponse = DexPairsResponse, + >( + network: DexNetwork, + id?: DexId, + baseAsset?: DexBaseAsset, + quoteAsset?: DexQuoteAsset, + filters?: DexPairsFilter, + sort: DexPairsSort = "volume_24h", + sortDir: SortDir = "desc", + aux?: AuxiliaryDexPairs, + ): Promise { + return await this.cmc.client.req(this.endpoints.pairs, { + ...(network?.id && { network_id: network.id }), + ...(network?.slug && { network_slug: network.slug }), + ...(id?.id && { dex_id: id.id }), + ...(id?.slug && { dex_slug: id.slug }), + ...(baseAsset?.id && { base_asset_id: baseAsset.id }), + ...(baseAsset?.symbol && { base_asset_symbol: baseAsset.symbol }), + ...(baseAsset?.ucid && { base_asset_ucid: baseAsset.ucid }), + ...(baseAsset?.contract && { base_asset_contract_address: baseAsset.contract }), + ...(quoteAsset?.id && { quote_asset_id: quoteAsset.id }), + ...(quoteAsset?.symbol && { quote_asset_symbol: quoteAsset.symbol }), + ...(quoteAsset?.ucid && { quote_asset_ucid: quoteAsset.ucid }), + ...(quoteAsset?.contract && { quote_asset_contract_address: quoteAsset.contract }), + limit: filters?.limit, + scroll_id: filters?.scrollId, + liquidity_min: filters?.liquidityMin, + liquidity_max: filters?.liquidityMax, + volume_24h_min: filters?.volume24hMin, + volume_24h_max: filters?.volume24hMax, + no_of_transactions_24h_min: filters?.noOfTransactions24hMin, + no_of_transactions_24h_max: filters?.noOfTransactions24hMax, + percent_change_24h_min: filters?.percentChange24hMin, + percent_change_24h_max: filters?.percentChange24hMax, + sort: sort, + sort_dir: sortDir, + aux: aux, + }); + } + + /** + * The latest OHLCV (Open, High, Low, Close, Volume) market values for one or more spot pairs for the current UTC day. \ + * *Since the current UTC day is still active these values are updated frequently.* + * *You can find the final calculated OHLCV values for the last completed UTC day along with all historic days using {@link DexRepository.ohlcvHistory}.* + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getPairsLatestOHLCV | DEX OHLCV Latest} \ + * {@link DexRepository.ohlcvHistory} \ + * {@link DexOhlcvQuote} \ + * {@link DexSecurityScan} \ + * {@link DexOhlcvResponse} \ + * {@link DexOhlcv} \ + * {@link DexNetwork} \ + * {@link Convert} \ + * {@link AuxiliaryDexOhlcv} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get the latest OHLCV data by contract address and network id + * ```typescript + * import type { DexOhlcvQuote, DexSecurityScan } from "cmc-api"; + * const ohlcvs = await cmc.dex.ohlcv("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // "WETH/USDT" + * for (const ohlcv of ohlcvs) console.log(ohlcv); + * ``` + * @example get the latest OHLCV data by contract address and network slug + * ```typescript + * import type { DexOhlcvQuote, DexSecurityScan } from "cmc-api"; + * const ohlcvs = await cmc.dex.ohlcv("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // "SOL/WETH" + * for (const ohlcv of ohlcvs) console.log(ohlcv); + * ``` + * + * @template TQuote - The type for the quote object, defaults to `DexOhlcvQuote`. + * @template TSecurityScan - The type for the security scan object, defaults to `DexSecurityScan`. + * @template TResponse - The type for the response, defaults to `DexOhlcvResponse`. + * + * @param {string | string[]} contract - The contract address or addresses to get the OHLCV data for. + * @param {DexNetwork} network - The network ids/slug on which the contract(s) reside. + * @param {Convert} [convert] - The currency to convert the OHLCV data to. + * @param {boolean} [reverseOrder=true] - Whether to reverse the order of the returned data. + * @param {boolean} [skipInvalid=false] - Whether to skip invalid data points. + * @param {AuxiliaryDexOhlcv} [aux] - Optional auxiliary data for the OHLCV request. + * + * @returns {Promise} - A promise that resolves to the OHLCV data response. + */ + public async ohlcv< + TQuote extends object = DexOhlcvQuote, + TSecurityScan extends object = DexSecurityScan, + TResponse = DexOhlcvResponse, + >( + contract: string | string[], + network: DexNetwork, + convert?: Convert, + reverseOrder: boolean = true, + skipInvalid: boolean = false, + aux?: AuxiliaryDexOhlcv, + ): Promise { + return await this.cmc.client.req(this.endpoints.ohlcv, { + ...(network?.id && { network_id: network.id }), + ...(network?.slug && { network_slug: network.slug }), + ...(isNumeric(convert) ? { convert_id: convert } : { convert }), + contract_address: contract, + reverse_order: reverseOrder, + skip_invalid: skipInvalid, + aux: aux, + }); + } + + /** + * The historical OHLCV (Open, High, Low, Close, Volume) data along with market cap for any spot pairs using time interval parameters. + * + * @see + * {@link https://pro.coinmarketcap.com/api/v1#operation/getPairHistoricalOHLCV | DEX OHLCV Historical} \ + * {@link DexOhlcvHistorical} \ + * {@link DexOhlcvHistoricalResponse} \ + * {@link DexOhlcvHistoricalQuotes} \ + * {@link DexSecurityScan} \ + * {@link DexNetwork} \ + * {@link Convert} \ + * {@link DexOhlcvHistoricalTimePeriod} \ + * {@link DexOhlcvHistoricalInterval} \ + * {@link AuxiliaryDexOhlcvHistorical} + * + * @example import the CoinMarketCapApi class and create a new instance + * ```typescript + * import { CoinMarketCapApi } from "cmc-api"; + * const cmc = new CoinMarketCapApi("YOUR_COINMARKETCAP_APIKEY"); + * ``` + * + * @example get historical OHLCV data on daily interval and period by contract address and network id + * ```typescript + * import type { DexOhlcvHistoricalQuotes, DexSecurityScan } from "cmc-api"; + * const ohlcvsHistories = await cmc.dex.ohlcvHistory("0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b", { id: 1 }); // USDT/WETH in uniswap-v3 DEX + * for (const ohlcvHistory of ohlcvsHistories) console.log(ohlcvHistory); + * ``` + * + * @example get historical OHLCV data on daily interval and period by contract address and network slug + * ```typescript + * import type { DexOhlcvHistoricalQuotes, DexSecurityScan } from "cmc-api"; + * const ohlcvsHistories = await cmc.dex.ohlcvHistory("0x127452f3f9cdc0389b0bf59ce6131aa3bd763598", { slug: "ethereum" }); // SOL/WETH in uniswap-v3 DEX + * for (const ohlcvHistory of ohlcvsHistories) console.log(ohlcvHistory); + * ``` + * + * @template TQuotes - The type for the quotes object. Defaults to `DexOhlcvHistoricalQuotes`. + * @template TSecurityScan - The type for the security scan object. Defaults to `DexSecurityScan`. + * @template TResponse - The type for the response object. Defaults to `DexOhlcvHistoricalResponse`. + * + * @param {string | string[]} contract - The contract address or an array of contract addresses. + * @param {DexNetwork} network - The network ids/slug on which the contract resides. + * @param {Date} [timeStart] - The start time for the historical data. + * @param {Date} [timeEnd] - The end time for the historical data. + * @param {DexOhlcvHistoricalTimePeriod} [timePeriod="daily"] - The time period for the historical data (e.g., `"daily"`, `"weekly"`). + * @param {number} [count] - The number of data points to fetch. The default is `10 items`. The current query limit is `500 items` + * @param {DexOhlcvHistoricalInterval} [interval="daily"] - The interval for the historical data (e.g., `"daily"`, `"hourly"`). + * @param {Convert} [convert] - The currency to convert the data to. + * @param {boolean} [reverseOrder=true] - Whether to reverse the order of the data points. + * @param {boolean} [skipInvalid=false] - Whether to skip invalid data points. + * @param {AuxiliaryDexOhlcvHistorical} [aux] - Auxiliary data for the historical request. + * + * @returns {Promise} A promise that resolves to the historical OHLCV data. + */ + public async ohlcvHistory< + TQuotes extends object = DexOhlcvHistoricalQuotes, + TSecurityScan extends object = DexSecurityScan, + TResponse = DexOhlcvHistoricalResponse, + >( + contract: string | string[], + network: DexNetwork, + timeStart?: Date, + timeEnd?: Date, + timePeriod: DexOhlcvHistoricalTimePeriod = "daily", + count?: number, + interval: DexOhlcvHistoricalInterval = "daily", + convert?: Convert, + reverseOrder: boolean = true, + skipInvalid: boolean = false, + aux?: AuxiliaryDexOhlcvHistorical, + ): Promise { + return await this.cmc.client.req(this.endpoints.ohlcvHistorical, { + ...(network?.id && { network_id: network.id }), + ...(network?.slug && { network_slug: network.slug }), + ...(isNumeric(convert) ? { convert_id: convert } : { convert }), + contract_address: contract, + time_start: dateToUnix(timeStart), + time_end: dateToUnix(timeEnd), + time_period: timePeriod, + count: count, + interval: interval, + reverse_order: reverseOrder, + skip_invalid: skipInvalid, + aux: aux, + }); + } +} diff --git a/src/responses/dex.response.ts b/src/responses/dex.response.ts new file mode 100644 index 0000000..43f2177 --- /dev/null +++ b/src/responses/dex.response.ts @@ -0,0 +1,1646 @@ +import type { Timestamp } from "@option/common.type"; +import type { Urls } from "@response/common.response"; + +/** + * The aggregated security scan results for a decentralized exchange (DEX) contract. + */ +export interface DexSecurityScanAggregated { + /** + * The contract has been verified. + */ + contract_verified: boolean; + + /** + * The contract is identified as a honeypot. + */ + honeypot: boolean; +} + +/** + * The security scan results from a third-party for a decentralized exchange (DEX). + */ +export interface DexSecurityScanThirdParty { + /** + * Indicates if the token is involved in an airdrop scam. + */ + airdrop_scam: boolean; + + /** + * Indicates if the token has anti-whale mechanisms. + */ + anti_whale: boolean; + + /** + * Indicates if the anti-whale mechanisms are modifiable. + */ + anti_whale_modifiable: boolean; + + /** + * Indicates if the token is blacklisted. + */ + blacklisted: boolean; + + /** + * Indicates if the ownership of the token can be taken back. + */ + can_take_back_ownership: boolean; + + /** + * Indicates if the token cannot be bought. + */ + cannot_buy: boolean; + + /** + * Indicates if the token cannot be sold completely. + */ + cannot_sell_all: boolean; + + /** + * Indicates if the token allows external calls. + */ + external_call: boolean; + + /** + * Indicates if the owner of the token is hidden. + */ + hidden_owner: boolean; + + /** + * Indicates if the token is a honeypot (a trap set to detect, deflect, or counteract attempts at unauthorized use). + */ + honeypot: boolean; + + /** + * Indicates if the token is listed in a decentralized exchange (DEX). + */ + in_dex: boolean; + + /** + * Indicates if the token is mintable. + */ + mintable: boolean; + + /** + * Indicates if the token is open source. + */ + open_source: boolean; + + /** + * Indicates if the owner can change the balance of the token. + */ + owner_change_balance: boolean; + + /** + * Indicates if personal slippage is modifiable. + */ + personal_slippage_modifiable: boolean; + + /** + * Indicates if the token uses a proxy contract. + */ + proxy: boolean; + + /** + * Indicates if the token has a self-destruct function. + */ + self_destruct: boolean; + + /** + * Indicates if slippage is modifiable. + */ + slippage_modifiable: boolean; + + /** + * Indicates if there is a trading cool-down period. + */ + trading_cool_down: boolean; + + /** + * Indicates if the transfer of the token can be paused. + */ + transfer_pausable: boolean; + + /** + * Indicates if the token is a true token (not a scam or fake). + */ + true_token: boolean; + + /** + * Indicates if the token is on a trust list. + */ + trust_list: boolean; + + /** + * Indicates if the token is whitelisted. + */ + whitelisted: boolean; +} + +/** + * Represents a security scan for a decentralized exchange (DEX). + * @see {@link DexSecurityScanAggregated} + * @see {@link DexSecurityScanThirdParty} + * @template TAggregated - The type for aggregated security scan data. Defaults to `DexSecurityScanAggregated`. + * @template TThirdParty - The type for third-party security scan data. Defaults to `DexSecurityScanThirdParty`. + */ +export interface DexSecurityScan { + /** + * The aggregated security scan data. + */ + aggregated: TAggregated; + + /** + * The third-party security scan data. + */ + third_party: TThirdParty; +} + +/** + * A mapping values of a decentralized exchange (DEX) with various attributes. + */ +export interface DexIdMap { + /** + * The unique identifier of the DEX + */ + id: number; + + /** + * The name of the DEX + */ + name: string; + + /** + * The slug representing the network of the DEX + */ + network_slug: string; + + /** + * An alternative name for the DEX + */ + alternativeName?: string; + + /** + * The identifier of the associated cryptocurrency + */ + cryptocurrencyId?: string; + + /** + * The slug representing the associated cryptocurrency + */ + cryptocurrencySlug?: string; + + /** + * The URL to explore the DEX pool + */ + poolExplorerUrl?: string; + + /** + * The URL to explore the DEX token + */ + tokenExplorerUrl?: string; + + /** + * The URL to view the transaction hash + */ + transactionHashUrl?: string; + + /** + * The identifier of the wrapped token + */ + wrappedTokenId?: string; + + /** + * The slug representing the wrapped token + */ + wrappedTokenSlug?: string; +} + +/** + * Represents a response containing a map of Dex IDs. + * @see {@link DexIdMap} + */ +export type DexIdMapResponse = DexIdMap[]; + +/** + * The metadata of a decentralized exchange (DEX). + */ +export interface DexMetadata { + /** + * Unique identifier for the DEX + */ + id: number; + + /** + * Name of the DEX + */ + name: string; + + /** + * Slug (URL-friendly name) of the DEX + */ + slug: string; + + /** + * URL to the hosted cmc logo of the DEX. *`64px` is default size returned.* \ + * Replace `64x64` in the image path with these alternative sizes: `16`, `32`, `64`, `128`, `200` + */ + logo: string; + + /** + * Current status of the DEX, either `"active"` or `"inactive"` + */ + status: "active" | "inactive"; + + /** + * Notice or announcement related to the DEX, can be `null` + */ + notice: string | null; + + /** + * Description of the DEX, can be `null` + */ + description: string | null; + + /** + * Optional date when the DEX was launched + */ + date_launched?: Timestamp; + + /** + * URLs related to the DEX, including chat, twitter, website, fee, and blog + */ + urls: Pick & { + fee: string[]; + blog: string[]; + }; +} + +/** + * A response containing metadata for multiple decentralized exchanges (DEX). + * @see {@link DexMetadata} + */ +export type DexMetadataResponse = DexMetadata[]; + +/** + * A market quote for a listing on a decentralized exchange (DEX). + */ +export interface DexListingQuote { + /** + * The id of specified currency + */ + convert_id: string; + + /** + * The timestamp of the last update + */ + last_updated: Timestamp; + + /** + * The type of market for the quote. \ + * *Can be `"spot"`, `"perpetual"`, or `"futures"`.* + */ + market_type: "spot" | "perpetual" | "futures"; + + /** + * The number of transactions in the last 24 hours. \ + * *Can be `null` if the data is not available.* + */ + num_transactions_24h?: number | null; + + /** + * The percentage change in volume over the last 24 hours + */ + percent_change_volume_24h?: number; + + /** + * Reported 24 hour volume in the specified currency + */ + volume_24h: number; +} + +/** + * A decentralized exchange (DEX) listing. + * @see {@link Urls} \ + * @see {@link DexListingQuote} + * @template TQuote - The type of the quote object, defaults to `DexListingQuote`. + */ +export interface DexListing { + /** + * The unique identifier for the DEX listing + */ + id: number; + + /** + * The URL-friendly name of the DEX + */ + slug: string; + + /** + * The name of the DEX + */ + name: string; + + /** + * The status of the DEX, either `"active"` or `"inactive"` + */ + status: "active" | "inactive"; + + /** + * The type of the DEX. \ + * *Can be `"orderbook"`, `"swap"`, or `"aggregator"`.* + */ + type: "orderbook" | "swap" | "aggregator"; + + /** + * The URL to the hosted cmc logo of the DEX. *`64px` is default size returned.* \ + * *Replace `64x64` in the image path with these alternative sizes: `16`, `32`, `64`, `128`, `200`* + */ + logo: string; + + /** + * The description of the DEX, can be `null` + */ + description: string | null; + + /** + * Notice or announcement related to the DEX, can be `null` + */ + notice: string | null; + + /** + * The 24 hour trading volume in USD + */ + market_share: number; + + /** + * The number of market pairs available on the DEX + */ + num_market_pairs: number; + + /** + * The date when the DEX was launched + */ + date_launched?: Timestamp; + + /** + * The timestamp of the last update + */ + last_updated: Timestamp; + + /** + * An array of market quotes + */ + quote: TQuote[]; + + /** + * Various resource URLs for this DEX + */ + urls?: Pick & { + /** + * Array of official web URLs covering exchange fees. + */ + fee: string[]; + + /** + * Array of official blog URLs + */ + blog: string[]; + }; +} + +/** + * A list of decentralized exchange (DEX) listings. + * @see {@link DexListing} + * @see {@link DexListingQuote} + * @template TQuote - The type of the quote object, which extends the default `DexListingQuote` object. + */ +export type DexListingResponse = DexListing[]; + +/** + * A market quotes in different currency conversions. + */ +export interface DexQuote { + /** + * id of specified currency + */ + convert_id: string; + + /** + * The fully diluted value of the asset + */ + fully_diluted_value: number; + + /** + * Timestamp (ISO 8601) of when the conversion currency's current value was referenced for this conversion + */ + last_updated: string; + + /** + * Total liquidity available currently in the specified currency. \ + * *This field will return `null` if not available.* + */ + liquidity: number | null; + + /** + * The percentage change in price over the last hour + */ + percent_change_price_1h: number; + + /** + * The percentage change in price over the last 24 hours + */ + percent_change_price_24h: number; + + /** + * The price in the specified currency for this spot pair + */ + price: number; + + /** + * The price of the base asset in quote asset for this spot pair + */ + price_by_quote_asset: number; + + /** + * Reported 24 hour volume in the specified spot pair in the specified currency + */ + volume_24h: number; + + /** + * The 24 hours buy volume of the asset + */ + "24h_buy_volume"?: number; + + /** + * The 24 hours sell volume of the asset + */ + "24h_sell_volume"?: number; +} + +/** + * Interface representing the quotes for a decentralized exchange (DEX). + * @see {@link DexQuote} + * @see {@link DexSecurityScan} + * @template TQuote - Type of the quote object, extending `DexQuote`. + * @template TSecurityScan - Type of the security scan object, extending `DexSecurityScan`. + */ +export interface DexQuotes { + /** + * The contract addres of this base asset in the spot pair + */ + base_asset_contract_address: string; + + /** + * The id of this base asset in the spot pair + */ + base_asset_id: string; + + /** + * The name of this base asset in the spot pair + */ + base_asset_name: string; + + /** + * The symbol of this base asset in the spot pair + */ + base_asset_symbol: string; + + /** + * The ucid of this base asset in the spot pair + */ + base_asset_ucid: string; + + /** + * Buy tax on the asset + */ + buy_tax?: number; + + /** + * The unique contract address for this spot pair + */ + contract_address: string; + + /** + * Timestamp (ISO 8601) when we started tracking this asset + */ + created_at: Timestamp; + + /** + * Timestamp (ISO 8601) of the launch date for this exchange + */ + date_launched: Timestamp; + + /** + * The id of this dex the spot pair is on + */ + dex_id: string; + + /** + * The name of this dex the spot pair is on + */ + dex_slug: string; + + /** + * Number of holders of the asset + */ + holders?: number; + + /** + * Timestamp (ISO 8601) of the last time this record was updated + */ + last_updated: Timestamp; + + /** + * The name of this spot pair + */ + name: string; + + /** + * The id of the network the spot pair is on + */ + network_id: string; + + /** + * The slug of the network the spot pair is on + */ + network_slug: string; + + /** + * Number of transactions in past 24 hours + */ + num_transactions_24h?: number; + + /** + * Percentage of the base asset in the pool + */ + percent_pooled_base_asset?: number; + + /** + * Base asset in the pool + */ + pool_base_asset?: number; + + /** + * When the pool of the asset was created + */ + pool_created?: Timestamp; + + /** + * Quote asset in the pool + */ + pool_quote_asset?: number; + + /** + * Array of market quotes in different currency conversions + * @see {@link DexQuote} + */ + quote: TQuote[]; + + /** + * The contract addresss of this quote asset in the spot pair + */ + quote_asset_contract_address: string; + + /** + * The id of this quote asset in the spot pair + */ + quote_asset_id: string; + + /** + * The name of this quote asset in the spot pair + */ + quote_asset_name: string; + + /** + * The symbol of this quote asset in the spot pair + */ + quote_asset_symbol: string; + + /** + * The ucid of this quote asset in the spot pair + */ + quote_asset_ucid: string; + + /** + * Security scan by Go+ \ + * *Only returned if passed in aux* + * @see {@link DexSecurityScan} + */ + security_scan?: TSecurityScan; + + /** + * Sell tax on the asset + */ + sell_tax?: number; + + /** + * Total supply of the base asset + */ + total_supply_base_asset?: number; + + /** + * Total supply of the quote asset + */ + total_supply_quote_asset?: number; + + /** + * Number of asset buys in the past 24 hours + */ + "24h_no_of_buys"?: number; + + /** + * Number of asset sells in the past 24 hours + */ + "24h_no_of_sells"?: number; + + /** + * 24 hours volume of the quote asset + */ + "24h_volume_quote_asset"?: number; +} + +/** + * A response containing an array of decentralized exchange (DEX) quotes. + * @template TQuote - The type of the quote object. Defaults to `DexQuote`. + * @template TSecurityScan - The type of the security scan object. Defaults to `DexSecurityScan`. + */ +export type DexQuotesResponse< + TQuote extends object = DexQuote, + TSecurityScan extends object = DexSecurityScan, +> = DexQuotes[]; + +/** + * An market quote for a decentralized exchange (DEX) trade. \ + * *This type extends a subset of properties from `DexQuote`* + * *and includes additional properties specific to the trade amounts and total value.* + * @see {@link DexQuote} + */ +export type DexTradeQuote = Pick & { + /** + * Amount of base asset traded + */ + amount_base_asset: number; + + /** + * Amount of quote asset traded + */ + amount_quote_asset: number; + + /** + * Total value of trade in the specified currency + */ + total: number; +}; + +/** + * A decentralized exchange (DEX) trade. + * @see {@link DexTradeQuote} + * @template TQuote - The type of the quote object, defaults to `DexTradeQuote`. + */ +export interface DexTrade { + /** + * Timestamp (ISO 8601) of specified transaction + */ + date: Timestamp; + + /** + * The type of trade, either `"buy"` or `"sell"` + */ + type: "buy" | "sell"; + + /** + * Transaction hash of the trade. \ + * *Only returned if passed in aux* + */ + transaction_hash?: string; + + /** + * Link to the transaction on a blockchain explorer if available \ + * *Only returned if passed in aux* + */ + blockchain_explorer_link?: string; + + /** + * An array of market quotes in different currency conversions. + * @see {@link DexTradeQuote} + */ + quote: TQuote[]; +} + +/** + * A collection of decentralized exchange (DEX) trades. + * @see {@link DexTrade} + * @see {@link DexTradeQuote} + * @see {@link DexSecurityScan} + * @template TQuote - The type of the quote asset in the trade. Defaults to `DexTradeQuote`. + * @template TTrade - The type of the trade. Defaults to `DexTrade`. + * @template TSecurityScan - The type of the security scan object. Defaults to `DexSecurityScan`. + */ +export interface DexTrades< + TQuote extends object = DexTradeQuote, + TTrade extends object = DexTrade, + TSecurityScan extends object = DexSecurityScan, +> { + /** + * Number of asset buys in the past 24 hours + */ + "24h_no_of_buys"?: number; + + /** + * Number of asset sells in the past 24 hours + */ + "24h_no_of_sells"?: number; + + /** + * 24 hours volume of the quote asset + */ + "24h_volume_quote_asset"?: number | null; + + /** + * The contract addres of this base asset in the spot pair + */ + base_asset_contract_address: string; + + /** + * The id of this base asset in the spot pair + */ + base_asset_id: string; + + /** + * The name of this base asset in the spot pair. + */ + base_asset_name: string; + + /** + * The symbol of this base asset in the spot pair. + */ + base_asset_symbol: string; + + /** + * The ucid of this base asset in the spot pair. + */ + base_asset_ucid: string; + + /** + * Buy tax on the asset + */ + buy_tax?: number; + + /** + * The unique contract address for this spot pair. + */ + contract_address: string; + + /** + * Timestamp (ISO 8601) when we started tracking this asset. + */ + created_at: Timestamp; + + /** + * Timestamp (ISO 8601) of the launch date for this exchange. + */ + date_launched: Timestamp; + + /** + * The id of this dex the spot pair is on. + */ + dex_id: string; + + /** + * The name of this dex the spot pair is on. + */ + dex_slug: string; + + /** + * Number of holders of the asset + */ + holders?: number; + + /** + * Timestamp (ISO 8601) of the last time this record was updated. + */ + last_updated: Timestamp; + + /** + * The name of this spot pair. + */ + name: string; + + /** + * The id of the network the spot pair is on. + */ + network_id: string; + + /** + * The slug of the network the spot pair is on. + */ + network_slug: string; + + /** + * Number of transactions in past 24 hours + */ + num_transactions_24h?: number; + + /** + * Percentage of the base asset in the pool + */ + percent_pooled_base_asset?: number; + + /** + * Base asset in the pool + */ + pool_base_asset?: number; + + /** + * When the pool of the asset was created + */ + pool_created?: Timestamp; + + /** + * Quote asset in the pool + */ + pool_quote_asset?: number; + + /** + * The contract addresss of this quote asset in the spot pair. + */ + quote_asset_contract_address: string; + + /** + * The id of this quote asset in the spot pair. + */ + quote_asset_id: string; + + /** + * The name of this quote asset in the spot pair. + */ + quote_asset_name: string; + + /** + * The symbol of this quote asset in the spot pair. + */ + quote_asset_symbol: string; + + /** + * The ucid of this quote asset in the spot pair. + */ + quote_asset_ucid: string; + + /** + * Security scan by Go+ + */ + security_scan?: TSecurityScan[]; + + /** + * Sell tax on the asset + */ + sell_tax?: number; + + /** + * Total supply of the quote asset + */ + total_supply_base_asset?: number; + + /** + * Total supply of the quote asset + */ + total_supply_quote_asset?: number; + + /** + * A array of market quotes in different currency conversions. + */ + trades: TTrade[]; +} + +/** + * A response containing an array of decentralized exchange (DEX) trades. + * @see {@link DexTrade} + * @see {@link DexTrades} + * @see {@link DexTradeQuote} + * @see {@link DexSecurityScan} + * @template TQuote - The type of the quote object, extending from `DexTradeQuote`. + * @template TTrade - The type of the trade object, extending from `DexTrade` with `TQuote`. + * @template TSecurityScan - The type of the security scan object, extending from `DexSecurityScan`. + */ +export type DexTradesResponse< + TQuote extends object = DexTradeQuote, + TTrade extends object = DexTrade, + TSecurityScan extends object = DexSecurityScan, +> = DexTrades[]; + +/** + * A quote for a DEX (Decentralized Exchange) pair. + */ +export interface DexPairQuote { + /** + * 24 hours buy volume of the asset + */ + "24h_buy_volume"?: number; + + /** + * 24 hours sell volume of the asset + */ + "24h_sell_volume"?: number; + + /** + * id of specified currency + */ + convert_id: string; + + /** + * The fully diluted value of the asset. + */ + fully_diluted_value: number; + + /** + * Timestamp (ISO 8601) of when the conversion currency's current value was referenced for this conversion + */ + last_updated: string; + + /** + * Total liquidity available currently in the specified currency. \ + * *This field will return `null` if not available.* + */ + liquidity?: number | null; + + /** + * 1 hour price change percentage in the specified spot pair in the specified currency + */ + percent_change_price_1h: number; + + /** + * 24 hour price change percentage in the specified spot pair in the specified currency + */ + percent_change_price_24h: number; + + /** + * Price in the specified currency for this spot pair + */ + price: number; + + /** + * Price of the base asset in quote asset for this spot pair + */ + price_by_quote_asset: number; + + /** + * Reported 24 hour volume in the specified spot pair in the specified currency + */ + volume_24h: number; +} + +/** + * A DEX (Decentralized Exchange) pair. + */ +export interface DexPairs { + /** + * Number of asset buys in the past 24 hours + */ + "24h_no_of_buys"?: number; + + /** + * Number of asset sells in the past 24 hours + */ + "24h_no_of_sells"?: number; + + /** + * 24 hours volume of the quote asset + */ + "24h_volume_quote_asset"?: number; + + /** + * The contract addres of this base asset in the spot pair + */ + base_asset_contract_address: string; + + /** + * The id of this base asset in the spot pair + */ + base_asset_id: string; + + /** + * The name of this base asset in the spot pair + */ + base_asset_name: string; + + /** + * The symbol of this base asset in the spot pair + */ + base_asset_symbol: string; + + /** + * The ucid of this base asset in the spot pair + */ + base_asset_ucid: string; + + /** + * Buy tax on the asset + */ + buy_tax?: number; + + /** + * The unique contract address for this spot pair + */ + contract_address: string; + + /** + * Timestamp (ISO 8601) when we started tracking this asset + */ + created_at: Timestamp; + + /** + * Timestamp (ISO 8601) of the launch date for this exchange + */ + date_launched: Timestamp; + + /** + * The id of this dex the spot pair is on + */ + dex_id: string; + + /** + * The short name of this dex the spot pair is on + */ + dex_slug: string; + + /** + * Number of holders of the asset + */ + holders?: number; + + /** + * Timestamp (ISO 8601) of the last time this record was updated + */ + last_updated: Timestamp; + + /** + * The name of this spot pair + */ + name: string; + + /** + * The id of the network the spot pair is on + */ + network_id: string; + + /** + * The slug of the network the spot pair is on + */ + network_slug: string; + + /** + * Number of transactions in past 24 hours + */ + num_transactions_24h?: number; + + /** + * Percentage of the base asset in the pool + */ + percent_pooled_base_asset?: number; + + /** + * Base asset in the pool + */ + pool_base_asset?: number; + + /** + * When the pool of the asset was created + */ + pool_created: Timestamp; + + /** + * Quote asset in the pool + */ + pool_quote_asset?: number; + + /** + * An array of market quotes in different currency conversions + */ + quote: TQuote[]; + + /** + * The contract addresss of this quote asset in the spot pair + */ + quote_asset_contract_address: string; + + /** + * The id of this quote asset in the spot pair + */ + quote_asset_id: string; + + /** + * The name of this quote asset in the spot pair + */ + quote_asset_name: string; + + /** + * The symbol of this quote asset in the spot pair + */ + quote_asset_symbol: string; + + /** + * The ucid of this quote asset in the spot pair + */ + quote_asset_ucid: string; + + /** + * A unique identifier used to fetch the next batch of results from the next API related API call, if applicable. \ + * *`scroll_id` is an alternative to traditional pagingation techniques.* + */ + scroll_id: string; + + /** + * Security scan by Go+ \ + * *Only returned if passed in aux* + * @see {@link DexSecurityScan} + */ + security_scan?: TSecurityScan[]; + + /** + * Sell tax on the asset + */ + sell_tax?: number; + + /** + * Total supply of the quote asset + */ + total_supply_base_asset?: number; + + /** + * Total supply of the quote asset + */ + total_supply_quote_asset?: number; +} + +/** + * An array response of DEX (Decentralized Exchange) pairs. + * @see {@link DexPairs} + * @see {@link DexPairQuote} + * @see {@link DexSecurityScan} + * @template TQuote - The type of the quote object, extending from `DexPairQuote`. + * @template TSecurityScan - The type of the security scan object, extending from `DexSecurityScan`. + */ +export type DexPairsResponse< + TQuote extends object = DexPairQuote, + TSecurityScan extends object = DexSecurityScan, +> = DexPairs[]; + +/** + * Represents a Dex OHLCV (Open, High, Low, Close, Volume) Quote. \ + * *This type is a combination of selected properties from `DexQuote` and additional OHLCV properties.* + * @see {@link DexQuote} + */ +export type DexOhlcvQuote = Pick & { + /** + * Latest price today in UTC time for the convert option requested. \ + * *This is not the final price during close as the current day period is not over.* + */ + close: number; + + /** + * Highest price so far today in UTC time for the convert option requested. + */ + high: number; + + /** + * Lowest price today in UTC time for the convert option requested. + */ + low: number; + + /** + * Price from first datapoint of today in UTC time for the convert option requested. + */ + open: number; + + /** + * Adjusted volume for this time series interval. + */ + volume: number; +}; + +/** + * A Dex OHLCV (Open, High, Low, Close, Volume) response. + * @see {@link DexOhlcvQuote} + * @see {@link DexSecurityScan} + * @template TQuote - The type of the quote object, defaults to `DexOhlcvQuote`. + * @template TSecurityScan - The type of the security scan object, defaults to `DexSecurityScan`. + */ +export interface DexOhlcv { + /** + * Number of asset buys in the past 24 hours. + */ + "24h_no_of_buys"?: number; + + /** + * Number of asset sells in the past 24 hours. + */ + "24h_no_of_sells"?: number; + + /** + * 24 hours volume of the quote asset. + */ + "24h_volume_quote_asset"?: number | null; + + /** + * The contract addres of this base asset in the spot pair. + */ + base_asset_contract_address: string; + + /** + * The id of this base asset in the spot pair. + */ + base_asset_id: string; + + /** + * The name of this base asset in the spot pair. + */ + base_asset_name: string; + + /** + * The symbol of this base asset in the spot pair. + */ + base_asset_symbol: string; + + /** + * The ucid of this base asset in the spot pair. + */ + base_asset_ucid: string; + + /** + * Buy tax on the asset. + */ + buy_tax?: number; + + /** + * The unique contract address for this spot pair. + */ + contract_address: string; + + /** + * Timestamp (ISO 8601) when we started tracking this asset. + */ + created_at: Timestamp; + + /** + * Timestamp (ISO 8601) of the launch date for this exchange. + */ + date_launched: Timestamp; + + /** + * The id of this dex the spot pair is on. + */ + dex_id: string; + + /** + * The name of this dex the spot pair is on. + */ + dex_slug: string; + + /** + * Number of holders of the asset. + */ + holders?: number; + + /** + * Timestamp (ISO 8601) of the last time this record was updated. + */ + last_updated: Timestamp; + + /** + * The name of this spot pair. + */ + name: string; + + /** + * The id of the network the spot pair is on. + */ + network_id: string; + + /** + * The slug of the network the spot pair is on. + */ + network_slug: string; + + /** + * Number of transactions in past 24 hours. + */ + num_transactions_24h?: number; + + /** + * Percentage of the base asset in the pool. + */ + percent_pooled_base_asset?: number; + + /** + * Base asset in the pool. + */ + pool_base_asset?: number; + + /** + * When the pool of the asset was created. + */ + pool_created?: Timestamp; + + /** + * Quote asset in the pool. + */ + pool_quote_asset?: number; + + /** + * Array of market quotes in different currency conversions. + */ + quote: TQuote[]; + + /** + * The contract addresss of this quote asset in the spot pair. + */ + quote_asset_contract_address: string; + + /** + * The id of this quote asset in the spot pair. + */ + quote_asset_id: string; + + /** + * The name of this quote asset in the spot pair. + */ + quote_asset_name: string; + + /** + * The symbol of this quote asset in the spot pair. + */ + quote_asset_symbol: string; + + /** + * The ucid of this quote asset in the spot pair. + */ + quote_asset_ucid: string; + + /** + * Security scan by Go+ + * @see {@link DexSecurityScan} + */ + security_scan?: TSecurityScan[]; + + /** + * Sell tax on the asset + */ + sell_tax?: number; + + /** + * Timestamp (ISO 8601) of the end of this OHLCV period. \ + * *Always `null` as the current day is incomplete.* \ + * *See last_updated for the last UTC time included in the current OHLCV calculation.* + */ + time_close: Timestamp | null; + + /** + * Timestamp (ISO 8601) of the start of this OHLCV period. + */ + time_open: Timestamp; + + /** + * Total supply of the quote asset. + */ + total_supply_base_asset?: number; + + /** + * Total supply of the quote asset. + */ + total_supply_quote_asset?: number; +} + +/** + * The response type for Dex OHLCV (Open, High, Low, Close, Volume) data. + * @see {@link DexOhlcv} + * @see {@link DexOhlcvQuote} + * @see {@link DexSecurityScan} + * @template TQuote - The type of the quote object, defaults to `DexOhlcvQuote`. + * @template TSecurityScan - The type of the security scan object, defaults to `DexSecurityScan`. + */ +export type DexOhlcvResponse< + TQuote extends object = DexOhlcvQuote, + TSecurityScan extends object = DexSecurityScan, +> = DexOhlcv[]; + +/** + * A historical quotes for a decentralized exchange (DEX). + * @see {@link DexOhlcvQuote} + * @template TQuote - The type of the quote objects, extending from `DexOhlcvQuote`. + */ +export interface DexOhlcvHistoricalQuotes { + /** + * An array of quote objects + * @see {@link DexOhlcvQuote} + */ + quote: TQuote[]; + + /** + * Timestamp (ISO 8601) of the end of this OHLCV period. \ + * *Always `null` as the current day is incomplete.* \ + * *See last_updated for the last UTC time included in the current OHLCV calculation.* + */ + time_close: Timestamp; + + /** + * Timestamp (ISO 8601) of the start of this OHLCV period. + */ + time_open: Timestamp; +} + +/** + * A historical OHLCV (Open, High, Low, Close, Volume) data for a decentralized exchange (DEX). + * @see {@link DexOhlcvHistoricalQuotes} + * @see {@link DexSecurityScan} + * @template TQuotes - The type of the quote objects, extending from `DexOhlcvHistoricalQuotes`. + * @template TSecurityScan - The type of the security scan object, extending from `DexSecurityScan`. + */ +export interface DexOhlcvHistorical< + TQuotes extends object = DexOhlcvHistoricalQuotes, + TSecurityScan extends object = DexSecurityScan, +> { + /** + * Number of asset buys in the past 24 hours. + */ + "24h_no_of_buys"?: number; + + /** + * Number of asset sells in the past 24 hours. + */ + "24h_no_of_sells"?: number; + + /** + * 24 hours volume of the quote asset. + */ + "24h_volume_quote_asset"?: number; + + /** + * The contract addres of this base asset in the spot pair. + */ + base_asset_contract_address: string; + + /** + * The id of this base asset in the spot pair. + */ + base_asset_id: string; + + /** + * The name of this base asset in the spot pair. + */ + base_asset_name: string; + + /** + * The symbol of this base asset in the spot pair. + */ + base_asset_symbol: string; + + /** + * The ucid of this base asset in the spot pair. + */ + base_asset_ucid: string; + + /** + * Buy tax on the asset. + */ + buy_tax?: number; + + /** + * The unique contract address for this spot pair. + */ + contract_address: string; + + /** + * Timestamp (ISO 8601) when we started tracking this asset. + */ + created_at: Timestamp; + + /** + * Timestamp (ISO 8601) of the launch date for this exchange. + */ + date_launched: Timestamp; + + /** + * The id of this dex the spot pair is on. + */ + dex_id: string; + + /** + * The name of this dex the spot pair is on. + */ + dex_slug: string; + + /** + * Number of holders of the asset + */ + holders?: number; + + /** + * Timestamp (ISO 8601) of the last time this record was updated. + */ + last_updated: Timestamp; + + /** + * The name of this spot pair. + */ + name: string; + + /** + * The id of the network the spot pair is on. + */ + network_id: string; + + /** + * The slug of the network the spot pair is on. + */ + network_slug: string; + + /** + * Number of transactions in past 24 hours + */ + num_transactions_24h?: number; + + /** + * Percentage of the base asset in the pool + */ + percent_pooled_base_asset?: number; + + /** + * Base asset in the pool + */ + pool_base_asset?: number; + + /** + * When the pool of the asset was created + */ + pool_created?: Timestamp; + + /** + * Quote asset in the pool + */ + pool_quote_asset?: number; + + /** + * The contract addresss of this quote asset in the spot pair. + */ + quote_asset_contract_address: string; + + /** + * The id of this quote asset in the spot pair. + */ + quote_asset_id: string; + + /** + * The name of this quote asset in the spot pair. + */ + quote_asset_name: string; + + /** + * The symbol of this quote asset in the spot pair. + */ + quote_asset_symbol: string; + + /** + * The ucid of this quote asset in the spot pair. + */ + quote_asset_ucid: string; + + /** + * An array of historical quotes for the spot pair. + * @see {@link DexOhlcvHistoricalQuotes} + */ + quotes: TQuotes[]; + + /** + * Security scan by Go+ + * @see {@link DexSecurityScan} + */ + security_scan?: TSecurityScan[]; + + /** + * Sell tax on the asset + */ + sell_tax?: number; + + /** + * Total supply of the quote asset + */ + total_supply_base_asset?: number; + + /** + * Total supply of the quote asset + */ + total_supply_quote_asset?: number; +} + +/** + * The response for historical OHLCV (Open, High, Low, Close, Volume) data from a decentralized exchange (DEX). + * @see {@link DexOhlcvHistorical} + * @see {@link DexOhlcvHistoricalQuotes} + * @see {@link DexSecurityScan} + * @template TQuotes - The type of the quotes object, defaults to `DexOhlcvHistoricalQuotes`. + * @template TSecurityScan - The type of the security scan object, defaults to `DexSecurityScan`. + */ +export type DexOhlcvHistoricalResponse< + TQuotes extends object = DexOhlcvHistoricalQuotes, + TSecurityScan extends object = DexSecurityScan, +> = DexOhlcvHistorical[]; diff --git a/src/types/dex.option.ts b/src/types/dex.option.ts new file mode 100644 index 0000000..18e42ec --- /dev/null +++ b/src/types/dex.option.ts @@ -0,0 +1,600 @@ +/** + * The Dex identifier which can be either an `id` or a `slug`. + * + * *This type is a union of two possible shapes:* + * - *An object with an `id` property which can be a number or an array of numbers, and no `slug`.* + * - *An object with a `slug` property which can be a string or an array of strings, and no `id`.* + * + * @example import dex id type + * ```typescript + * import type { DexId } from "cmc-api"; + * ``` + * + * @example using a id + * ```typescript + * const dexById: DexId = { id: 1348 }; + * ``` + * + * @example using a slug + * ```typescript + * const dexBySlug: DexId = { slug: 'uniswap-v3' }; + * ``` + * + * @example using an array of ids + * ```typescript + * const dexByIds: DexId = { id: [1348, 6707] }; + * ``` + * + * @example using an array of slugs + * ```typescript + * const dexBySlugs: DexId = { slug: ['uniswap-v3', 'pancakeswap-v3-eth'] }; + * ``` + */ +export type DexId = { id: number | number[]; slug?: never } | { id?: never; slug: string | string[] }; + +/** + * The decentralized exchange (DEX) network identifier. + * + * *This type can be one of the following*: + * - *An object with an `id` property, which can be a number or array of number, and no `slug` property.* + * - *An object with a `slug` property, which can be a string or array of string, and no `id` property.* + * + * @example import dex network type + * ```typescript + * import type { DexNetwork } from "cmc-api"; + * ``` + * + * @example dex network with id + * ```typescript + * const dexNetworkWithId: DexNetwork = { id: '1' }; + * ``` + * + * @example dex network with slug + * ```typescript + * const dexNetworkWithSlug: DexNetwork = { slug: 'ethereum' }; + * ``` + */ +export type DexNetwork = { id: number | number[]; slug?: never } | { id?: never; slug: string | string[] }; + +/** + * The base asset in a decentralized exchange (DEX). + * + * *This type can be one of the following*: + * - *An object with an `id` property, which can be a number or array of number, and no `symbol`, `ucid`, or `contract` property.* + * - *An object with a `symbol` property, which can be a string or array of string, and no `id`, `ucid`, or `contract` property.* + * - *An object with a `ucid` property, which can be a number or array of number, and no `id`, `symbol`, or `contract` property.* + * - *An object with a `contract` property, which can be a string, and no `id`, `symbol`, or `ucid` property.* + * + * @example import dex base asset type + * ```typescript + * import type { DexBaseAsset } from "cmc-api"; + * ``` + * + * @example using an id + * ```typescript + * const baseAssetById: DexBaseAsset = { id: 11840 }; + * ``` + * + * @example using a symbol + * ```typescript + * const baseAssetBySymbol: DexBaseAsset = { symbol: 'OP' }; + * ``` + * + * @example using a ucid + * ```typescript + * const baseAssetByUcid: DexBaseAsset = { ucid: 11840 }; + * ``` + * + * @example using a contract + * ```typescript + * const baseAssetByContract: DexBaseAsset = { contract: '0x4200000000000000000000000000000000000042' }; + * ``` + */ +export type DexBaseAsset = + | { id: number | number[]; symbol?: never; ucid?: never; contract?: never } // id + | { id?: never; symbol: string | string[]; ucid?: never; contract?: never } // symbol + | { id?: never; symbol?: never; ucid: number | number[]; contract?: never } // ucid + | { id?: never; symbol?: never; ucid?: never; contract: string }; // contract + +/** + * The quote asset in a decentralized exchange (DEX). \ + * *This type is an alias for `DexBaseAsset`.* + * @see {@link DexBaseAsset} + */ +export type DexQuoteAsset = DexBaseAsset; + +/** + * The sorting options for a list of decentralized exchanges (DEX). + * @property {"id"} - Sort by the unique identifier of the DEX. + * @property {"name"} - Sort by the name of the DEX. + */ +export type DexListSort = "id" | "name"; + +/** + * The list of auxiliary DEX (Decentralized Exchange) options. + * + * The list can contain the following string values: + * - `"alternativeName"`: *An alternative name for the DEX.* + * - `"cryptocurrencyId"`: *The ID of the cryptocurrency.* + * - `"cryptocurrenySlug"`: *The slug of the cryptocurrency (Note: This might be a typo of `"cryptocurrencySlug"`).* + * - `"wrappedTokenId"`: *The ID of the wrapped token.* + * - `"wrappedTokenSlug"`: *The slug of the wrapped token.* + * - `"tokenExplorerUrl"`: *The URL to explore the token.* + * - `"poolExplorerUrl"`: *The URL to explore the pool.* + * - `"transactionHashUrl"`: *The URL to explore the transaction hash.* + * + * The type can also be an array of the above string values. + */ +export type AuxiliaryDexList = + | "alternativeName" + | "cryptocurrencyId" + | "cryptocurrenySlug" /** Maybe typo of "cryptocurrencySlug" */ + | "wrappedTokenId" + | "wrappedTokenSlug" + | "tokenExplorerUrl" + | "poolExplorerUrl" + | "transactionHashUrl" + | ( + | "alternativeName" + | "cryptocurrencyId" + | "cryptocurrenySlug" /** Maybe typo of "cryptocurrencySlug" */ + | "wrappedTokenId" + | "wrappedTokenSlug" + | "tokenExplorerUrl" + | "poolExplorerUrl" + | "transactionHashUrl" + )[]; + +/** + * The auxiliary metadata for a decentralized exchange (DEX). \ + * *This type can be a single metadata key or an array of metadata keys.* + * + * The possible metadata keys are: + * - `"urls"`: *URLs related to the DEX.* + * - `"logo"`: *The logo of the DEX.* + * - `"description"`: *A description of the DEX.* + * - `"date_launched"`: *The launch date of the DEX.* + * - `"notice"`: *Any notices related to the DEX.* + */ +export type AuxiliaryDexMetadata = + | "urls" + | "logo" + | "description" + | "date_launched" + | "notice" + | ("urls" | "logo" | "description" | "date_launched" | "notice")[]; + +/** + * The type of a decentralized exchange (DEX) listing. + * + * This type can be one of the following string literals: + * - `"all"`: *Represents all types of DEX listings.* + * - `"orderbook"`: *Represents DEX listings that use an order book.* + * - `"swap"`: *Represents DEX listings that use a swap mechanism.* + * - `"aggregator"`: *Represents DEX listings that aggregate multiple sources.* + * + * Additionally, it can be an array of any combination of the above string literals. + */ +export type DexListingType = + | "all" + | "orderbook" + | "swap" + | "aggregator" + | ("all" | "orderbook" | "swap" | "aggregator")[]; + +/** + * The sorting options for a decentralized exchange (DEX) listing. + * + * The sorting can be based on one of the following criteria: + * - `"name"`: *Sort by the name of the DEX.* + * - `"volume_24h"`: *Sort by the 24-hour trading volume.* + * - `"market_share"`: *Sort by the market share.* + * - `"num_markets"`: *Sort by the number of markets.* + * + * Additionally, it can be an array of the above criteria to allow for multiple sorting options. + */ +export type DexListingSort = + | "name" + | "volume_24h" + | "market_share" + | "num_markets" + | ("name" | "volume_24h" | "market_share" | "num_markets")[]; + +/** + * The auxiliary listing options for a decentralized exchange (DEX). + * This type can either be a single string value `"date_launched"` or an array of such strings. + */ +export type AuxiliaryDexListing = "date_launched" | string[]; + +/** + * The various auxiliary quotes available for a decentralized exchange (DEX). + * + * The `AuxiliaryDexQuotes` type can be one of the following string literals or an array of these string literals: + * - `"pool_created"`: *Indicates when the pool was created.* + * - `"percent_pooled_base_asset"`: *The percentage of the base asset that is pooled.* + * - `"num_transactions_24h"`: *The number of transactions in the last 24 hours.* + * - `"pool_base_asset"`: *The base asset in the pool.* + * - `"pool_quote_asset"`: *The quote asset in the pool.* + * - `"24h_volume_quote_asset"`: *The 24-hour volume of the quote asset.* + * - `"total_supply_quote_asset"`: *The total supply of the quote asset.* + * - `"total_supply_base_asset"`: *The total supply of the base asset.* + * - `"holders"`: *The number of holders.* + * - `"buy_tax"`: *The buy tax rate.* + * - `"sell_tax"`: *The sell tax rate.* + * - `"security_scan"`: *The result of a security scan.* + * - `"24h_no_of_buys"`: *The number of buys in the last 24 hours.* + * - `"24h_no_of_sells"`: *The number of sells in the last 24 hours.* + * - `"24h_buy_volume"`: *The buy volume in the last 24 hours.* + * - `"24h_sell_volume"`: *The sell volume in the last 24 hours.* + */ +export type AuxiliaryDexQuotes = + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + | ( + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + )[]; + +/** + * The auxiliary fields data for DEX trades. \ + * *Additionally, it can be an array of any combination of the above string literals.* + * + * This type can be one of the following: + * - `"transaction_hash"`: *A string representing the transaction hash*. + * - `"blockchain_explorer_link"`: *A string representing the link to the blockchain explorer*. + */ +export type AuxiliaryDexTrades = + | "transaction_hash" + | "blockchain_explorer_link" + | ("transaction_hash" | "blockchain_explorer_link")[]; + +/** + * The filter options for querying DEX pairs. + */ +export interface DexPairsFilter { + /** + * After your initial query, the API responds with the initial set of results and a `scrollId`. \ + * *To retrieve the next set of results, provide this `scrollId` of the last JSON with your follow-up request.* \ + * *`scrollId` is an alternative to traditional pagination techniques.* + */ + scrollId?: string; + + /** + * The number of results to return. \ + * *Use this parameter and the start parameter to determine your own pagination size.* + */ + limit?: number; + + /** + * A threshold of minimum liquidity to filter results by. \ + * *must be in range: `[ 0 .. 100000000000000000 ]`* + */ + liquidityMin?: number; + + /** + * A threshold of maximum liquidity to filter results by. \ + * *must be in range: `[ 0 .. 100000000000000000 ]`* + */ + liquidityMax?: number; + + /** + * A threshold of minimum 24 hour USD volume to filter results by. \ + * *must be in range: `[ 0 .. 100000000000000000 ]`* + */ + volume24hMin?: number; + + /** + * A threshold of maximum 24 hour USD volume to filter results by. \ + * *must be in range: `[ 0 .. 100000000000000000 ]`* + */ + volume24hMax?: number; + + /** + * A threshold of minimum 24h no. of transactions to filter results by. \ + * *must be in range: `[ 0 .. 100000000000000000 ]`* + */ + noOfTransactions24hMin?: number; + + /** A threshold of maximum 24h no. of transactions to filter results by. \ + * *must be in range: `[ 0 .. 100000000000000000 ]`* + */ + noOfTransactions24hMax?: number; + + /** + * A threshold of minimum 24 hour percent change to filter results by. \ + * *must be: `>= -100`* + */ + percentChange24hMin?: number; + + /** + * A threshold of maximum 24 hour percent change to filter results by. \ + * *must be: `>= -100`* + */ + percentChange24hMax?: number; +} + +/** + * The sorting options available for DEX pairs. + * + * The available options are: + * - `"name"`: *Sort by the name of the DEX pair.* + * - `"date_added"`: *Sort by the date the DEX pair was added.* + * - `"price"`: *Sort by the price of the DEX pair.* + * - `"volume_24h"`: *Sort by the 24-hour trading volume of the DEX pair.* + * - `"percent_change_1h"`: *Sort by the 1-hour percentage change of the DEX pair.* + * - `"percent_change_24h"`: *Sort by the 24-hour percentage change of the DEX pair.* + * - `"liquidity"`: *Sort by the liquidity of the DEX pair.* + * - `"fully_diluted_value"`: *Sort by the fully diluted value of the DEX pair.* + * - `"no_of_transactions_24h"`: *Sort by the number of transactions in the last 24 hours of the DEX pair.* + */ +export type DexPairsSort = + | "name" + | "date_added" + | "price" + | "volume_24h" + | "percent_change_1h" + | "percent_change_24h" + | "liquidity" + | "fully_diluted_value" + | "no_of_transactions_24h"; + +/** + * The various auxiliary data points for decentralized exchange (DEX) pairs. + * + * Possible values: + * - `"pool_created"`: *Indicates the creation of the pool.* + * - `"percent_pooled_base_asset"`: *The percentage of the base asset pooled.* + * - `"num_transactions_24h"`: *The number of transactions in the last 24 hours.* + * - `"pool_base_asset"`: *The amount of the base asset in the pool.* + * - `"pool_quote_asset"`: *The amount of the quote asset in the pool.* + * - `"24h_volume_quote_asset"`: *The 24-hour trading volume of the quote asset.* + * - `"total_supply_quote_asset"`: *The total supply of the quote asset.* + * - `"total_supply_base_asset"`: *The total supply of the base asset.* + * - `"holders"`: *The number of holders of the asset.* + * - `"buy_tax"`: *The tax applied on buying the asset.* + * - `"sell_tax"`: *The tax applied on selling the asset.* + * - `"security_scan"`: *The results of the security scan.* + * - `"24h_no_of_buys"`: *The number of buys in the last 24 hours.* + * - `"24h_no_of_sells"`: *The number of sells in the last 24 hours.* + * - `"24h_buy_volume"`: *The volume of buys in the last 24 hours.* + * - `"24h_sell_volume"`: *The volume of sells in the last 24 hours.* + * + * Additionally, it can be an array of any combination of the above string literals. + */ +export type AuxiliaryDexPairs = + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + | ( + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + )[]; + +/** + * Represents auxiliary data for a decentralized exchange (DEX) OHLCV (Open, High, Low, Close, Volume). \ + * *This type can be a single string value or an array of string values.* + * + * Possible values include: + * - `"pool_created"`: *Indicates when the pool was created.* + * - `"percent_pooled_base_asset"`: *Percentage of the base asset pooled.* + * - `"num_transactions_24h"`: *Number of transactions in the last 24 hours.* + * - `"pool_base_asset"`: *The base asset in the pool.* + * - `"pool_quote_asset"`: *The quote asset in the pool.* + * - `"24h_volume_quote_asset"`: *24-hour volume of the quote asset.* + * - `"total_supply_quote_asset"`: *Total supply of the quote asset.* + * - `"total_supply_base_asset"`: *Total supply of the base asset.* + * - `"holders"`: *Number of holders.* + * - `"buy_tax"`: *Tax applied on buys.* + * - `"sell_tax"`: *Tax applied on sells.* + * - `"security_scan"`: *Security scan information.* + * - `"24h_no_of_buys"`: *Number of buys in the last 24 hours.* + * - `"24h_no_of_sells"`: *Number of sells in the last 24 hours.* + * - `"24h_buy_volume"`: *Buy volume in the last 24 hours.* + * - `"24h_sell_volume"`: *Sell volume in the last 24 hours.* + */ +export type AuxiliaryDexOhlcv = + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + | ( + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + )[]; + +/** + * The time period for historical OHLCV (Open, High, Low, Close, Volume) data for a decentralized exchange (DEX). + * + * The available time periods are: + * - `"daily"`: *Daily time period.* + * - `"hourly"`: *Hourly time period.* + * - `"1m"`: *1 minute time period.* + * - `"5m"`: *5 minutes time period.* + * - `"15m"`: *15 minutes time period.* + * - `"30m"`: *30 minutes time period.* + * - `"4h"`: *4 hours time period.* + * - `"8h"`: *8 hours time period.* + * - `"12h"`: *12 hours time period.* + * - `"weekly"`: *Weekly time period.* + * - `"monthly"`: *Monthly time period.* + */ +export type DexOhlcvHistoricalTimePeriod = + | "daily" + | "hourly" + | "1m" + | "5m" + | "15m" + | "30m" + | "4h" + | "8h" + | "12h" + | "weekly" + | "monthly"; + +/** + * The intervals for historical OHLCV (Open, High, Low, Close, Volume) data for a decentralized exchange (DEX). + * + * The available intervals are: + * - `"1m"`: *1 minute* + * - `"5m"`: *5 minutes* + * - `"15m"`: *15 minutes* + * - `"30m"`: *30 minutes* + * - `"1h"`: *1 hour* + * - `"4h"`: *4 hours* + * - `"8h"`: *8 hours* + * - `"12h"`: *12 hours* + * - `"daily"`: *1 day* + * - `"weekly"`: *1 week* + * - `"monthly"`: *1 month* + */ +export type DexOhlcvHistoricalInterval = + | "1m" + | "5m" + | "15m" + | "30m" + | "1h" + | "4h" + | "8h" + | "12h" + | "daily" + | "weekly" + | "monthly"; + +/** + * The historical OHLCV (Open, High, Low, Close, Volume) data for a decentralized exchange (DEX). \ + * *This type can be a single string value or an array of string values representing various historical metrics.* + * + * Possible values: + * - `"pool_created"`: *Indicates when the pool was created.* + * - `"percent_pooled_base_asset"`: *The percentage of the base asset pooled.* + * - `"num_transactions_24h"`: *The number of transactions in the last 24 hours.* + * - `"pool_base_asset"`: *The base asset in the pool.* + * - `"pool_quote_asset"`: *The quote asset in the pool.* + * - `"24h_volume_quote_asset"`: *The 24-hour volume of the quote asset.* + * - `"total_supply_quote_asset"`: *The total supply of the quote asset.* + * - `"total_supply_base_asset"`: *The total supply of the base asset.* + * - `"holders"`: *The number of holders.* + * - `"buy_tax"`: *The buy tax percentage.* + * - `"sell_tax"`: *The sell tax percentage.* + * - `"security_scan"`: *The result of a security scan.* + * - `"24h_no_of_buys"`: *The number of buys in the last 24 hours.* + * - `"24h_no_of_sells"`: *The number of sells in the last 24 hours.* + * - `"24h_buy_volume"`: *The buy volume in the last 24 hours.* + * - `"24h_sell_volume"`: *The sell volume in the last 24 hours.* + */ +export type AuxiliaryDexOhlcvHistorical = + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + | ( + | "pool_created" + | "percent_pooled_base_asset" + | "num_transactions_24h" + | "pool_base_asset" + | "pool_quote_asset" + | "24h_volume_quote_asset" + | "total_supply_quote_asset" + | "total_supply_base_asset" + | "holders" + | "buy_tax" + | "sell_tax" + | "security_scan" + | "24h_no_of_buys" + | "24h_no_of_sells" + | "24h_buy_volume" + | "24h_sell_volume" + )[];