# cryptoprice

cryptoprice reads public cryptocurrency data from CoinGecko: whether
the API is up, what coins cost right now, the full record for a single
coin, the complete coin list, search across coins and exchanges,
historical market charts, the global market picture, and what is
trending. One binary serves a command-line interface and a stdio MCP
server.

No API key is needed. CoinGecko's free tier is keyless, so cryptoprice
works with nothing configured. If you do have a demo key, set
`COINGECKO_API_KEY` and it will be sent as the `x-cg-demo-api-key`
header; when the variable is absent or empty, no key header is sent
and nothing fails for lack of a key. Free-tier rate limits apply to
upstream calls.

## Install

```bash
npx @reneturcios/cryptoprice ping
```

Or run the container image:

```bash
docker run -i ghcr.io/cloudcorprecords/cryptoprice
```

The container defaults to the MCP server (see below). Pass CLI
arguments to use it as a CLI instead.

## CLI

```bash
cryptoprice ping
cryptoprice price bitcoin,ethereum usd,eur --change
cryptoprice coin bitcoin
cryptoprice coins --platform
cryptoprice search "wrapped bitcoin"
cryptoprice chart ethereum eur 30
cryptoprice global
cryptoprice trending

cryptoprice --version
```

Each command prints the upstream JSON payload. Exit codes: `0` on
success, `1` when a call fails (including an upstream API error such
as a rate limit), `2` for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:

```bash
npx -y @reneturcios/cryptoprice mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "cryptoprice": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cryptoprice", "mcp"]
    }
  }
}
```

### Tools

| Tool | Input | What it returns |
| --- | --- | --- |
| `ping` | (none) | The CoinGecko API status. |
| `get_price` | `ids`, `vs_currencies` (required), `include_24hr_change` (optional) | Current prices, optionally with 24h change. |
| `get_coin` | `id` (required) | Full data for one coin: description, links, and market data. |
| `list_coins` | `include_platform` (optional) | All coins with IDs, symbols, and names. |
| `search_coins` | `query` (required) | Coins, exchanges, and categories matching the query. |
| `get_market_chart` | `id`, `vs_currency`, `days` (required) | Historical prices, market caps, and volumes. |
| `get_global_data` | (none) | Total market cap, volume, and dominance. |
| `get_trending` | (none) | Trending coins, NFTs, and categories. |

All calls use the CoinGecko API under
`https://api.coingecko.com/api/v3`. Identifiers such as `ids` and
`id` are CoinGecko IDs (for example `bitcoin`), not symbols.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.