BlockMarketScan API

/**
 * BlockMarketScan JavaScript SDK v2.0.0
 * https://blockmarketscan.com
 *
 * Every endpoint requires an API key. Request one at /developers.
 *
 *   const bms = new BlockMarketScan({ apiKey: 'bms_...' });
 *   const top = await bms.getListingsLatest({ limit: 50 });
 *   const btc = await bms.getQuotesLatest({ symbol: 'BTC' });
 *
 * Prices are live: every quote carries a price_source field naming the feed that
 * produced it ("binance", "livecoinwatch", "dexscreener" or "db").
 *
 * Keep your key server side. In a browser it is visible to anyone who opens
 * devtools; proxy through your own backend instead.
 */

class BlockMarketScanError extends Error {
  constructor(message, status, body) {
    super(message);
    this.name = 'BlockMarketScanError';
    this.status = status;
    this.body = body;
  }
}

class BlockMarketScan {
  /**
   * @param {Object|string} options  An options object, or the API key directly.
   * @param {string} options.apiKey  Required. Sent as the x-api-key header.
   * @param {string} [options.baseUrl]
   * @param {number} [options.timeoutMs=15000]
   * @param {number} [options.retries=2]  Retries on 429 and 5xx, with backoff.
   */
  constructor(options = {}) {
    const config = typeof options === 'string' ? { apiKey: options } : options;

    this.apiKey = config.apiKey || (typeof process !== 'undefined' && process.env
      ? process.env.BMS_API_KEY
      : undefined);
    this.baseUrl = (config.baseUrl || 'https://blockmarketscan.com/api').replace(/\/$/, '');
    this.timeoutMs = config.timeoutMs ?? 15000;
    this.retries = config.retries ?? 2;

    if (!this.apiKey) {
      throw new BlockMarketScanError(
        'An API key is required. Pass { apiKey } or set BMS_API_KEY. Request one at https://blockmarketscan.com/developers',
        401,
        null,
      );
    }
  }

  async _fetch(path, params = {}) {
    const url = new URL(this.baseUrl + path);
    Object.entries(params).forEach(([k, v]) => {
      if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v));
    });

    let lastError;
    for (let attempt = 0; attempt <= this.retries; attempt += 1) {
      const controller = new AbortController();
      const timer = setTimeout(() => controller.abort(), this.timeoutMs);

      try {
        const res = await fetch(url, {
          headers: { 'x-api-key': this.apiKey, accept: 'application/json' },
          signal: controller.signal,
        });

        if (res.ok) return await res.json();

        const body = await res.json().catch(() => null);
        const message = body?.status?.error_message || body?.error || 'Request failed';

        // 401 and 403 are never retried: a bad key stays bad.
        if (res.status === 401 || res.status === 403 || res.status === 404) {
          throw new BlockMarketScanError(message, res.status, body);
        }

        // 429 and 5xx are transient. Honour Retry-After when present.
        lastError = new BlockMarketScanError(message, res.status, body);
        if (attempt < this.retries) {
          const retryAfter = Number(res.headers.get('retry-after'));
          const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
            ? retryAfter * 1000
            : 2 ** attempt * 500;
          await new Promise((resolve) => setTimeout(resolve, waitMs));
          continue;
        }
      } catch (error) {
        if (error instanceof BlockMarketScanError) throw error;
        lastError = error;
        if (attempt < this.retries) {
          await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 500));
          continue;
        }
      } finally {
        clearTimeout(timer);
      }
    }

    throw lastError;
  }

  // ----------------------------------------------------- CoinMarketCap shape

  /** Id map. */
  getCryptoMap({ start, limit, sort, symbol } = {}) {
    return this._fetch('/v1/cryptocurrency/map', { start, limit, sort, symbol });
  }

  /** Metadata: logo, description, links, contract addresses. */
  getCryptoInfo({ id, slug, symbol, address } = {}) {
    return this._fetch('/v2/cryptocurrency/info', { id, slug, symbol, address });
  }

  /** Ranked listings with live quotes. */
  getListingsLatest({ start, limit, sort, sortDir } = {}) {
    return this._fetch('/v3/cryptocurrency/listings/latest', {
      start, limit, sort, sort_dir: sortDir,
    });
  }

  /** Newly listed assets. */
  getListingsNew({ start, limit } = {}) {
    return this._fetch('/v1/cryptocurrency/listings/new', { start, limit });
  }

  /** Live quotes for specific assets. */
  getQuotesLatest({ id, slug, symbol, address } = {}) {
    return this._fetch('/v3/cryptocurrency/quotes/latest', { id, slug, symbol, address });
  }

  /** Exchange and DEX pairs for a token. */
  getMarketPairs({ id, slug, symbol, limit } = {}) {
    return this._fetch('/v2/cryptocurrency/market-pairs/latest', { id, slug, symbol, limit });
  }

  /** Latest candle. Synthesised from the live price when no candle is stored. */
  getOhlcvLatest({ id, slug, symbol } = {}) {
    return this._fetch('/v2/cryptocurrency/ohlcv/latest', { id, slug, symbol });
  }

  /** Historical candles. */
  getOhlcvHistorical({ id, slug, symbol, timeStart, timeEnd, count } = {}) {
    return this._fetch('/v2/cryptocurrency/ohlcv/historical', {
      id, slug, symbol, time_start: timeStart, time_end: timeEnd, count,
    });
  }

  /** Price and percent changes over multiple windows. */
  getPricePerformance({ id, slug, symbol } = {}) {
    return this._fetch('/v2/cryptocurrency/price-performance-stats/latest', { id, slug, symbol });
  }

  /** Category list. */
  getCategories({ limit } = {}) {
    return this._fetch('/v1/cryptocurrency/categories', { limit });
  }

  /** Tokens within one category. */
  getCategory({ id, start, limit, sort, sortDir } = {}) {
    return this._fetch('/v1/cryptocurrency/category', {
      id, start, limit, sort, sort_dir: sortDir,
    });
  }

  /** Trending by activity. */
  getTrendingLatest(limit = 20) {
    return this._fetch('/v1/cryptocurrency/trending/latest', { limit });
  }

  /** Top gainers and losers together. */
  getGainersLosers(limit = 20) {
    return this._fetch('/v1/cryptocurrency/trending/gainers-losers', { limit });
  }

  /** Lightweight price lookup: the cheapest call for a price. */
  getSimplePrice({ id, slug, symbol } = {}) {
    return this._fetch('/v1/simple/price', { id, slug, symbol });
  }

  /** Global market metrics. Aggregates, refreshed on the ingest cycle. */
  getGlobalMetrics() {
    return this._fetch('/v1/global-metrics/quotes/latest');
  }

  // ------------------------------------------------- BlockMarketScan native

  /**
   * Token list with filters.
   * @param {Object} o
   * @param {number} [o.page=1]
   * @param {number} [o.limit=100]      Max 200.
   * @param {string} [o.sort=market_cap] market_cap, price_usd, volume_24h,
   *   percent_change_1h, percent_change_24h, percent_change_7d, cmc_rank, name, symbol
   * @param {string} [o.order=desc]     asc or desc
   * @param {string} [o.search]         Name, symbol, or contract address
   * @param {string} [o.chain]          Any of 460 networks: "ethereum", "bsc",
   *   "base", "solana", "hyperevm". Aliases resolve, so "BNB" and
   *   "binance-smart-chain" are the same filter.
   * @param {string} [o.category]       defi, rwa, meme, gamefi, ai, stablecoins,
   *   layer1, layer2, depin, nft, exchange, privacy, oracle, payments, altcoins
   * @param {boolean} [o.newOnly]
   */
  getTokens({ page, limit, sort, order, search, chain, category, newOnly } = {}) {
    const params = { page, limit, sort, order, search, chain, category };
    if (newOnly) params.new = 'true';
    return this._fetch('/tokens', params);
  }

  /** One token by slug or UUID, with pairs and full metadata. */
  getToken(idOrSlug) {
    return this._fetch('/tokens/' + encodeURIComponent(idOrSlug));
  }

  /** OHLCV for one token, by UUID. */
  getOHLCV(tokenId) {
    return this._fetch('/tokens/' + encodeURIComponent(tokenId) + '/ohlcv');
  }

  /** Compact price rows for many tokens at once, keyed by token id. */
  getPriceSnapshot(tokenIds = []) {
    return this._fetch('/prices/snapshot', {
      ids: Array.isArray(tokenIds) ? tokenIds.join(',') : tokenIds,
    });
  }

  /**
   * Global stats. Field names are short and not the CMC ones:
   * { totalTokens, totalMcap, totalVolume, btcDom, ethDom }
   */
  getStats() {
    return this._fetch('/stats');
  }

  // ---------------------------------------------------------- convenience

  search(query) {
    return this.getTokens({ search: query });
  }

  getTopGainers(limit = 20) {
    return this.getTokens({ sort: 'percent_change_24h', order: 'desc', limit });
  }

  getTopLosers(limit = 20) {
    return this.getTokens({ sort: 'percent_change_24h', order: 'asc', limit });
  }

  getNewlyLaunched(limit = 50) {
    return this.getTokens({ newOnly: true, limit });
  }

  getByChain(chain, limit = 100) {
    return this.getTokens({ chain, limit });
  }

  getByCategory(category, limit = 100) {
    return this.getTokens({ category, limit });
  }

  /**
   * Poll a set of symbols and call back whenever a price changes.
   * Returns a stop function. Default cadence stays inside the 120 req/min limit.
   */
  watchPrices(symbols, onUpdate, intervalMs = 15000) {
    const list = Array.isArray(symbols) ? symbols : [symbols];
    let stopped = false;
    let previous = {};

    const tick = async () => {
      if (stopped) return;
      try {
        const res = await this.getQuotesLatest({ symbol: list.join(',') });
        const changed = {};
        Object.entries(res.data || {}).forEach(([key, token]) => {
          const price = token?.quote?.USD?.price;
          if (price != null && price !== previous[key]) {
            previous[key] = price;
            changed[key] = token;
          }
        });
        if (Object.keys(changed).length) onUpdate(changed, res);
      } catch (error) {
        onUpdate(null, null, error);
      }
    };

    void tick();
    const timer = setInterval(tick, intervalMs);
    return () => { stopped = true; clearInterval(timer); };
  }
}

if (typeof module !== 'undefined' && module.exports) {
  module.exports = BlockMarketScan;
  module.exports.BlockMarketScan = BlockMarketScan;
  module.exports.BlockMarketScanError = BlockMarketScanError;
}
if (typeof window !== 'undefined') {
  window.BlockMarketScan = BlockMarketScan;
  window.BlockMarketScanError = BlockMarketScanError;
}