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

# Sentiment and Narratives

> The crowd's read on 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

> [tab] 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] 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] AI agent
>
> Connect the [MCP server](https://shumi.mintlify.site/agents/mcp.md) 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.

## 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 running out of steam. Often near a top |

`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](https://shumi.mintlify.site/trade-decisions/signals.md) 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` |

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


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