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

# Market State

> How many coins are trending up, sideways or down, whether the market has flipped, BTC dominance, and the regime signal log.

Four commands under `shumi market` and `shumi regime` answer "what is the whole market doing": breadth counts, a flip check, market totals and the regime signal log. For a one-word answer, run `shumi market health --context` and read `summary` and `regimeAge.dominant`: which side is winning and for how many days. The plain call gives the counts behind it.

## Count the coins trending up, sideways or down

<Tabs>
  <Tab title="Terminal">
    ```bash theme={"dark"}
    shumi market health
    ```

    Add `--context` for the fuller bundle described below.
  </Tab>

  <Tab title="API">
    ```bash theme={"dark"}
    curl "https://api.shumi.ai/api/cli/market/health" \
      -H "Authorization: Bearer shumi_sk_your_key_here"
    ```

    Add `?context=1` for the fuller bundle.
  </Tab>

  <Tab title="AI agent">
    Connect the [MCP server](/agents/mcp) and call `get_market_health`, with `context: true` for the fuller bundle.
  </Tab>
</Tabs>

The plain call returns the coin count in each trend state, refreshed every 5 minutes:

```json theme={"dark"}
"trends": {"UP": 410, "HODL": 387, "DOWN": 194}
```

`UP` and `DOWN` are coins in a daily uptrend or downtrend. `HODL` means the coin's trend disagrees across quote currencies (up in dollars, down against BTC, for example), so it counts as sideways. `hasExtremes` and `extremes` list extreme movers when there are any.

`--context` adds the dollar-only view, which counts UP and DOWN only, plus the fields below. Read `summary` first, then `regimeAge` and `stressIndicator`.

| Field | What it tells you |
| - | - |
| `summary` | One line, e.g. "USD-leg UP-dominant for 5d. 22% down on the USD leg. BTC/ETH/SOL USD-legs aligned." |
| `breadthVelocity` | Today's `UP` and `DOWN` counts with `upPct`, the change since yesterday (`delta`), how many coins `flipped`, and the same share `monthAgo` |
| `regimeAge` | Which side is `dominant`, for how many `days`, `since` which date, and the `previousDominant` |
| `leadership` | BTC, ETH and SOL: `trend`, `streakDays` and whether each is `alignedWithMarket` |
| `stressIndicator` | A `level` (for example `low`) and a `score` from three sensors: breadth, leadership and regime fragility |

## Check whether the market has flipped

```bash theme={"dark"}
shumi market crossing
```

API: `GET /api/cli/market/crossing`. Agent tool: `get_market_crossing`.

A crossing is one trend group overtaking another across the market, for example DOWN coins outnumbering UP coins. When none has fired you get an empty `crossings` list and `"message": "No crossing detected"`.

## Get BTC dominance and market totals

```bash theme={"dark"}
shumi market global
```

API: `GET /api/cli/market/global`. Agent tool: `get_global_market`.

| Field | Meaning |
| - | - |
| `totalMarketCap` | Total crypto market cap, keyed by currency. Read `.usd` |
| `totalMarketVolume` | 24h volume, same keys |
| `marketCapPercentage` | Share of market cap by coin. `btc` is BTC dominance, for example 58.7. `eth`, `usdt` and others are listed too |

## Read the regime signal log

<Tabs>
  <Tab title="Terminal">
    ```bash theme={"dark"}
    shumi regime signals
    shumi regime history BTC
    ```

    Bare `shumi regime` prints help only.
  </Tab>

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

    Use `action=history&symbol=BTC` for one coin.
  </Tab>

  <Tab title="AI agent">
    Call `get_regime` with `view: "signals"`, or with `symbol` for one coin's history.
  </Tab>
</Tabs>

The regime model tracks long trades. The log shows it entering when price touches the lower band of its range and leaving at the upper band, on a time stop or on a stop loss. `long_entry` means the model opened a long. `long_exit` means it closed at the upper band, in profit or not. `time_stop_long` means it ran out of time. `exit_long_stop` means it hit its stop.

`regime signals` lists those entries and exits, newest first, 20 per call. `data.meta.total` holds the full count (106 at the time of writing).

| Field | Meaning |
| - | - |
| `symbol` | Coin |
| `signalType` | `long_entry`, `long_exit`, `time_stop_long` or `exit_long_stop` |
| `signalDate`, `price` | When it fired and at what price |
| `rsiValue` | RSI at the signal. Set on entries, empty on exits |
| `bandTouched` | `lower` on entries, `upper` on exits, empty on stops |
| `regimeAtSignal`, `regimeDays` | The regime the coin was in and how long it had held |
| `confluenceScore` | Confluence count, 0 or 1 in recent output |

`regime history BTC` returns that coin's tracked outcomes, in `trades`, and `currentPosition`, which is empty when no entry is open. Each outcome has:

| Field | Meaning |
| - | - |
| `direction` | `long` or `short` |
| `entryDate`, `entryPrice` | When and where the entry was tracked |
| `exitDate`, `exitPrice`, `exitReason` | When, where and why it closed |
| `returnPct`, `holdDays` | The return and how long it ran |

For "is the market up or down right now", use `market health --context` and `market crossing` above.


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