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

# Sentiment and Narratives

> What the crowd is saying about a coin or the market, which categories are heating up, and which narratives are active.

Shumi reads news, social posts and video transcripts every hour and writes short summaries: one for the market, one per coin, one per category and one per narrative.

## Get a sentiment read

<Tabs>
  <Tab title="Terminal">
    ```bash theme={"dark"}
    shumi sentiment coin BTC
    shumi sentiment market
    shumi sentiment slopes
    ```

    Other views: `latest`, `summary`, `narratives`, `categories`, `health`, `entity-slopes`, `category <name>`, `narrative <name>`.
  </Tab>

  <Tab title="API">
    ```bash theme={"dark"}
    curl "https://api.shumi.ai/api/cli/sentiment?action=coin&symbol=BTC" \
      -H "Authorization: Bearer shumi_sk_your_key_here"
    ```

    `action` takes any view above. Add `name` for `category` and `narrative`.
  </Tab>

  <Tab title="AI agent">
    Connect the [MCP server](/agents/mcp) and call `get_coin_sentiment` with `symbol`, `get_market_sentiment` with `view` set to `market`, `latest`, `summary`, `narratives`, `categories`, `slopes`, `entity-slopes` or `health`, `get_category` with `view` set to `sentiment` for one category, and `get_narrative` for one narrative.
  </Tab>
</Tabs>

## Read a coin summary and its stance

`sentiment coin BTC` returns:

| Field                  | Meaning                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| `summary`              | One written read covering a rolling month, from `analysis_start_time` to `analysis_end_time` (`interval` `1m`) |
| `total_items_analyzed` | How many items it read, for example 10,401 for BTC                                                             |
| `sources`              | What it drew on, each with `url`, `title` and `source`                                                         |
| `stance`               | The crowd's stance                                                                                             |

The stance is one word, and it can be empty:

| Stance         | Plain meaning                                   |
| -------------- | ----------------------------------------------- |
| `accumulation` | Buyers building positions. Bullish              |
| `capitulation` | Panic selling that has run out. Often a bottom  |
| `neutral`      | No lean                                         |
| `distribution` | Holders selling into strength. A topping sign   |
| `euphoria`     | Late crowd excitement. Bearish for a contrarian |
| `exhaustion`   | Trend tired, usually a top, but unclear         |

`sentiment market` returns the last nine hourly market summaries plus the rolling monthly one, each with a stance when one is set. The [signal verdict](/trade-decisions/signals) scores the stance directly.

## See which categories are heating up

`sentiment slopes` returns 24 categories:

| Field                    | Meaning                                                                     |
| ------------------------ | --------------------------------------------------------------------------- |
| `category`               | e.g. "Prediction Markets", "Memecoins", "RWA"                               |
| `slope`                  | Rate of change of the sentiment score over recent days. Positive is warming |
| `mean_score`             | Average score over the window                                               |
| `row_count`, `day_count` | How many summaries and days feed it                                         |
| `signal`                 | `BUILDING`, `FLAT`, `DECLINING` or `INSUFFICIENT_DATA`                      |

In the example 14 of 24 were `INSUFFICIENT_DATA`, meaning no reading.

## List active narratives

```bash theme={"dark"}
shumi narratives
shumi narratives "RWA Tokenization"
```

API: `GET /api/cli/narratives`. Agent tools: `list_narratives`, and `get_narrative` with `name`.

A narrative is a theme the crowd is talking about, such as "Institutional BTC Accumulation". `total_count` was 186 in the example. Each item has:

| Field                       | Meaning                                                       |
| --------------------------- | ------------------------------------------------------------- |
| `narrative_name`, `summary` | The theme and a written summary                               |
| `freshness_score`           | Higher is fresher                                             |
| `attention_state.stage`     | `emerging`, `established` or `fading`                         |
| `attention_state.z_score`   | How far current attention sits above the theme's own baseline |

Narrative stages and category slope signals are separate labels on separate data. In the example "Memecoin Market" was `fading` while the Memecoins category slope read `BUILDING`.