@molecule/api-crypto-prices-coingecko

CoinGecko crypto-prices provider for molecule.dev.

Implements the CryptoPricesProvider interface against the CoinGecko v3 API. The public endpoint (https://api.coingecko.com/api/v3) is keyless and free for personal / non-commercial use, with conservative rate-limits. Setting the COINGECKO_API_KEY environment variable switches to the Pro endpoint (https://pro-api.coingecko.com/api/v3) and authenticates with the x-cg-pro-api-key header.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider } from '@molecule/api-crypto-prices'
import { provider } from '@molecule/api-crypto-prices-coingecko'

setProvider(provider)

Type

provider

Installation

npm install @molecule/api-crypto-prices-coingecko @molecule/api-crypto-prices

API

Interfaces

CoinGeckoCryptoPricesConfig

Configuration options for the CoinGecko crypto-prices provider.

The CoinGecko public API (https://api.coingecko.com/api/v3) is keyless and free for personal / non-commercial use, so all fields are optional. Setting apiKey switches the provider to the CoinGecko Pro endpoint (https://pro-api.coingecko.com/api/v3) and authenticates with the x-cg-pro-api-key header.

interface CoinGeckoCryptoPricesConfig {
  /**
   * Base URL override. Defaults to `'https://api.coingecko.com/api/v3'` when
   * `apiKey` is omitted, or `'https://pro-api.coingecko.com/api/v3'`
   * when `apiKey` is set.
   */
  baseUrl?: string

  /**
   * CoinGecko Pro API key. When set, the provider uses the Pro host and
   * sends the `x-cg-pro-api-key` header. The free public endpoint requires
   * no key.
   */
  apiKey?: string

  /**
   * Request timeout in milliseconds. Defaults to `10000`.
   */
  timeout?: number
}

Classes

CoinGeckoRateLimitedError

Error thrown by the CoinGecko provider when the upstream API rejects a request with HTTP 429 (Too Many Requests).

The error never includes the configured API key (or any other secret) in its message or properties.

class CoinGeckoRateLimitedError extends Error {
  /**
   * Stable error code: always `RATE_LIMITED`.
   */
  public readonly code: typeof RATE_LIMITED = RATE_LIMITED

  /**
   * Suggested wait, in seconds, parsed from the upstream `Retry-After`
   * header. `null` when the header was absent or unparseable.
   */
  public readonly retryAfterSeconds: number | null

  /**
   * Constructs a new `CoinGeckoRateLimitedError`.
   *
   * @param message - Human-readable description of the rate-limit event.
   * @param retryAfterSeconds - Suggested wait before retrying, in seconds.
   */
  public constructor(message: string, retryAfterSeconds: number | null) {
    super(message)
    this.name = 'CoinGeckoRateLimitedError'
    this.retryAfterSeconds = retryAfterSeconds
  }
}

Functions

createProvider(config)

Creates a CoinGecko crypto-prices provider.

function createProvider(config?: CoinGeckoCryptoPricesConfig): CryptoPricesProvider

• config — Provider configuration. All fields are optional.

Returns: A CryptoPricesProvider backed by the CoinGecko v3 API.

Constants

provider

The provider implementation, lazily initialized on first use.

Reads COINGECKO_API_KEY and COINGECKO_BASE_URL from environment variables. When COINGECKO_API_KEY is set the provider routes traffic to the Pro endpoint and authenticates with the x-cg-pro-api-key header; the public free tier requires no key.

const provider: CryptoPricesProvider

RATE_LIMITED

Stable error code emitted by the CoinGecko provider when the upstream API returns HTTP 429 (Too Many Requests).

Catch on this constant rather than parsing error messages — the message text is for humans only.

const RATE_LIMITED: 'RATE_LIMITED'

Core Interface

Implements @molecule/api-crypto-prices interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-crypto-prices'
import { provider } from '@molecule/api-crypto-prices-coingecko'

export function setupCryptoPricesCoingecko(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-crypto-prices ^1.0.1

Environment Variables

• COINGECKO_API_KEY (optional) — CoinGecko Pro API key
  • Setup: Optional. Leave unset to use the free keyless public endpoint (conservative rate limits). Set a Pro key to switch to pro-api.coingecko.com with higher limits.
  • Get it here: https://www.coingecko.com/en/api/pricing
  • Example: CG-...

Runtime Dependencies

• @molecule/api-crypto-prices

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

• A known coin's spot price renders in the UI: getPrice(id, 'usd') (id from listCoins()/listSupportedSymbols(), never a hardcoded provider id) returns a CoinPriceQuote with a PLAUSIBLE price (BTC is thousands of USD, not 0/null/NaN) and it shows on screen, not "—".
• The market list shows DISTINCT prices: listCoins() renders multiple CoinMarketRows and each coin's price is its own value (BTC ≠ ETH, not a repeated copy), with symbol/name matching the row.
• If a chart/detail screen is exposed, getHistorical(id, days) returns a series of CoinPricePoint (ts, price) samples in chronological order that render as a line/spark chart — not a single point or an empty box.
• Switching the quote currency (USD→EUR) re-fetches with the new vsCurrency and the displayed values CHANGE, shown with the right symbol and precision ($/€, not a raw float).
• Prices refresh: a later getPrice/listCoins can return a different price/change24h and the UI updates (or shows an "as of" time from asOf) — it isn't frozen at first paint.
• Edge/error: an unknown coin id or symbol surfaces a clear "not found" in the UI, and a provider/rate-limit failure degrades gracefully (stale-but- shown or an empty state) — never a crash, blank, or NaN.
• The provider API key (if the bonded provider needs one) stays server-side: the browser calls the app's own endpoint, never the upstream API directly, and that endpoint isn't an open proxy for arbitrary coin/currency params.