> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shumi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Quickstart

> Get an API key, call the Shumi API from your own code, and add the MCP server to your AI agent.

Get an API key, make your first call and connect an AI agent. For the web chat and the first terminal commands, start on the [Overview](/).

## Get an API key

Keys come from the CLI. Needs Node 22 or later.

```bash theme={"dark"}
npm install -g shumi
shumi login
shumi keys create my-bot
```

`shumi login` opens your browser to sign in. `shumi keys create` prints a key that starts with `shumi_sk_`. `shumi keys list` shows your keys and `shumi keys revoke <prefix>` removes one.

## Call the API

Every route sits under `https://api.shumi.ai/api/cli` and takes the key as a Bearer token.

```bash theme={"dark"}
curl "https://api.shumi.ai/api/cli/signal/BTC" \
  -H "Authorization: Bearer shumi_sk_your_key_here"
```

Some examples use `$SHUMI_TOKEN` for your key: `export SHUMI_TOKEN=shumi_sk_your_key_here`.

The [API Overview](/api-reference/introduction) and the endpoint reference in the sidebar list every route.

## What a call costs

On the free plan each call counts as one question: 10 to start, then 1 per day. After that the API answers `402 Payment Required` and offers pay per call in USDC. See [Plans and Quotas](/platform/access) and [Pay Per Call](/agents/payments).

## Read the response

Every data route except the plain-word question route answers in the same envelope.

```json theme={"dark"}
{
  "schemaVersion": 1,
  "data": { "symbol": "BTC", "verdict": "strong-bull", "score": 3.5, "confidence": "high" },
  "meta": {
    "ts": "2026-09-23T13:46:57.027Z",
    "route": "signal/BTC",
    "as_of": "2026-09-23T13:46:56.725Z",
    "data_age_seconds": 0
  }
}
```

| Field | Meaning |
| - | - |
| `data` | The result. Its shape depends on the route |
| `meta.ts` | When the response was built |
| `meta.as_of` | When the data behind it was last updated |
| `meta.data_age_seconds` | How old that data is, in seconds |

Check `meta.data_age_seconds` before you act on a price or a funding rate. [Coverage](/platform/coverage#how-fresh-the-data-is) lists how often each kind of data refreshes.

## Add Shumi to an AI agent

The hosted MCP server needs nothing installed. Send the key as a header.

```bash theme={"dark"}
claude mcp add --transport http shumi https://mcp.shumi.ai/mcp \
  --header "Authorization: Bearer shumi_sk_your_key_here"
```

In Claude, choose **Add custom connector**, open the request headers and enter URL `https://mcp.shumi.ai/mcp`, header name `Authorization`, header value `Bearer shumi_sk_your_key_here`.

To run the server on your own machine, the package is `@shumi-ai/mcp` and the key goes in `SHUMI_TOKEN`:

```bash theme={"dark"}
claude mcp add shumi -e SHUMI_TOKEN=shumi_sk_your_key_here -- npx -y @shumi-ai/mcp
```

Restart the client. Tools such as `get_coin_risk`, `scan_coins` and `ask_shumi` appear. [MCP Server](/agents/mcp) lists them all and shows the JSON config for Claude Desktop and Cursor.

To script the terminal, see [CLI](/agents/cli).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.