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

> Rank the day's biggest movers, or filter the tracked coins by trend, category and market cap.

`shumi scan` ranks the tracked coins or filters them by trend, category and market cap. Use it to find today's biggest gainers and losers, or a short list of coins in the trend you want. On the web, ask in chat: "what's pumping today?"

## Find the biggest movers

<Tabs>
  <Tab title="Terminal">
    ```bash theme={"dark"}
    shumi scan --sort change24h --limit 10              # top 24h gainers
    shumi scan --sort change24h --order asc --limit 10  # top 24h losers
    shumi scan --sort change7d --limit 10               # top 7d gainers
    ```

    Each row carries the move:

    ```json theme={"dark"}
    {"name": "PHALA", "symbol": "pha", "change_24h_pct": 40.59, "change_7d_pct": 144.28, "lowConfidence": false}
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={"dark"}
    curl "https://api.shumi.ai/api/cli/scan?sortBy=change24h&sortOrder=desc&limit=10" \
      -H "Authorization: Bearer shumi_sk_your_key_here"
    ```
  </Tab>

  <Tab title="AI agent">
    Use the `scan_coins` tool with `sort_by: "change24h"`. Add `sort_order: "asc"` for the losers.
  </Tab>
</Tabs>

These need CLI 0.9.1 or `@shumi-ai/mcp` 1.2.1 or later. `shumi version` shows yours.

## Filter by trend, category and size

```bash theme={"dark"}
shumi scan --category Meme --trend UP --limit 5
```

Returns `["Shiba Inu","Pepe","Pudgy Penguins", ...]`.

| CLI flag | API parameter | What it does |
| - | - | - |
| `--trend` | `trend` | `UP`, [`HODL`](/research/market-health#count-the-coins-trending-up-sideways-or-down) or `DOWN` |
| `--interval` | `interval` | Judge the trend on the daily (`1d`, default) or weekly (`1w`) chart |
| `--category` | `categories` | One category, by the name `shumi category list` prints |
| `--mcap-min`, `--mcap-max` | `marketCapMin`, `marketCapMax` | Market cap bounds in US dollars. `100000000` is \$100M |
| `--limit` | `limit` | Stop after that many rows |

Category names match whatever the case or spacing: `layer 2` finds `Layer-2`, and `DeFi` finds `Decentralized Finance (DeFi)`. An unknown name returns an error that points to `shumi category list`.

## Choose the ranking

`--sort` (API `sortBy`) picks what to rank by. `--order` (API `sortOrder`) is `desc` for largest first, the default, or `asc` for smallest first.

| `--sort` | Ranks by | Each row |
| - | - | - |
| `marketCap` (default) | Market cap | The coin name |
| `change24h` | 24h price change | `name`, `symbol`, `change_24h_pct`, `change_7d_pct`, `lowConfidence` |
| `change7d` | 7d price change | Same as `change24h` |
| `streak` | Days in the current trend (weeks with `--interval 1w`) | `name`, `symbol`, `trend`, `streak`, `streakCapped` |
| `price` | Price | `name`, `symbol`, `price_usd` |

* **The sort runs first, then the filters.** `--sort change24h --trend UP --limit 10` gives the ten biggest 24h gainers that are in an uptrend.
* **The change sorts start at \$50M market cap**, so thin micro-caps do not fill the top. Pass `--mcap-min 0` to include them, or set your own floor. With `--mcap-max` below \$50M the floor is off.
* **`change_24h_pct` is the same number** [Coin Lookup](/research/coin-analysis) shows for that coin.
* **`lowConfidence: true`** marks a move over 100% on a price fewer than three exchanges quote. Check it before you act on it.
* **`streakCapped: true`** means the run is at least 400 days long (three years on the weekly), and may be longer.
* A coin with no value for the sort key comes last.

## Check a coin from the list

The next commands take a ticker. A sorted scan gives you the `symbol`. For a name-only list, `shumi coin by-name Ethereum` returns the coin with its `symbol` (`eth`). Then:

* `shumi coin lookup ETH` for the current trend and the exchanges with the most volume, or `shumi coin risk ETH` for price, funding and trend ([Coin Lookup](/research/coin-analysis)).
* `shumi signal ETH` for a verdict ([Signals](/trade-decisions/signals)).

If you screen for one direction, check [Market State](/research/market-health#count-the-coins-trending-up-sideways-or-down) first to see how many coins share that trend across the market.


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