# coinintel

coinintel wraps a read-only crypto market-intelligence API:
finding and resolving coins, current prices and history,
per-coin sentiment, risk and signals, market-wide health,
sentiment and regime reads, trend and coin scans, narratives,
categories, and funding momentum and alerts. One binary serves
a command-line interface and a stdio MCP server.

An API key is required. Set `SHUMI_TOKEN` before use; when it
is missing or blank, every tool fails with an error naming
`SHUMI_TOKEN` before any request is made. The key is sent as
the `x-api-key` header. The API base URL can be overridden
with `SHUMI_API_URL`; when it is not set, calls go to
`https://api.shumi.ai` (a reconstruction — the upstream README
does not publish a base URL).

List-returning tools share a convention: `top` (an integer)
keeps only the first N entries, and `fields` (a comma-separated
list of names) keeps only those fields on each entry. Both are
sent to the API, and the same trimming is applied to array
responses locally.

This build is a labelled core subset: 20 read-only tools. The
upstream tool set also documents signal-quality, pair
suggestions, real-world-asset, unlock, holder, wallet, futures,
basket, transcript, question-answering, and web-search tools;
those are not part of this subset.

## Install

```bash
npx @reneturcios/coinintel get_regime
```

Or run the container image:

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

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

## CLI

The subcommands mirror the MCP tool names:

```bash
export SHUMI_TOKEN=...

coinintel lookup_coin --query bitcoin
coinintel resolve_coin --query ether
coinintel get_prices --symbols BTC,ETH --top 2 --fields symbol,price
coinintel get_coin_historical --coin BTC --range 30d
coinintel get_coin_sentiment --coin BTC
coinintel get_coin_risk --coin BTC
coinintel get_global_market
coinintel get_market_health --top 5
coinintel scan_trends
coinintel scan_coins --fields symbol,score
coinintel list_narratives
coinintel get_narrative --narrative "ai tokens"
coinintel list_categories
coinintel get_category --category defi
coinintel get_funding_momentum
coinintel get_funding_alerts
coinintel get_regime
coinintel get_signal --coin BTC

coinintel --version
```

Results print the upstream JSON payload. Exit codes: `0` on
success, `1` when a call fails (including a missing token or an
upstream API error), `2` for usage errors.

## MCP server

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

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

MCP client configuration:

```json
{
  "mcpServers": {
    "coinintel": {
      "command": "npx",
      "args": ["-y", "@reneturcios/coinintel", "mcp"],
      "env": { "SHUMI_TOKEN": "..." }
    }
  }
}
```

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `lookup_coin` | `query` (required) | Look up coins matching a free-text query. |
| `resolve_coin` | `query` (required) | Resolve a query to a single canonical coin. |
| `get_prices` | `symbols` (required array), `top`, `fields` | Get current prices for symbols. |
| `get_coin_historical` | `coin` (required), `range`, `top`, `fields` | Get historical data for a coin. |
| `get_coin_sentiment` | `coin` (required), `top`, `fields` | Get sentiment data for a coin. |
| `get_coin_risk` | `coin` (required) | Get the risk assessment for a coin. |
| `get_global_market` | `top`, `fields` | Get global market overview data. |
| `get_market_health` | `top`, `fields` | Get market health indicators. |
| `get_market_sentiment` | `top`, `fields` | Get aggregate market sentiment. |
| `get_market_crossing` | `top`, `fields` | Get market crossing signals. |
| `scan_trends` | `top`, `fields` | Scan for current market trends. |
| `scan_coins` | `top`, `fields` | Scan coins against market criteria. |
| `list_narratives` | `top`, `fields` | List market narratives. |
| `get_narrative` | `narrative` (required) | Get a single market narrative. |
| `list_categories` | `top`, `fields` | List coin categories. |
| `get_category` | `category` (required) | Get a single coin category. |
| `get_funding_momentum` | `top`, `fields` | Get funding-rate momentum data. |
| `get_funding_alerts` | `top`, `fields` | Get funding-rate alerts. |
| `get_regime` | (none) | Get the current market regime. |
| `get_signal` | `coin` (required) | Get the trading signal for a coin. |

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