# coinglecko

[![Package Version](https://img.shields.io/hexpm/v/coinglecko)](https://hex.pm/packages/coinglecko)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/coinglecko/)

A type-safe [CoinGecko API](https://docs.coingecko.com/) client for Gleam.

Works on both **Erlang** and **JavaScript** targets.

## Installation

```sh
gleam add coinglecko@1
```

You also need an HTTP client for your target:

```sh
# Erlang
gleam add gleam_httpc@5

# JavaScript
gleam add gleam_fetch@1
```

## Quick Start (Erlang)

```gleam
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`:

```gleam
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:

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

## API Key

Get a free API key at [coingecko.com/en/api](https://www.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

```sh
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>.