coin-ids

(no submodules)

Purpose

Owns the curated mapping from uppercase ticker symbol (BTC, ETH, …) to the opaque CoinGecko coin id (bitcoin, ethereum, …) that the /simple/price endpoint requires. Without this translation step the provider would have to either fall back to CoinGecko's heavyweight /coins/list discovery endpoint (~10k entries, defeats tree-shaking) or ask every caller to learn CoinGecko's id convention — neither is acceptable for a slim sibling.

Features

Frozen COIN_IDS map covering the top 16 cryptos by market cap at landing (BTC, ETH, SOL, USDT, USDC, BNB, XRP, ADA, DOGE, DOT, AVAX, MATIC, LINK, UNI, ATOM, LTC).
Case-insensitive getCoinGeckoId(symbol) lookup returning string | undefined.
Zero runtime dependencies; pure data + a one-line lookup function.

Usage: Basic

import { getCoinGeckoId } from "@suaveplan/currency-provider-coingecko/coin-ids/coin-ids";

getCoinGeckoId("BTC"); // "bitcoin"
getCoinGeckoId("eth"); // "ethereum" — case-insensitive
getCoinGeckoId("ZZZ"); // undefined — unknown symbol

Usage: Advanced

The provider uses getCoinGeckoId as the proactive UNKNOWN_CURRENCY gate. Consumers can mirror the same pattern when composing their own filters before hitting the registry:

import {
 COIN_IDS,
 getCoinGeckoId,
} from "@suaveplan/currency-provider-coingecko/coin-ids/coin-ids";

function partitionSupported(symbols: readonly string[]): {
 supported: string[];
 unknown: string[];
} {
 const supported: string[] = [];
 const unknown: string[] = [];
 for (const symbol of symbols) {
  if (getCoinGeckoId(symbol) !== undefined) {
   supported.push(symbol);
  } else {
   unknown.push(symbol);
  }
 }
 return { supported, unknown };
}

// Iterate the full map when generating a UI dropdown:
const everyKnown = Object.keys(COIN_IDS);

API Reference

`COIN_IDS: Readonly<Record<string, string>>`

Frozen mapping from uppercase ticker (key) to CoinGecko coin id (value). Keys are always uppercase; mutation throws because the object is frozen.

`getCoinGeckoId(symbol: string): string | undefined`

Returns the CoinGecko coin id for the given symbol. The input is upper-cased before the lookup, so "btc" and "BTC" both resolve to "bitcoin". Returns undefined for any symbol not present in COIN_IDS. Does not throw.

Implementation Notes

The map is intentionally hand-curated rather than fetched at runtime: a sibling that issues a discovery call before every batch would (a) add a network round trip every consumer pays for once, (b) bloat the in-memory cache, and (c) couple this package's reliability to a second upstream endpoint whose response shape can drift. Adding a new symbol is a one-line PR; the trade-off is heavily skewed toward "type it in".

2.8 KiB Raw Blame History