coinglecko

A type-safe CoinGecko API client for Gleam.

Works on both Erlang and JavaScript targets.

Installation

gleam add coinglecko@1

You also need an HTTP client for your target:

# Erlang
gleam add gleam_httpc@5

# JavaScript
gleam add gleam_fetch@1

Quick Start (Erlang)

import coinglecko/client
import coinglecko/ping
import coinglecko/simple
import gleam/httpc
import gleam/io
import gleam/option.{None}
import gleam/result
import gleam/string

pub fn main() {
  let send = fn(req) { httpc.send(req) |> result.map_error(string.inspect) }
  let client = client.new_demo(api_key: "CG-your-key-here")

  // Check server status
  let assert Ok(pong) = ping.check(client, send:)
  io.println(pong.gecko_says)

  // Get Bitcoin price in USD
  let assert Ok(prices) = simple.price(
    client,
    ids: ["bitcoin"],
    vs_currencies: ["usd"],
    include_market_cap: None,
    include_24hr_vol: None,
    include_24hr_change: None,
    include_last_updated_at: None,
    precision: None,
    send:,
  )
}

JavaScript Usage

On JavaScript, use the request-building and decoding functions directly with gleam_fetch:

import coinglecko/client
import coinglecko/ping
import gleam/fetch
import gleam/javascript/promise

pub fn main() {
  let client = client.new_demo(api_key: "CG-your-key-here")

  // Build request (no HTTP call)
  let assert Ok(req) = ping.check_request(client)

  // Send with fetch (async)
  use resp <- promise.try_await(fetch.send(req))
  use body <- promise.try_await(fetch.read_text_body(resp))

  // Decode response
  let assert Ok(pong) = ping.decode_response(body.body)
  promise.resolve(Ok(pong))
}

Available Modules

Module	Description
`coinglecko/client`	Client construction (`new_demo`, `new_pro`)
`coinglecko/error`	Error types (`CoinGeckoError`)
`coinglecko/ping`	Server status check
`coinglecko/simple`	Current prices, supported currencies, token prices
`coinglecko/coins`	Coin list, markets, details, charts, OHLC, tickers, history, contract
`coinglecko/search`	Search coins/exchanges, trending coins
`coinglecko/global`	Global market data, DeFi data
`coinglecko/exchanges`	Exchange list, details, tickers
`coinglecko/categories`	Coin categories with market data
`coinglecko/asset_platforms`	Blockchain platform list
`coinglecko/nfts`	NFT collections, details, market charts
`coinglecko/derivatives`	Derivatives tickers, exchanges
`coinglecko/exchange_rates`	BTC exchange rates
`coinglecko/companies`	Public company treasury holdings
`coinglecko/pagination`	Page params, collect_all, collect_each
`coinglecko/rate_limit`	Rate limit header parsing
`coinglecko/retry`	Configurable retry with exponential backoff logic

Three-Layer API

Each endpoint provides three layers:

*_request(client, ...) – Builds an HTTP Request. Use this on JS or when you need full control.
decode_*(json_string) – Decodes a JSON response string. For testing or manual flows.
foo(client, ..., send:) – Convenience: builds, sends, and decodes in one call.

API Key

Get a free API key at coingecko.com/en/api.

Demo (free): client.new_demo(api_key: "CG-...")
Pro (paid): client.new_pro(api_key: "CG-...")

Error Handling

All API functions return Result(value, CoinGeckoError):

HttpError(String) – Network/transport failures
ApiError(status, body, error_message) – Non-200 responses (error_message parsed from JSON when available)
DecodeError(json.DecodeError) – JSON decoding failures
RequestError(String) – URL construction failures

Development

gleam build                      # Compile (Erlang)
gleam build --target javascript  # Compile (JS)
gleam test                       # Run tests
gleam format                     # Format code

Further documentation can be found at https://hexdocs.pm/coinglecko.