# CLI Source: https://docs.shumi.ai/agents/cli Install the shumi command, sign in, create API keys and pull market data into scripts and agents. `shumi` puts every Shumi data route in your terminal. It prints readable text for you and JSON for scripts and agents. ## Install and sign in **1. Install** Needs Node 22 or later. ```bash theme={"dark"} npm install -g shumi ``` **2. Sign in** ```bash theme={"dark"} shumi login ``` This opens your browser. If the browser shows a connection error after you signed in, run `shumi login --paste` and paste that page's URL. `shumi logout` clears the stored credentials. **3. Check the setup** ```bash theme={"dark"} shumi init ``` It checks your login and the network and suggests the next commands. ## Get data | You want | Command | | - | - | | A verdict on one coin, with evidence | `shumi BTC` or `shumi signal BTC` | | Risk context for one coin | `shumi coin risk BTC` | | Which asset a ticker points to | `shumi resolve GOLD` | | Trend counts UP, [HODL](/research/market-health#count-the-coins-trending-up-sideways-or-down) and DOWN | `shumi market health` | | Live prices | `shumi market prices --symbols BTC,ETH,SOL` | | Today's biggest movers | `shumi scan --sort change24h --limit 10` | | Coins that match a filter | `shumi scan --category Meme --trend UP --limit 20` | | Where funding is hot or cold | `shumi funding momentum [--symbol ETH]` | | Sentiment on one coin | `shumi sentiment coin BTC` | | Two coins to trade against each other | `shumi pairs suggestions` | | A stock, metal or commodity perp | `shumi rwa lookup AAPL` | | A question in plain words | `shumi ask "is BTC funding crowded?"` | `shumi scan --sort` needs CLI 0.9.1 or later, and the current trend on `shumi coin lookup` needs 0.9.0. `shumi version` shows yours, and [Market Screener](/research/market-screener) covers every scan flag. `shumi help` prints the full grouped list and every command takes `--help`. On the Free plan each data command counts as one question. [Plans and Quotas](/platform/access) has the numbers. ## Use it in scripts and agents Output switches to JSON on its own when you pipe it, so `shumi market health | jq .data.trends` works with no flag. The JSON is the same envelope the [API](/api-reference/introduction) returns. | Flag or variable | What it does | | - | - | | `--json` | Force JSON on stdout | | `--agent` | JSON, no spinner, no colour, no update notice. Errors go to stderr as JSON | | `--fields ` | Keep only these top-level keys, comma separated | | `--top ` | Keep the first N items when the response is a list | | `--auto-pay` | Pay a per-call price without asking, up to `SHUMI_MAX_PRICE_USDC` (0.10 by default). See [Pay Per Call](/agents/payments) | | `SHUMI_TOKEN` | An API key, created with `shumi keys create` on a machine with a browser and copied to one without | ```bash theme={"dark"} shumi funding momentum --agent | jq '.data.assets[] | select(.tier == "hot")' ``` `shumi commands --json` prints a manifest of every command with its arguments, so an agent can discover what it can call. ## Run a bot or dashboard For a script, bot or dashboard that checks Shumi on a timer, poll the data commands for the numbers. Ask Shumi only when something changes. ```bash theme={"dark"} # On every tick: price, funding, trend and sentiment for each coin, as JSON shumi coin risk PAXG BTC ETH --json # Only when a trend flips, funding moves or price leaves your range shumi ask "BTC's daily trend just turned DOWN. What changed?" ``` * On Plus, these commands never use a question: `coin risk`, `market health`, `market prices`, `funding momentum` and `scan`. Poll them as often as you like. Anything that writes a fresh AI answer or reading can use one. That covers `ask`, `coin `, `search`, `tweets`, and the sentiment, signal, narrative and watch commands. * On Free every call counts, and `coin risk` with three coins is three calls. With several coins, also check each row for `error`. On Pro nothing counts. * `shumi ask` writes a full answer. It takes longer and uses one question on Free and Plus. Call it when something happens, not on a timer. * Exit code 3 means out of quota (`429` or `402`) and 5 means a server error. On either, wait before trying again and double the wait each time it fails. Retrying on the next tick hits the same limit. ## Create an API key A server, a bot or an [MCP client](/agents/mcp) needs a key instead of your login. ```bash theme={"dark"} shumi keys create my-bot shumi keys list shumi keys revoke ``` Keys start with `shumi_sk_`. `keys list` shows each key's prefix, and that is what `revoke` takes. A key carries the plan of the account that created it. ## Fix a problem ```bash theme={"dark"} shumi doctor ``` It checks the config file, the login token and its expiry, the network, the API and whether your version is current. `shumi billing tier` shows the plan the API applies to you. Both work when you are out of quota. # MCP Server Source: https://docs.shumi.ai/agents/mcp Give an AI agent Shumi's market data as MCP tools, hosted or run locally. The Shumi MCP server exposes the same data the [CLI](/agents/cli) and [API](/api-reference/introduction) return, as tools an AI agent can call. You need an API key: run `shumi login`, then `shumi keys create`. Connect to the hosted server at `https://mcp.shumi.ai/mcp`, or run the `@shumi-ai/mcp` package locally with `npx`. Both serve the same tools against the same account and quota. ## Connect your client **Claude (hosted)** In Claude, choose **Add custom connector**, open the request headers section and enter: | Field | Value | | - | - | | URL | `https://mcp.shumi.ai/mcp` | | Header name | `Authorization` | | Header value | `Bearer shumi_sk_...` | `x-api-key` with the bare key as the value also works. Everyone who uses this connector shares the one Shumi account behind the key, and its quota. **Claude Desktop** Add this to `claude_desktop_config.json` and restart the app. ```json theme={"dark"} { "mcpServers": { "shumi": { "command": "npx", "args": ["-y", "@shumi-ai/mcp"], "env": { "SHUMI_TOKEN": "shumi_sk_your_key_here" } } } } ``` **Claude Code** Local: ```bash theme={"dark"} claude mcp add shumi -e SHUMI_TOKEN=shumi_sk_your_key_here -- npx -y @shumi-ai/mcp ``` Hosted: ```bash theme={"dark"} claude mcp add --transport http shumi https://mcp.shumi.ai/mcp \ --header "Authorization: Bearer shumi_sk_your_key_here" ``` **Cursor** Add this to `~/.cursor/mcp.json` and restart the app. ```json theme={"dark"} { "mcpServers": { "shumi": { "command": "npx", "args": ["-y", "@shumi-ai/mcp"], "env": { "SHUMI_TOKEN": "shumi_sk_your_key_here" } } } } ``` > [!WARNING] > > Send the key as a header. Never put it in the URL. A URL is written to server logs, proxies and browser history. The local server reads three variables: | Variable | Required | What it does | | - | - | - | | `SHUMI_TOKEN` | Yes | Your API key | | `SHUMI_API_URL` | No | Point the server at a different API host | | `SHUMI_WALLET` | No | A wallet address to include in plain-word question context | `GET https://mcp.shumi.ai/health` answers without a key, so you can tell a bad key from a server that is down. A missing or wrong key on the hosted server comes back as a normal response carrying an `AUTH_REQUIRED` error. If the tools appear but every call returns `AUTH_REQUIRED`, check the header name and value. ## Call a tool There are 31 tools. 29 return data. `ask_shumi` and `search_web` return written answers. | You want | Tools | | - | - | | One coin | `get_coin_risk`, `lookup_coin`, `resolve_coin`, `get_coin_sentiment`, `get_coin_historical` | | The whole market | `get_market_health`, `get_global_market`, `get_market_crossing`, `get_prices`, `scan_trends`, `scan_coins` | | Sentiment and narratives | `get_market_sentiment`, `list_narratives`, `get_narrative`, `list_categories`, `get_category` | | Funding, regime and signals | `get_funding_momentum`, `get_funding_alerts`, `get_regime`, `get_signal`, `get_signal_quality`, `get_futures_signals` | | Pairs | `get_pair_suggestions` | | Stocks, metals, commodities, indices and FX as perps | `list_rwa_assets`, `get_rwa_asset` | | Holders, wallets, baskets, transcripts | `get_holders`, `get_wallets`, `get_basket`, `get_transcripts` | | A question in plain words | `ask_shumi`, `search_web` | `get_coin_risk` takes 1 to 15 symbols at once. `resolve_coin` tells the token `GOLD` from the metal; resolve first when a ticker could mean two things. Real-world assets have their own two tools; the coin tools will not find them. For "what's pumping today?", call `scan_coins` with `sort_by: "change24h"`. [Market Screener](/research/market-screener) explains each sort and the fields each row carries. | `scan_coins` input | Values | | - | - | | `sort_by` | `marketCap` (default), `change24h`, `change7d`, `streak`, `price` | | `sort_order` | `desc` (default, largest first) or `asc` | | `category` | One name from `list_categories` | | `mcap_min`, `mcap_max` | Market-cap bounds in US dollars | `lookup_coin` returns `currentTrend`: the coin's daily trend now, the day it started and how many days it has run. [Coin Lookup](/research/coin-analysis#read-the-current-trend) explains the fields. A local server needs `@shumi-ai/mcp` 1.2.1 or later for both. Every list in a tool result holds 50 items at most, and fewer when the result is large. | To | Use | | - | - | | Get fewer items | `top`, below 50 | | Keep only some keys | `fields` | | See whether a list was cut | `meta._truncated`. It reports cuts made to keep the result small, but not the default 50-item cut on tools with the shared `top` filter | | Know the full count | Compare the list's length with `meta.total`, `total_count` or `count` where the result has one. `list_categories` and `scan_coins` have none | | Get the full real-world asset list | `GET /api/cli/rwa/assets?top=1000` over the API | | Read the walk-forward record or live streams | `shumi walkforward` and `shumi watch` in the [CLI](/agents/cli), or the [API](/api-reference/introduction#stream-live-data) | Two resources describe the server: `shumi://capabilities` lists the tools, and `shumi://billing/tier` shows the plan on your key. On the Free plan every tool call counts as one question. When the quota is used up, the tool returns an error with a hint on how to continue. [Plans and Quotas](/platform/access) explains the plans. ## Ask a question with ask\_shumi `ask_shumi` takes one `query` in plain words. Shumi works out which data it needs, fetches it and writes an answer, returned as plain text. Use it for a question that needs judgement or compares several things, such as "is funding on SOL crowded compared with last month?". For a fact with one exact answer, call the data tool instead: it is faster and returns the current figures without prose. `search_web` takes a `query` and returns search results, or a written answer when `answer` is `true`. ## Read a result A data tool returns `data` and `meta`. On most tools `meta.as_of` and `meta.data_age_seconds` say how old the data is. Check `data_age_seconds` before your agent acts on a funding rate or a price. # Pay Per Call Source: https://docs.shumi.ai/agents/payments Pay for single API calls in USDC on Base with the x402 protocol, with no subscription. Without a subscription you can pay for one call at a time. The payment travels on the HTTP request itself, using [x402](https://x402.org), in USDC on Base. No card and no plan needed. Payment starts once your free questions are used up: 10 to start, then 1 per day. A call that fails on Shumi's side is never charged, because settlement runs only after a successful response. ## Check the price | Call | Price | | - | - | | A data call: `coin`, `market`, `funding`, `regime`, `signal`, `scan` and the rest | 0.005 USDC | | A plain-word question (`shumi ask`, `POST /api/cli`) | 0.05 USDC | | `pairs` and `walkforward` | 0.05 USDC | | `watch` live streams | No per-call price | `GET https://api.shumi.ai/api/cli/manifest` lists the priced routes with their price. ## Set up a wallet **1. Create a wallet** ```bash theme={"dark"} shumi wallet create ``` A wallet on your machine, encrypted with a passphrase you choose. It only pays and is separate from the account you signed in with. **2. Fund it with USDC on Base** ```bash theme={"dark"} shumi wallet address shumi wallet fund --amount 25 ``` Send USDC on Base to the address, or open the link `wallet fund` prints to buy USDC with a card. You need no ETH for gas. **3. Check the balance** ```bash theme={"dark"} shumi wallet balance ``` ## Pay from the terminal The next priced command asks before it pays: ``` πŸ’Έ Shumi needs 0.005 USDC on Base to run `shumi coin risk DOGE`. From 0xD1C8…6f99 (balance 4.83 USDC) To 0xc624…b394 Pay? [Y/n] ``` Check the recipient before you answer. Enter or `y` pays and runs the command. `n` stops with `Payment declined` and nothing is charged. To pay without a prompt, add `--auto-pay` or set `SHUMI_AUTO_PAY=1`. `--agent` implies it. Three variables control unattended payment: | Variable | Default | What it does | | - | - | - | | `SHUMI_MAX_PRICE_USDC` | `0.10` | Ceiling per call. A higher price is refused | | `SHUMI_DAILY_USDC_CAP` | `1.00` | Ceiling per UTC day, so a looping agent cannot drain the wallet | | `SHUMI_X402_PRIVATE_KEY` | none | Sign with this key instead of the encrypted wallet. Needed for `--agent` runs, which cannot type a passphrase | `shumi wallet receipts` lists your last 20 payments, with `--since`, `--until` and `--export csv`. ## Pay from your own code A priced route answers `402 Payment Required` with an x402 challenge instead of the usual envelope: ```json theme={"dark"} { "x402Version": 1, "accepts": [{ "scheme": "exact", "network": "base", "maxAmountRequired": "5000", "resource": "https://api.shumi.ai/api/cli/coin/risk/DOGE", "payTo": "0x...", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "maxTimeoutSeconds": 60, "extra": { "name": "USD Coin", "version": "2" } }] } ``` `maxAmountRequired` is in USDC's smallest unit. USDC has six decimals, so `5000` is 0.005 USDC. **1. Sign** Sign an EIP-3009 `transferWithAuthorization` for `maxAmountRequired` to `payTo`. **2. Resend** Repeat the request with the signed payload in the `X-PAYMENT` header. **3. Read the receipt** Shumi runs the call, settles on chain and returns the settlement in `X-PAYMENT-RESPONSE` (x402 v1). Newer x402 v2 servers use `PAYMENT-RESPONSE`, so read either. A failed call settles nothing. # Resolve the caller's entitlement Source: https://docs.shumi.ai/api-reference/account/resolve-the-callers-entitlement /api-reference/openapi.json get /api/cli/billing/tier Reports the tier the gate will actually apply to this credential, so a client never has to guess why a request was refused. # Ask a natural-language question Source: https://docs.shumi.ai/api-reference/ask/ask-a-natural-language-question /api-reference/openapi.json post /api/cli Runs the full Shumi engine: classify, plan, execute tools, generate. Returns a streamed response. This route does **not** use the standard envelope β€” it streams, and its errors are `{ "error": "..." }`. # All categories Source: https://docs.shumi.ai/api-reference/categories/all-categories /api-reference/openapi.json get /api/cli/category/list # Category trend breakdown Source: https://docs.shumi.ai/api-reference/categories/category-trend-breakdown /api-reference/openapi.json get /api/cli/category/info/{name} # Coins in a category Source: https://docs.shumi.ai/api-reference/categories/coins-in-a-category /api-reference/openapi.json get /api/cli/category/coins/{name} # Sentiment for a category Source: https://docs.shumi.ai/api-reference/categories/sentiment-for-a-category /api-reference/openapi.json get /api/cli/category/sentiment/{name} # Bundled risk context Source: https://docs.shumi.ai/api-reference/coins/bundled-risk-context /api-reference/openapi.json get /api/cli/coin/risk/{symbol} Price, funding, trend alignment, sentiment stance, and BTC correlation in one payload. Fields that could not be refreshed are listed in `_stale_fields`. # Coin by canonical id Source: https://docs.shumi.ai/api-reference/coins/coin-by-canonical-id /api-reference/openapi.json get /api/cli/coin/by-id/{id} # Coin by display name Source: https://docs.shumi.ai/api-reference/coins/coin-by-display-name /api-reference/openapi.json get /api/cli/coin/by-name/{name} # Crowd sentiment for one coin Source: https://docs.shumi.ai/api-reference/coins/crowd-sentiment-for-one-coin /api-reference/openapi.json get /api/cli/coin/sentiment/{symbol} # Historical metadata Source: https://docs.shumi.ai/api-reference/coins/historical-metadata /api-reference/openapi.json get /api/cli/coin/historical/{symbol} # Look up a coin by ticker Source: https://docs.shumi.ai/api-reference/coins/look-up-a-coin-by-ticker /api-reference/openapi.json get /api/cli/coin/lookup Returns coin metadata and trend state. If the ticker also matches a real-world asset, the response carries a `note` naming the collision. # Resolve a contract address to a coin Source: https://docs.shumi.ai/api-reference/coins/resolve-a-contract-address-to-a-coin /api-reference/openapi.json get /api/cli/coin/by-contract/{address} # Resolve free text to an asset Source: https://docs.shumi.ai/api-reference/coins/resolve-free-text-to-an-asset /api-reference/openapi.json get /api/cli/resolve Probes the crypto and RWA lanes and returns ranked matches, each tagged with how it was found. Use this to disambiguate a ticker that exists in both lanes, such as `GOLD` or `COIN`. # API Overview Source: https://docs.shumi.ai/api-reference/introduction Base URL, authentication, the response envelope, error codes and quotas for the Shumi API. The Shumi API returns market data and verdicts as JSON over HTTPS. The [CLI](/agents/cli) and the [MCP server](/agents/mcp) both call it. The API reference in the sidebar lists every endpoint with its parameters. ``` https://api.shumi.ai ``` Data routes live under `/api/cli`. `GET /api/cli/manifest` is public and lists the priced routes with their price and refresh interval. ## Authenticate a request Every data route needs a bearer token in the `Authorization` header. ```bash theme={"dark"} curl https://api.shumi.ai/api/cli/signal/BTC \ -H "Authorization: Bearer shumi_sk_your_key_here" ``` | Token | Looks like | Where you get it | | - | - | - | | API key | starts with `shumi_sk_` | `shumi keys create` in the CLI. For servers, bots and agents | | Login token | a JWT | `shumi login` stores it for the CLI | Without a token the API answers `403 AUTH_REQUIRED`. With a malformed, unknown, expired or revoked one it answers `401 AUTH_INVALID`. ## Read the response Every data route except the plain-word question route returns the same envelope: `schemaVersion`, `data` and `meta`. This is `GET /api/cli/signal/BTC` with `evidence` cut to one line. ```json theme={"dark"} { "schemaVersion": 1, "data": { "symbol": "BTC", "verdict": "strong-bull", "score": 3.5, "confidence": "high", "evidence": ["trend (daily) is bullish since 2026-09-19T00:00:00.000Z"] }, "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 | | - | - | | `schemaVersion` | `1`. Changes only when the envelope's shape changes | | `data` | The payload. Its shape depends on the route | | `meta.ts` | When the API answered | | `meta.route` | The route that answered | | `meta.as_of` | When the newest data point in the payload was recorded. On most routes | | `meta.data_age_seconds` | Seconds between `as_of` and `ts`. On most routes | Check `data_age_seconds` before you act on a funding rate or a price. [Coverage](/platform/coverage#how-fresh-the-data-is) lists how often each kind of data refreshes. ## Handle an error A failed call replaces `data` with `error`. ```json theme={"dark"} { "schemaVersion": 1, "error": { "code": "BAD_REQUEST", "message": "action=coin requires ?symbol=" } } ``` | Code | HTTP | Meaning | | - | - | - | | `BAD_REQUEST` | 400 | A parameter is missing or invalid. The message names it | | `AUTH_REQUIRED` | 403 | No token was sent | | `AUTH_INVALID` | 401 | The token was rejected | | `RATE_LIMITED` | 429 | Free quota used up on a route with no per-call price | | `UPSTREAM_4XX` | same as upstream | A data source refused the request | | `UPSTREAM_5XX` | 502 | A data source failed | | `NETWORK` | 502 | A data source could not be reached | | `INTERNAL` | 500 | Something else went wrong | On upstream errors, `error.details` carries `upstreamStatus` and the upstream body. > [!NOTE] > > `POST /api/cli`, the plain-word question route, streams its answer and returns a bare `{ "error": "..." }` on failure. Every other route uses the envelope above. ## Know what a call costs On the Free plan, every call to a data route counts as one question: 10 to start, then 1 per day, resetting at 00:00 UTC. After that, a priced route answers `402 Payment Required` with an x402 challenge: 0.005 USDC per data call, 0.05 USDC for a plain-word question, `pairs` or `walkforward`. [Pay Per Call](/agents/payments) shows the challenge and how to answer it. [Plans and Quotas](/platform/access) covers the plans. To see which plan the API applies to your token: ```bash theme={"dark"} curl https://api.shumi.ai/api/cli/billing/tier \ -H "Authorization: Bearer $SHUMI_TOKEN" ``` ```json theme={"dark"} { "data": { "tier": "pro", "source": "manual", "expiresAt": null } } ``` `GET /api/cli/billing/tier` and `GET /api/cli/manifest` never count against your quota and never ask for payment. For a bot or dashboard on a timer, [Run a bot or dashboard](/agents/cli#run-a-bot-or-dashboard) shows which calls to repeat and which to save for a change. ## Stream live data `GET /api/cli/watch/{stream}` keeps the connection open and sends one JSON object per line. | Parameter | Values | | - | - | | `stream` | `funding`, `regime` or `sentiment` | | `interval` | Seconds between polls, 10 to 300 | | `diff=1` | Send a line only when the payload changed | ```bash theme={"dark"} curl -N "https://api.shumi.ai/api/cli/watch/funding?interval=30" \ -H "Authorization: Bearer $SHUMI_TOKEN" ``` A Free account can stream while it has questions left. Once the quota is spent, a stream answers `429 RATE_LIMITED` before the first line. Streams cannot be paid per call. # Breadth crossings Source: https://docs.shumi.ai/api-reference/market/breadth-crossings /api-reference/openapi.json get /api/cli/market/crossing Always returns a `crossings` array. It is empty when nothing has fired, so callers never branch on shape. # Filterable market screener Source: https://docs.shumi.ai/api-reference/market/filterable-market-screener /api-reference/openapi.json get /api/cli/scan Accepts the same filter parameters as the web screener and passes them through. # Global market snapshot Source: https://docs.shumi.ai/api-reference/market/global-market-snapshot /api-reference/openapi.json get /api/cli/market/global # Live prices Source: https://docs.shumi.ai/api-reference/market/live-prices /api-reference/openapi.json get /api/cli/market/prices Symbol-keyed. Tickers are resolved to canonical ids server-side. # Market breadth and health Source: https://docs.shumi.ai/api-reference/market/market-breadth-and-health /api-reference/openapi.json get /api/cli/market/health # Reference baselines Source: https://docs.shumi.ai/api-reference/market/reference-baselines /api-reference/openapi.json get /api/cli/market/baselines # List real-world assets Source: https://docs.shumi.ai/api-reference/rwa/list-real-world-assets /api-reference/openapi.json get /api/cli/rwa/assets Equities, metals, and commodities. These are real-world instruments, not tokenised crypto wrappers. # One real-world asset Source: https://docs.shumi.ai/api-reference/rwa/one-real-world-asset /api-reference/openapi.json get /api/cli/rwa/asset/{id} # Real-world asset by ticker Source: https://docs.shumi.ai/api-reference/rwa/real-world-asset-by-ticker /api-reference/openapi.json get /api/cli/rwa/symbol/{symbol} # Active narratives Source: https://docs.shumi.ai/api-reference/sentiment/active-narratives /api-reference/openapi.json get /api/cli/narratives # Sentiment and narrative momentum Source: https://docs.shumi.ai/api-reference/sentiment/sentiment-and-narrative-momentum /api-reference/openapi.json get /api/cli/sentiment # Stream updates as NDJSON Source: https://docs.shumi.ai/api-reference/streaming/stream-updates-as-ndjson /api-reference/openapi.json get /api/cli/watch/{stream} Long-lived newline-delimited JSON. One object per line, emitted every `interval` seconds until the client disconnects. Opening a stream counts against quota; it is not payable per call, so an exhausted quota returns 429 rather than a payment challenge. # Highlights mined from tracked transcripts Source: https://docs.shumi.ai/api-reference/tracking/highlights-mined-from-tracked-transcripts /api-reference/openapi.json get /api/cli/transcripts Spoken-word commentary from tracked video and podcast sources, tagged with the coins, sectors, and macro topics mentioned. # Tracked basket snapshots Source: https://docs.shumi.ai/api-reference/tracking/tracked-basket-snapshots /api-reference/openapi.json get /api/cli/basket # Tracked token holder counts Source: https://docs.shumi.ai/api-reference/tracking/tracked-token-holder-counts /api-reference/openapi.json get /api/cli/holders # Tracked wallet activity Source: https://docs.shumi.ai/api-reference/tracking/tracked-wallet-activity /api-reference/openapi.json get /api/cli/wallets # Futures signal engine Source: https://docs.shumi.ai/api-reference/trade-decisions/futures-signal-engine /api-reference/openapi.json get /api/cli/futures # Market regime Source: https://docs.shumi.ai/api-reference/trade-decisions/market-regime /api-reference/openapi.json get /api/cli/regime # Pair trading and delta-neutral Source: https://docs.shumi.ai/api-reference/trade-decisions/pair-trading-and-delta-neutral /api-reference/openapi.json get /api/cli/pairs `suggestions` pairs two different coins. `delta-neutral` is the same coin across two venues, earning the funding spread. They are not interchangeable. # Perpetual funding momentum Source: https://docs.shumi.ai/api-reference/trade-decisions/perpetual-funding-momentum /api-reference/openapi.json get /api/cli/funding/momentum Market-wide when `symbol` is omitted, otherwise scoped to one asset. # Recent funding alert events Source: https://docs.shumi.ai/api-reference/trade-decisions/recent-funding-alert-events /api-reference/openapi.json get /api/cli/funding/alerts # Signal quality scoring Source: https://docs.shumi.ai/api-reference/trade-decisions/signal-quality-scoring /api-reference/openapi.json get /api/cli/signal-quality # Synthesised verdict for one asset Source: https://docs.shumi.ai/api-reference/trade-decisions/synthesised-verdict-for-one-asset /api-reference/openapi.json get /api/cli/signal/{symbol} Fans out to risk context, funding momentum, active regime, and coin sentiment, then returns a rules-based verdict with the evidence behind it. No model call. # Trend state across the market Source: https://docs.shumi.ai/api-reference/trade-decisions/trend-state-across-the-market /api-reference/openapi.json get /api/cli/trends # Walkforward backtest records Source: https://docs.shumi.ai/api-reference/trade-decisions/walkforward-backtest-records /api-reference/openapi.json get /api/cli/walkforward Historical record of a forward-testing engine. Read it as history β€” an empty `positions` list means the engine has written nothing, not that the market has no setups. # CoinRotator Source: https://docs.shumi.ai/coinrotator The rule-based crypto screener at coinrotator.app, and how Shumi links to it. [coinrotator.app](https://coinrotator.app) is a free crypto screener with no account: the top 1,000+ coins by market cap, each with its price, a 24h trend, a 7d trend, the streak in days and its market cap. Trend is UP, [HODL](/research/market-health#count-the-coins-trending-up-sideways-or-down) or DOWN. The screener applies fixed rules, so the same data always gives the same result. Shumi reads the same data together with funding, sentiment and narratives, and weighs them into an answer. The two work together: when a Shumi answer names a coin, it links to the coin's page, such as [coinrotator.app/coin/solana](https://coinrotator.app/coin/solana). An answer about market breadth links to [Market Health](https://coinrotator.app/market-health). ## Screen coins on coinrotator.app | Page | What it shows | | - | - | | [Crypto Screener](https://coinrotator.app) | Every tracked coin with price, trend, streak and market cap | | [Newly listed coins](https://coinrotator.app/new-coins) | Recent listings that pass a volume floor | | [Low Market Cap](https://coinrotator.app/low-market-cap) | Small caps filtered by trend direction | | [Crypto Trends Today](https://coinrotator.app/todays-trends) | Coins that changed trend direction today | | [Oldest Trends](https://coinrotator.app/oldest-trends) | The longest-running trend streaks, longest first | | [4h Alerts](https://coinrotator.app/4h-alerts) | Coins that flipped trend on the latest 4h candle, newest first | | [Categories](https://coinrotator.app/category) | Trend and streak per category, from its top 10 coins | | [Watchlist](https://coinrotator.app/watchlist) | Coins you starred. Stored in your browser | Exchange pages list one venue's coins sorted by trend: [Binance](https://coinrotator.app/binance-screener), [KuCoin](https://coinrotator.app/kucoin-screener) and [Solana](https://coinrotator.app/solana-screener) for spot; [Binance](https://coinrotator.app/binance-futures-screener), [Bitget](https://coinrotator.app/bitget-futures-screener), [OKX](https://coinrotator.app/okx-futures-screener), [Bybit](https://coinrotator.app/bybit-futures-screener), [MEXC](https://coinrotator.app/mexc-futures-screener), [KuCoin](https://coinrotator.app/kucoin-futures-screener) and [BingX](https://coinrotator.app/bingx-futures-screener) for perpetual futures. The [RWA Perps Screener](https://coinrotator.app/rwa-perps-screener) lists real-world-asset perpetuals (stocks, metals, energy, indices, FX), ranked by open interest. It covers Hyperliquid, Aster, Lighter and Variational. Shumi reads the same assets through `shumi stock` and `shumi commodity`, see [Coin Lookup](/research/coin-analysis). The [CoinRotator v2.1 TradingView indicator](https://www.tradingview.com/script/S7zzOb0C-CoinRotator-v2-1-Stable-Version/) renews monthly with Shumi Plus. Pro and Genesis include lifetime indicator access. Most pages show their last data update at the top. Categories update daily at 01:00 UTC and weekly on Mondays. # Decision record Source: https://docs.shumi.ai/evidence/decision-record One Shumi take a day, published verbatim with its inputs' times, scored later by rules fixed before the first entry. Once a day Shumi is asked one fixed question about one coin, and its answer is published here unedited. Every take is published, including takes that came back stale, unparsed or with an error. Nothing is edited or removed after publication: an outcome is a new block added below the entry it belongs to, and the page's git history shows every change. **Status: registered, unresolved.** The first three entries, for 2026-10-16 to 2026-10-18, landed here on 2026-10-21. The record stays "registered, unresolved" until its first reading. The full rules it runs on are in the [pre-registration](/evidence/pre-registration), fixed on 2026-10-14 before the first entry; this page summarises them. **Correction, 2026-10-22.** In the first three entries (R-2026-10-16 to R-2026-10-18), the "Pre-registration" row named a draft of the rules from 2026-10-13, in an internal repository a reader cannot open. That draft predates three changes made on 2026-10-13 and 2026-10-14, before the first entry: founders read each day's entries before they publish (by 19:15 UTC), an entry's publication time is when it lands here, and longs are no longer halved while Bitcoin is below its 200-day average. The entries are scored under the rules registered on 2026-10-14, and those three cells now link the public copy of them. This page's summary also said a long was sized at 0.5 % risk while Bitcoin is below its 200-day average; the registered rules dropped that halving on 2026-10-14, before the first entry, and the summary now matches them. Nothing else in any entry changed. ## How a coin is picked A query picks the coin, not a person. At 12:15 UTC it counts how often each coin appeared in Shumi's hourly sentiment summaries over the previous 24 hours and picks the coin with the highest count. Ties go to the larger market cap. Eligible coins are the top 500 by market cap, excluding stablecoins, wrapped, bridged and liquid-staking tokens, real-world-asset rows (stocks, commodities), coins without a current trend, coins picked in the previous 7 days, and coins whose earlier plan here is still open. Every entry lists the five highest counts next to the pick. ## The question At 13:15 UTC the same message is sent once in a new Shumi chat, with no follow-up and no regenerating. It asks which plan the data favours today, long, short or neither. It asks Shumi to state both plans with entry zone, stop, target and data score, the exit rule, the biggest risk, the venue, and the time of every input it used. It never asks what to buy. ## How a plan is scored * A plan fills only when price reaches its entry zone. A plan that never fills is published with the reason it lapsed and is not scored. * A filled plan ends at the first of: a daily close beyond its stop, the site's trend turning against it, or a reversal signal once the plan is at least 3 % in profit. The printed target is not an exit. There is no time limit. * Results are in R (the loss the plan stated up front) and in account terms at 1 % risk per plan, long or short, after costs of 0.4 % round trip for coins ranked 1–100 and 1 % for ranks 101–500. Funding over the hold is shown, never assumed to be zero. * NEITHER is a full answer. It is scored as staying out. ## The bar The record is read twice: first when 30 plans have resolved that were entered in at least 8 different weeks, then at 60 plans entered in at least 12 different weeks. A reading is published as "passed" or "not passed". It passes only if all of these hold after costs: 1. The average result per plan is above zero, and so is the average of weekly averages (each week of entries counted once). 2. Across every published day, Shumi's total is ahead of taking the published long plan every day on the same coin. 3. At least 40 % of the plans end with a net result above zero. 4. No scheduled day is missing from the record. The bar was fixed before any outcome was seen. A change to it is a new version with its own date; entries already published keep the version they were published under. ## Entries Each entry shows when the question was asked and when the answer was published, the coin and why it was picked, the site trend at selection, any labels (`stale input`, `exit line missing`, `no plan`, `unparsed`, `error`, `no eligible coin`), both plans as parsed, Shumi's full answer verbatim (which states the time of every input it used and the size it prints), and the link to the live Shumi session. ### R-2026-10-16 | Field | Value | | - | - | | Asked at | 2026-10-16T13:15:00.020Z | | Prepared at | 2026-10-16T17:41:18.235Z (266 min after asking) (published when its commit reached master: see the page history) | | Coin | `Bitcoin` (`BTC`), CoinGecko `bitcoin`, rank 1 at selection | | Selection | `BTC 24, ETH 14, SOL 10, HYPE 9, XRP 6` | | Site trend at selection | `HODL, as of 2026-10-16, since 2026-10-10` | | Labels | none | | Stance | LONG | | Long plan | entry 81280–81820, stop 78300, target 86950, data score 6/10 | | Short plan | entry 82080–82110, stop 85350, target 76290, data score 2/10 | | Scored side | long | | Exit line | `Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit.` | | Exit rule scored | The plan ends at the first of: a daily close (00:00 UTC) beyond the stop published with the take; the site's trend turning to the opposite side; an opposite reversal signal while the plan is at least 3 % in profit. The printed target is not an exit. | | Live Shumi link | [https://shumi.ai/s/AZIOFGCoeO](https://shumi.ai/s/AZIOFGCoeO) | | Served by | `openai/gpt-5.4 via openrouter; classifier openai/gpt-5.6-luna; base/Classification Prompt v112, base/System prompt v204, Tool Definitions v96` | | Pre-registration | [version 1, registered 2026-10-14](/evidence/pre-registration) | Full take, verbatim: ```text theme={"dark"} Data favours: LONG $BTC | long | 81280-81820 | 78300 | 86950 | 6/10 $BTC | short | 82080-82110 | 85350 | 76290 | 2/10 Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit. Biggest risk: the wider market is still falling in dollar terms, with 74.9% of coins down, so BTC can be pulled lower even with the higher long score. Venue: Binance BTC/USDT. Source times used: price 2026-10-16 13:15 UTC; futures 2026-10-16 13:00 UTC; market breadth 2026-10-16; trend as of 2026-10-16; plan levels as of 2026-10-15; sentiment posts on X 2026-10-16 13:00 UTC, 15 minutes old; X posting rate measured 2026-10-16 07:18 UTC. ``` Published at 2026-10-21T07:40:26Z. ### R-2026-10-17 | Field | Value | | - | - | | Asked at | 2026-10-17T13:15:00.016Z | | Prepared at | 2026-10-17T16:38:20.587Z (203 min after asking) (published when its commit reached master: see the page history) | | Coin | `Ethereum` (`ETH`), CoinGecko `ethereum`, rank 2 at selection | | Selection | `BTC 20, ETH 13, SOL 8, XRP 4, PYTH 3` | | Site trend at selection | `DOWN, as of 2026-10-17, since 2026-10-11` | | Labels | none | | Stance | SHORT | | Long plan | entry 2409–2416, stop 2275, target 2648, data score 4/10 | | Short plan | entry 2519–2542, stop 2668, target 2145, data score 6/10 | | Scored side | short | | Exit line | `Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit.` | | Exit rule scored | The plan ends at the first of: a daily close (00:00 UTC) beyond the stop published with the take; the site's trend turning to the opposite side; an opposite reversal signal while the plan is at least 3 % in profit. The printed target is not an exit. | | Live Shumi link | [https://shumi.ai/s/MJ67GmQMbs](https://shumi.ai/s/MJ67GmQMbs) | | Served by | `openai/gpt-5.4 via openrouter; classifier openai/gpt-5.6-luna; base/Classification Prompt v112, base/System prompt v204, Tool Definitions v96` | | Pre-registration | [version 1, registered 2026-10-14](/evidence/pre-registration) | Full take, verbatim: ```text theme={"dark"} Data favours: SHORT $ETH | long | 2409-2416 | 2275 | 2648 | 4/10 $ETH | short | 2519-2542 | 2668 | 2145 | 6/10 Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit. The biggest risk is a squeeze back into the short entry area while ETH is already below it, so I would act on Binance Futures. Used times: price 2026-10-17 13:15 UTC; futures carry 2026-10-17 13:00 UTC; trend as of 2026-10-17; levels as of 2026-10-16; wider market 2026-10-17; people’s view from posts on X 2026-10-17 12:50 UTC, current; posting pace on X 2026-10-17 13:15 UTC, current. ``` Published at 2026-10-21T07:51:50Z. ### R-2026-10-18 | Field | Value | | - | - | | Asked at | 2026-10-18T13:15:00.010Z | | Prepared at | 2026-10-18T16:51:19.045Z (216 min after asking) (published when its commit reached master: see the page history) | | Coin | `Hyperliquid` (`HYPE`), CoinGecko `hyperliquid`, rank 11 at selection | | Selection | `BTC 18, ETH 4, HYPE 3, LINK 2, BNB 1` | | Site trend at selection | `HODL, as of 2026-10-18, since 2026-10-12` | | Labels | none | | Stance | LONG | | Long plan | entry 75.27–76.32, stop 69.5, target 85.96, data score 5/10 | | Short plan | entry 81.64–82.69, stop 88.81, target 63.65, data score 4/10 | | Scored side | long | | Exit line | `Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit.` | | Exit rule scored | The plan ends at the first of: a daily close (00:00 UTC) beyond the stop published with the take; the site's trend turning to the opposite side; an opposite reversal signal while the plan is at least 3 % in profit. The printed target is not an exit. | | Live Shumi link | [https://shumi.ai/s/lKTM9bYwl1](https://shumi.ai/s/lKTM9bYwl1) | | Served by | `openai/gpt-5.4 via openrouter; classifier openai/gpt-5.6-luna; base/Classification Prompt v112, base/System prompt v204, Tool Definitions v96` | | Pre-registration | [version 1, registered 2026-10-14](/evidence/pre-registration) | Full take, verbatim: ```text theme={"dark"} Data favours: LONG $HYPE | long | 75.27-76.32 | 69.50 | 85.96 | 5/10 $HYPE | short | 81.64-82.69 | 88.81 | 63.65 | 4/10 Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit. The biggest risk is the market backdrop: 75.7% of coins are falling, so HYPE can get dragged lower while its own trend is still sideways. I would act on Hyperliquid. Used times: price 2026-10-18 13:15 UTC; futures 2026-10-18 13:00 UTC; levels 2026-10-17; trend as of 2026-10-18; market breadth 2026-10-18; posts on X 2026-10-18 12:49 UTC; mentions 2026-10-18 13:15 UTC. ``` Published at 2026-10-21T08:12:55Z. ### R-2026-10-22 | Field | Value | | - | - | | Asked at | 2026-10-22T13:15:00.012Z | | Prepared at | 2026-10-22T18:09:47.050Z (295 min after asking) (published when its commit reached master: see the page history) | | Coin | `XRP` (`XRP`), CoinGecko `ripple`, rank 5 at selection | | Selection | `BTC 23, ETH 15, SOL 6, ZEC 6, XRP 5 (tie-break on rank)` | | Site trend at selection | `HODL, as of 2026-10-22, since 2026-10-22` | | Labels | none | | Stance | LONG | | Long plan | entry 1.31–1.315, stop 1.223, target 1.48, data score 5/10 | | Short plan | entry 1.374–1.388, stop 1.51, target 1.18, data score 3/10 | | Scored side | long | | Exit line | `Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit.` | | Exit rule scored | The plan ends at the first of: a daily close (00:00 UTC) beyond the stop published with the take; the site's trend turning to the opposite side; an opposite reversal signal while the plan is at least 3 % in profit. The printed target is not an exit. | | Live Shumi link | [https://shumi.ai/s/QTAW1nPG0Q](https://shumi.ai/s/QTAW1nPG0Q) | | Served by | `openai/gpt-5.4 via openrouter; classifier openai/gpt-5.6-luna; base/Classification Prompt v114, base/System prompt v208, Tool Definitions v97` | | Pre-registration | [version 1, registered 2026-10-14](/evidence/pre-registration) | Full take, verbatim: ```text theme={"dark"} Data favours: LONG $XRP | long | 1.31-1.315 | 1.223 | 1.48 | 5/10 $XRP | short | 1.374-1.388 | 1.51 | 1.18 | 3/10 Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit. The biggest risk is that XRP is sideways today, so either side can fail quickly inside the range. I would act on Binance. price 2026-10-22 13:15 UTC; futures 2026-10-22 13:00 UTC; trend as of 2026-10-22; levels as of 2026-10-21; market 2026-10-22; market crowding 2026-10-22 13:15 UTC. ``` ### R-2026-10-23 | Field | Value | | - | - | | Asked at | 2026-10-23T13:15:00.022Z | | Prepared at | 2026-10-23T17:57:42.023Z (283 min after asking) (published when its commit reached master: see the page history) | | Coin | `Chainlink` (`LINK`), CoinGecko `chainlink`, rank 16 at selection | | Selection | `BTC 22, ETH 15, ZEC 6, HYPE 5, LINK 5` | | Site trend at selection | `DOWN, as of 2026-10-23, since 2026-10-17` | | Labels | none | | Stance | SHORT | | Long plan | entry 11.54–11.71, stop 10.58, target 13.49, data score 4/10 | | Short plan | entry 12.04–12.05, stop 13.05, target 9.904, data score 6/10 | | Scored side | short | | Exit line | `Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit.` | | Exit rule scored | The plan ends at the first of: a daily close (00:00 UTC) beyond the stop published with the take; the site's trend turning to the opposite side; an opposite reversal signal while the plan is at least 3 % in profit. The printed target is not an exit. | | Live Shumi link | [https://shumi.ai/s/EyNo9BOP1q](https://shumi.ai/s/EyNo9BOP1q) | | Served by | `openai/gpt-5.4 via openrouter; classifier openai/gpt-5.6-luna; base/Classification Prompt v114, base/System prompt v208, Tool Definitions v97` | | Pre-registration | [version 1, registered 2026-10-14](/evidence/pre-registration) | Full take, verbatim: ```text theme={"dark"} Data favours: SHORT $LINK | long | 11.54-11.71 | 10.58 | 13.49 | 4/10 $LINK | short | 12.04-12.05 | 13.05 | 9.904 | 6/10 Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit. The single biggest risk is the LG CNS partnership news keeping buyers active while the short entry sits almost on the current price. I would act on Binance. Price 2026-10-23 13:15 UTC; futures 2026-10-23 13:00 UTC; trend as of 2026-10-23; levels 2026-10-22 00:00 UTC; funding cross-market 2026-10-23 13:15 UTC; sentiment posts on X 2026-10-23 11:31 UTC, mentions measured 2026-10-23 13:15 UTC. ``` ### R-2026-10-24 | Field | Value | | - | - | | Asked at | 2026-10-24T13:15:00.034Z | | Prepared at | 2026-10-24T13:31:10.105Z (16 min after asking) (published when its commit reached master: see the page history) | | Coin | `Bitcoin` (`BTC`), CoinGecko `bitcoin`, rank 1 at selection | | Selection | `BTC 18, ETH 11, SOL 8, HYPE 6, ZEC 3` | | Site trend at selection | `UP, as of 2026-10-24, since 2026-10-22` | | Labels | none | | Stance | LONG | | Long plan | entry 80430–80590, stop 77430, target 87090, data score 8/10 | | Short plan | entry 80770–81280, stop 84100, target 76290, data score 2/10 | | Scored side | long | | Exit line | `Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit.` | | Exit rule scored | The plan ends at the first of: a daily close (00:00 UTC) beyond the stop published with the take; the site's trend turning to the opposite side; an opposite reversal signal while the plan is at least 3 % in profit. The printed target is not an exit. | | Live Shumi link | [https://shumi.ai/s/W0VcgGvsxT](https://shumi.ai/s/W0VcgGvsxT) | | Served by | `openai/gpt-5.4 via openrouter; classifier openai/gpt-5.6-luna; base/Classification Prompt v114, base/System prompt v208, Tool Definitions v97` | | Pre-registration | [version 1, registered 2026-10-14](/evidence/pre-registration) | Full take, verbatim: ```text theme={"dark"} Data favours: LONG $BTC | long | 80430-80590 | 77430 | 87090 | 8/10 $BTC | short | 80770-81280 | 84100 | 76290 | 2/10 Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit. Biggest risk: the wider market is still falling in dollar terms, with 68.6% of 993 coins down while BTC is one of the few still rising, so BTC can lose that relative strength fast. Venue: Binance Futures BTCUSDT. price 2026-10-24 13:15 UTC; futures 2026-10-24 13:00 UTC; trend as of 2026-10-24; levels as of 2026-10-23; market breadth 2026-10-24; Binance Futures BTCUSDT liquidations and traded price buckets fetched 2026-10-24 13:15 UTC. ``` # Decision record: pre-registration Source: https://docs.shumi.ai/evidence/pre-registration The rules the public decision record runs on, fixed on 2026-10-14 before the first entry: how the coin is picked, what Shumi is asked, how each plan is scored, and the bar it has to clear. ## The daily record Each day the record picks the coin that came up most often in Shumi's hourly sentiment summaries over the past 24 hours, from the top 500 by market cap. Stablecoins, wrapped, bridged and liquid-staking tokens, coins with no current trend, and coins picked in the past week or with a plan still open are skipped. At 13:15 UTC Shumi is asked for a plan for each side: entry zone, stop, target and a score out of 10. It also says which side the data favours, or that it favours neither. The entry goes live by 19:15 UTC, and the plan on the side Shumi favours is scored from that moment. A plan that fills stays open until a daily close beyond its stop, the trend turning against it, or a reversal signal once it is 3 % in profit. There is no time limit. A plan that never fills lapses and is not scored. The record is first scored once 30 plans have finished. Those plans must have been entered in at least 8 different weeks. It is scored again at 60 plans, entered in at least 12 different weeks. It passes only if all four of these hold, after fees and slippage: * the average plan made money, and so did the average week; * Shumi's chosen side made more in total than taking the long plan on the same coin every day, counting a day with no filled plan as 0; * at least 40 % of finished plans ended in profit; * no scheduled day was missed. Each score is published as "passed" or "not passed". Every plan and its result are in [the decision record](/evidence/decision-record). ## Full rules These rules were registered on 2026-10-14, before day one of [the decision record](/evidence/decision-record) (2026-10-16). A rule change is a new version with its own page and date, and entries already published keep being scored under the version they were published under. No rule on this page may change after the first outcome has been looked at. The pass mark (section 10) is a first version: it is re-set from live data through exactly that process. The founders agreed on 2026-10-09, on one condition: the take states, in plain words, the exit rule it is scored on. A plan that fills stays open until one of its exit rules closes it; a plan that never fills lapses (section 7). Every study figure is a dated reading of the market it was measured in, not a permanent property. **Research behind the scoring, in short.** These are readings, each dated: * Exits do most of the work. On every tradable Binance pair 2021-01 to 2026-08, CoinRotator's exits earned +1.49 % a trade net of fees, against βˆ’0.37 % for the older take-profit exit on the same entries (CoinRotator's exit study). * A fixed take-profit or a price-level target cut off the large winners that pay for a trend book (internal study, 2026-10-06). * Stops trigger on a daily close, with no maximum distance (internal studies, 2026-10-07; the founders' rule). * Sizing by risk is where the stop rule earns its keep (internal study, 2026-10-06). * Which build of the CR trend is used matters less than the exits. Under CoinRotator's exit rules every trend build tested made money before and after July 2024 (internal study, 2026-10-09). * Fast invalidations earn the most per trade at a lower hit rate. Users prefer to stay with a trade longer. The scored plan is the steady version, and the faster versions run beside it as shadow lines, so live data shows the trade-off (section 7). ## 1. Selection rule The day's coin is picked by a query, not by a person: 1. At the **selection time** (section 3), build the eligible set from the universe rules in section 4. 2. For each eligible coin, count Shumi's hourly sentiment summaries for it (matched by the coin's upper-case symbol) in the 24 hours ending at the selection time. These are the same summaries the production "hottest coins" list reads. An hourly summary is written only for coins mentioned in Shumi's curated sentiment feed (about 56 coins a day), so the count measures how much the curated feed is talking about a coin. Only the hourly summaries count: daily, weekly and monthly roll-ups are also stored, written whenever anyone asks Shumi about a coin, and counting those would let usage steer the pick (on test data for 2026-10-12, ZEC's 3 hourly summaries became 5, level with SOL). 3. Remove any coin selected on one of the previous 7 scheduled days. 4. Select the coin with the highest count. Ties, including a day on which every eligible count is zero, go to the better (lower) market-cap rank. 5. If two eligible coins share a symbol, the count belongs to the one with the better market-cap rank; the other gets zero. 6. If the eligible set is empty, the day publishes a `no eligible coin` entry. It is a published attempt with no take. 7. **One open plan per coin.** A coin whose earlier plan in this record is still open (section 7) is skipped, and the next coin by count is selected. The earlier plan stays scored on its own. No study has measured the following days of the most-talked-about coin. The record is the first reading of its own selection rule, and the always-long plan on the same coin (section 8) keeps the pick itself from being scored as Shumi's choice. Each entry publishes the five highest counts next to the chosen coin, so anyone with access to the data can re-run the count and anyone else can see the ranking it produced. Why this shape: it picks the coin people are talking about, which is the one most worth distributing into its community. The baseline in section 8 is built on the same coin, so the pick itself is never scored as Shumi's choice. The count reads one day of hourly summaries and keeps the 50 highest. Matching them to the eligible set and steps 3 to 5 happen in the selection script. ## 2. Prompt, surface and model **Surface:** the Shumi web chat engine, driven by a **scheduled job** instead of a person. Once a day at 13:15 UTC (section 3), Shumi gets the message described below in a fresh shumi.ai chat, as any visitor would ask it. The job sends once, sends no follow-up and does not regenerate. Each day's entry links the public answer and shows when it was asked and which model was set to answer. Every answer is posted exactly as Shumi gave it. **Why the question asks for a reading, not a call.** Shumi answers with readings, and each reading lists its inputs and how old each one is. So each entry names the plan the data favours. **The daily question.** One message: the question "XRP (XRP): which plan does the data favour today: long, short or neither?", with the day's coin in place of XRP. Instructions for the answer's layout follow it. The answer must open with one line, "Data favours: LONG", "Data favours: SHORT" or "Data favours: NEITHER". Then one line per side, in the form "\$XRP | long | entry zone | stop | target | score/10". Each line copies the plan Shumi's price levels give for that side, with n/a in any empty slot. Then the exit rule, quoted exactly: "Exit: the plan ends on a daily close beyond its stop, when the trend turns against it, or on a reversal signal once it is 3% in profit. The target is not an exit." Then the single biggest risk and the venue Shumi would act at. Last, the source time of every input it used (a date, for inputs dated by day). An input past its age limit is marked stale and left out of the reading. **Exit line:** the founders' condition of 2026-10-09: the published take states the exit rule it is scored on, in plain words, so a reader can follow the same trade from the take alone. The `Exit:` line is the section 7 rule, fixed in the question so it cannot drift from what is scored: the stop is a daily close beyond it, the trend change is the site's trend turning to the opposite side, and the reversal exit applies only at 3 % profit or more. A take whose `Exit:` line is missing or reworded is published with the label `exit line missing` and still scored; the record's entry prints the rule either way. **Stance parsing:** the stance is the token on the first line that matches `^Data favours: (LONG|SHORT|NEITHER)$`. Anything else is `unparsed`. Nobody reads a stance out of prose. NEITHER is a full answer, scored as staying out (section 10). **Plan parsing:** each plan line is parsed with `^\$(\S+) \| (long|short) \| ([0-9.]+)-([0-9.]+) \| ([0-9.]+|n/a) \| ([0-9.]+|n/a) \| (\d+|n/a)/10$` into entry low, entry high, stop, target and **data score**. The **scored plan** is the line whose side matches the stance. The record scores the numbers as Shumi published them, so anyone can check a score from the entry and public prices. Shumi copies them from its price-levels data. When the stance is LONG or SHORT and its line is missing, does not parse, or lacks entry or stop, the entry is labelled `no plan` and is not scored. The X/10 figure is called the **data score** everywhere in the record, never "conviction". **Model:** no model is pinned. Changes to Shumi's model or instructions during the record are allowed, and each entry names the model set when it was asked. **Retries:** if the request fails with no answer, the job retries once after 10 minutes. Both attempts are published; the retry's answer is the take of record. ## 3. Cadence Every day, including weekends, all times UTC. | Step | Time (UTC) | | - | - | | Selection query runs | 12:15 | | Daily coin is registered for the on-chain data pre-fetch | by 12:20 | | Prompt is sent by the scheduled job | 13:15 | | Entry is published on the canonical record, X and Telegram | by 19:15 | | Posted into the coin's community | same UTC day | Why these times: they stay clear of the database's busy windows for scheduled data jobs, of the 00:00–03:00 window in which coin lookups still serve yesterday's trend, and of the hourly futures-data update at :00. The pre-fetch runs every 30 minutes and refreshes anything older than 30 minutes, so the hour between registration and prompt guarantees at least one pass. The 12:15 selection job registers the day's coin for the pre-fetch. **Publication time.** Each day's entry goes live by 19:15 UTC with Shumi's answer exactly as given. Its publication time `T` is the time the entry was added to the published record (the page history shows it), and scoring (section 7) counts from `T`. An entry written before it goes live is labelled "Prepared at". It gives its publication time in the first line added below it, so the score can be rebuilt from the record alone. An entry that goes live after 19:15 is published late with its real `T`; one not live by 00:00 UTC is a day with no published entry (section 12). A day counts as scheduled whether or not anyone is at a keyboard. A missed prompt is still a day with no published entry and resets the 14-day count (section 12). ## 4. Universe A coin is eligible at selection time when all of these hold: 1. Market-cap rank between 1 and 500. This is the live sentiment read's coverage: a live read of X runs only for the top 500 by market cap. 2. A crypto asset, not a real-world-asset row (stocks, commodities). Those rows have no market-cap rank, so rule 1 already excludes them; this rule makes it explicit. 3. Not a stablecoin, using the category rule already in production: a category ending in "stablecoin", excluding "Stablecoin Issuer". 4. Not a wrapped, bridged or liquid-staking derivative of another asset: no CoinGecko category matching `wrapped`, `bridged` or `liquid staking` (case-insensitive) among the coin's CoinGecko categories. 5. A current trend exists: the site shows a trend for the coin, computed from complete data. A stored sentiment summary no older than 5 hours is not required. Since 2026-10-06, a missing or stale stored read triggers a live read of the last 6 hours of X posts for any top-500 coin, so a stored summary is no longer a coverage condition. ## 5. Maximum age per input Each input carries its own source time. "Asked at" (the moment the prompt was sent) is shown separately and never stands in for an input's age. | Input | Source time | Maximum age at "asked at" | Source of the limit | | - | - | - | - | | Trend | the trend's as-of date | the as-of date is the selection day, and the trend is computed from complete data. The trend is dated by the 00:00 UTC close it was computed from, so at 13:15 UTC on Oct 13 a current trend reads "as of 2026-10-13"; the price levels read 2026-10-12 for the same close, because they date a daily bar by its open. | the site's trend | | Social sentiment | stored read: the hour it summarises; live read: the newest X post used | 6 hours | production: a stored hourly read, or a live read of the last 6h of X when the stored one is missing or older than 6h | | On-chain: KOL traders | upstream fetch time | 60 minutes, because the selected coin is the registered daily coin (otherwise 10 minutes) | production on-chain data settings | | On-chain: holders, wallet tags, largest-pool liquidity | upstream fetch time | 60 minutes, because the selected coin is the registered daily coin (otherwise 6 hours) | same | | Price levels (swings, averages, ATR, stop) | the levels' as-of date (open of the newest daily bar; daily close = 00:00 UTC) | the previous UTC day's 00:00 close. The levels turn unavailable past 30h. | Shumi's price levels; spot-dependent fields are computed per request from the live price | **On-chain coverage:** the on-chain data covers `eth`, `bsc`, `base`, `robinhood` and `sol` (Solana added 2026-10-06; its inclusion in coverage was open at registration). For a coin with no contract on one of these chains (BTC, for one), the take lists the inputs it used and says nothing about on-chain; the entry shows no on-chain field. That is not staleness and does not affect a clean day. On-chain data is never called sentiment or depth near spot. **Sentiment freshness, what is and is not built:** the live rule is age only (6h). The fuller rule that was proposed, which would also invalidate a reading after an abnormal price move or new coin news since it was taken, is **not built**; the production code has a hook for it and nothing more. This page freezes the 6h age limit only. If the invalidation rule ships during the record, it is a Shumi change, logged per entry like a prompt change, and the limit here stays 6h. **Live-read limits that can produce a stale input:** live reads are capped at 300 a day across all coins, regenerated at most once per 3h per coin, and skipped when the cache is down. In each case the stale stored row is served with its true age, or no read. The record publishes that as `stale input` or `no current sentiment read`, never hides it. **`stale input` rule:** if any input Shumi used is past its limit, the entry is published with the label `stale input` and the input's actual age. The day is clean only when Shumi's own output already disclosed that input as stale (and so did not base the stance on it). An input shown with no source time at all makes the day not clean. A `stale input` entry with a LONG or SHORT stance is still scored in section 7, and is also reported as its own subgroup. ## 6. Venue From the founders' product bar: every entry names the venue Shumi said it would act on. Pool TVL, including the on-chain largest-pool liquidity, is never presented as executable depth near spot; that is checked for every entry, not printed in the take. The venue is published verbatim and does not change the score. ## 7. Outcome: scoring a plan A take is scored as the plan it states, not as a trade opened at publication. Markets keep no fixed timetable, so neither does the record: a plan fills when price reaches its zone, and ends when the market invalidates it or a reversal signal takes profit. NEITHER is a full answer. ### Price data Daily bars in USD for the coin's CoinGecko id, built from CoinGecko's 4h OHLC (`/coins/{id}/ohlc`), one bar per UTC day (open = first 4h open, high = max, low = min, close = the 4h bar closing at 00:00 UTC). This is how CoinRotator builds the daily bars the levels come from. 1. The close of UTC day D is used only from 00:00 UTC on D+1. No fill, stop or exit inside day D reads it. A same-day close once reversed an internal study's result. 2. On the publication day, only 4h bars opening at or after `T` count. 3. Every CoinGecko response is archived raw with its request range, and the bar width it returned is recorded. A response whose bars are not 4h wide is rejected and requested again, never mixed in. 4. While a plan is open, the record appends each day's bar and each day's trend state to the entry, so the score can be rebuilt from the record alone. 5. If no price exists for a day a plan needs, the outcome is `incomplete`. It is published, not scored, and never dropped. ### Trend state The record reads the **CoinRotator trend the site shows** (the production state: SuperTrend 5 Γ— 1.5 on the coin in USD, BTC and ETH; UP when all three are up, DOWN when all three are down, HODL otherwise), for the previous completed UTC day. The record never shows a trend the site contradicts. Two other trend builds are published next to every entry as shadow lines and never scored: * CoinRotator's slower trend: agrees with the site's trend on about 65 % of days. * The site's state with a 20/50 EMA tie-breaker on days the two builds disagree. *Research:* under CoinRotator's exit rules on every tradable Binance pair 2021-01 to 2026-08, the site's state made +0.15 % / +1.26 % a trade before / after July 2024, the EMA tie-breaker +1.29 % / +1.34 %, and CoinRotator's slower trend +1.36 % / +1.67 % (internal study, 2026-10-09). Live data decides between them in a later version. ### Entry Bars after `T` are checked in order: 1. A LONG fills on a bar whose low is at or below the entry high, at the entry high or at the open if the bar opens below it. A SHORT fills on a bar whose high is at or above the entry low, at the entry low or at the open if it opens above it. 2. Before a fill, the plan **lapses** on the first of these events, and is published with that reason: * `invalidated before entry`: a daily close beyond the stop; * `ran without entry`: price reaches the target; * `trend turned`: the site's trend turns against the side (DOWN for a LONG, UP for a SHORT). 3. A plan with no fill and no lapse after 30 daily closes is published as `not triggered`. This backstop only lets the record close the line. For every plan that does not fill, the record publishes the coin's move from `T` to the lapse, and how close price came to the entry zone in ATR. Neither is scored. A pullback entry tends to miss the strongest moves (an internal study: on breakouts, the 14 % that never pulled back were the big moves), so the record shows them. ### Exit: CoinRotator's exit rules, with the founders' stop After the fill, the scored plan ends at the first of: 1. **Stop:** a daily close (00:00 UTC) beyond the stop published at `T`, exiting at that close. The stop is volatility-based: the founders' rule (the nearest swing\_5 below price for a LONG, above for a SHORT, βˆ“ 0.5 ATR, at least 1.5 ATR from the entry midpoint, no maximum distance; "unbroken" was dropped from the wording on 2026-10-09), as Shumi's price levels print it. It is never moved, widened or trailed. A gap through the stop can cost more than 1R. 2. **Reversal signal, trend change:** the site's trend turns to the opposite side (DOWN for a LONG, UP for a SHORT), exiting at that day's close, at any profit or loss. HODL does not end the plan. 3. **Reversal signal, take profit:** an opposite mean reversion point (as defined in CoinRotator's exit study, including its "last 14 band re-entries" behaviour) while the plan is at least 3 % in profit at that close, exiting at that close. There is **no time limit** on a filled plan. Plans still open at a checkpoint are marked at that day's close and labelled `open` (section 10). The plan's printed target is not an exit. When price reaches it, the record publishes `reached target` with the date, and the plan stays open. CoinRotator continuation re-entries are not scored. After a plan closes, the coin can be selected again (section 1). Published labels name the exit kind, never the indicator: `exit (stop)`, `exit (trend change)`, `exit (reversal signal)`. *Research:* CoinRotator's exits are the founders' current rule, and a founder is trading them live (2026-10-09). On every tradable Binance pair 2021-01 to 2026-08 they earned +1.49 % a trade net of a 0.2 % fee, +1.36 % before July 2024 and +1.67 % after (CoinRotator's exit study). A close-triggered stop beat the same stop triggered on a wick, on longs and shorts, and no stop cap beat the uncapped stop (internal studies, 2026-10-07). ### Shadow exits, published, not scored Each one runs on the same fill as the scored plan, so live data shows which works best. A later version can promote one. | Shadow line | Rule | | - | - | | Reversal signal invalidates | an opposite mean reversion point ends the plan at any profit or loss | | Stop beyond the reversal bar | the stop sits beyond the bar of the latest reversal signal on the plan's side, not the volatility stop | | 2-bar reversal | after the plan is 3 % in profit, the second consecutive daily close against it ends the plan (CoinRotator's "second consecutive" mode) | | Faster average on a mature trend | once the site's trend on the plan's side is at least 14 days old, a daily close beyond the 20-day EMA ends the plan (open at registration: the 14 days and the 20-day EMA) | | Target as printed | exit when price reaches the plan's target | *Research:* faster invalidations earn more per trade at a lower hit rate, while users prefer staying with a trade through deep pullbacks (a founder, 2026-10-09). The scored plan is the steady version. The shadows record the faster ones on the same trades. ### Size and result per plan * **Size:** Shumi's price levels' size under the founders' rule: 1 % of the account Γ· stop distance, for longs and shorts alike. Longs are not halved when BTC is below its 200-day: on 2026-10-14 the founders replaced the halving with full size plus one line of history in the answer (an internal study found halving a preference, not an edge). The 200-day split is still published (section 10). The founders' other 2026-10-09 answers on the stop stand: the 1.5 ATR minimum is measured from the entry midpoint; 120 days means 120 daily candles. The plan is scored on a fill in its zone, so it uses the plan's size, not the stop-only size quoted for buying at market. A size above 100 % of the account carries `needs_leverage`. * `risk = |entry βˆ’ stop| / entry`; gross move `g = (exit βˆ’ entry) / entry` for a LONG, `(entry βˆ’ exit) / entry` for a SHORT. * **Net R** `= (g βˆ’ c) / risk`, with `c` from section 9. One R is the loss the plan stated up front. * **Account result** `= net R Γ— risk %`, where risk % is 1. The bar (section 10) uses the account result. * Also published per plan: net % move, exit kind, days held, the best and worst close while open and the highest high and lowest low (in R and %), whether `reached target` happened, and the result of every shadow line. **Not scored but counted as attempts:** NEITHER, `unparsed`, `no plan`, every lapse reason, `not triggered`, `incomplete`, `no short venue` (section 9), errors and `no eligible coin`. **Resolution:** a plan resolves at its exit. The outcome is a **new line** appended to the record that references the entry id; the entry itself is never edited. **The stop rule as written by the founders** (2026-10-07): > **The rule, for every trade:** > > 1. **Where:** the nearest unbroken swing\_5 low within 120 days, minus 0.5 ATR. If that is closer than 1.5 ATR to entry, use 1.5 ATR. Shorts: the swing high, mirrored. (Unchanged from the spec.) > 2. **Trigger:** a daily close beyond the level (00:00 UTC). An intraday wick does not trigger it. > 3. **Size:** position = 1% of account Γ· stop distance (a 25% stop means a 4% position). Halve it when BTC is below its 200-day. *(Superseded 2026-10-14, before day one: no halving; see Size above.)* > 4. **No maximum distance.** When the stop is far, show the smaller position. Do not drop or grey out the setup. "Unbroken" was dropped on 2026-10-09: a swing that price closed through and then reclaimed still counts. ## 8. Baseline (Open at registration.) Both baselines use the **same coin over the same dates**, the same section 7 rules, the same costs and the same sizing. 1. **Always-long plan (the bar's baseline):** on every published day, whatever the stance, the LONG plan line Shumi published is scored under section 7. This is what taking the long plan every day earns without Shumi's reading. Shumi's contribution is its choice of side and of when to stay out. 2. **Hold from publication (context):** buy at the first price after `T`, sell when the scored plan exits (or at its lapse). Reported next to every plan. BTC over the same window is reported as market context. *Research:* the house yardstick is always the same coin on the same dates. Holding over the plan's own window is nearly the same trade as the plan, so it serves as context only. ## 9. Costs and funding **Round-trip cost `c` (open at registration):** 40 bps for coins ranked 1–100 at selection time, 100 bps for ranks 101–500, for fees on both legs plus slippage. The same `c` applies to the baselines. *Research:* the 2026 stop and exit studies used 0.4 % round trip; the 100 bps tier is a convention. **Funding is shown, never assumed zero.** For every filled plan on a coin with a perp at the named venue (or, failing that, at Hyperliquid), the record publishes realised funding over the hold, signed (paid or received), and the account result including it. Where no funding data exists, the field reads `funding: not available`, never 0. SHORT plans are reported with and without funding. *Research:* funding moved shorts taken after crash days from +3.10 % to βˆ’2.40 % a trade in 2025–26 (internal study), and an internal short strategy's long-held shorts received +2.52 % a trade in 2023–25. **Stop slippage, reported:** the mean result if every stop exit had filled 100 bps worse. **Shorts that cannot be held:** a SHORT whose named venue lists no perp or borrow for the coin at `T` is published as `no short venue` and not scored. ## 10. The bar A first version. The founders, 2026-10-09: the pass mark is work in progress, re-set from consolidated live data through a new version of this page. It is never adjusted against outcomes already seen. **First reading:** checked once, on the first day on which **30 scored plans** (LONG or SHORT, filled, exited) have resolved **and** those plans were entered in at least **8 different UTC weeks**. If either is short, the check moves forward a week at a time. **Confirmed reading:** checked once at **60 scored plans entered in at least 12 different weeks**, the same template as an earlier internal forward test. At each reading the record passes only if all of these hold, net of costs, in account result (section 7): 1. The mean account result of the scored plans is above 0, and the mean of weekly means (each entry week counted once) is above 0. 2. **Ahead of the always-long plan, day by day.** Across every published day in the period, Shumi's total account result is above the always-long plan's total. On each day Shumi's result is its scored plan's, or 0 for NEITHER, `unparsed`, `no plan` and plans that did not fill. The always-long result is the published LONG line's, or 0 if it did not fill or is missing. Open plans on either side are marked at that day's close. 3. At least 40 % of the scored plans end with net R above 0. *Research:* trend exits in our studies keep their winners long, and their hit rates ran 31–44 % (internal studies, 2026-10). A plan with a 1.5R target breaks even near 40 % before costs. 4. No scheduled attempt in the period is missing from the record. Condition 2 scores staying out directly: a NEITHER on a day the long plan lost counts for Shumi, and one on a day it won counts against. No separate cap on abstentions is needed. Each reading is published as **"passed"** or **"not passed"**, as a new dated decision. Until the first reading the record is "registered, unresolved". **Reported alongside, never part of the bar:** * median net R, and the mean without the single best plan; * the busiest entry week's share of the total, and the most-repeated coin's share; * splits by LONG / SHORT Γ— BTC above / below its 200-day, by calendar month, by rank 1–100 / 101–500, and by data score (0–4, 5–7, 8–10, and the 8/10-and-above subset paying customers act on); * the label `one-sided` if more than 85 % of scored plans are on one side; * fill rate, lapse reasons, NEITHER share; * every shadow exit and shadow trend line, scored the same way; * the hold-from-publication baseline and BTC. These are published as dated regime readings. No expected hit rate per regime is published. ## 11. Publication format Each entry carries this field list. The record's own words are "take", "reading", "plan", "result". It never says "accurate", "win rate", "proven" or "profitable"; counts are published as counts with their sample size. | Field | Content | | - | - | | Entry id | `R-YYYY-MM-DD` (retry: `R-YYYY-MM-DD-b`) | | Asked at | UTC timestamp the prompt was sent | | Published at (`T`) | UTC time the entry went live, and the delay from "asked at". An entry labelled "Prepared at" states `T` and the delay in its first appended line | | Coin | name, symbol, CoinGecko id, market-cap rank at selection | | Selection | the five highest counts from section 1, and whether a tie-break or an open-plan skip decided it | | Input ages | trend as-of; sentiment time, stored or live; on-chain fetch time per input, when the coin has on-chain data; price-levels as-of; each with its age at "asked at" | | Context at `T` | site trend, its age and days since its last flip; CoinRotator's slower trend; EMA tie-break trend; whether the stance is with or against the coin's trend; BTC's trend, BTC vs its 200-day and vs its prior cycle high; funding rate | | Labels | `stale input`, `exit line missing`, `no plan`, `no short venue`, `needs_leverage`, `incomplete`, `error`, `no eligible coin`, as applicable | | Stance | LONG, SHORT, NEITHER or `unparsed` | | Plans | both plan lines verbatim, parsed (entry zone, stop, target, data score), and the scored side | | Size | the size as printed, and the account risk % | | Exit rule | Shumi's `Exit:` line verbatim, and the section 7 rule in the same words | | One risk | verbatim from Shumi | | Venue | verbatim | | Full take | Shumi's verbatim answer | | Live Shumi link | the Send a Shumi share URL (`https://shumi.ai/s/`) | | Served by | the model set to answer, its provider, and the version of Shumi's instructions that served it | | Daily lines while open | that day's bar, site trend, and whether `reached target` occurred | | Outcome (appended at exit or lapse) | fill price and date or lapse reason; exit kind, price and date; gross move, net R, account result, with and without funding; best and worst point; every shadow line's result; the always-long plan's result; hold-from-publication and BTC over the same window; pullback depth at fill in ATR | Shumi's cycle-high price bet and its 25 / 50 / 75 % alert ladder are published verbatim if they appear, and never scored. **Canonical record:** an append-only page on the public docs site (served at docs.shumi.ai), one git commit per entry and per outcome, so "never edited or removed" is checkable from git history. Distribution, from the product bar: Shumi's own X and Telegram, plus the coin's community, each post linking the entry and the live Shumi link. ## 12. The 14-day run and the clean day The founders' success criterion for the record, quoted unchanged: > the daily record described under *Product bar* is published on each of 14 consecutive scheduled days and distributed from Shumi's own X and Telegram plus the coin's community. A day with no published entry resets the 14-day count (an entry that says `error` or `stale input` is published, and does not reset it). A published day is *clean* when its data age is correct, its links work, and it was distributed the same day; the run passes when β‰₯ 90 % of the 14 days are clean. The founders run it until it passes, then QA owns the cadence and the founders stop touching it The 14-day run measures whether the record is produced and distributed reliably. The bar in section 10 measures whether the takes are good enough to trade on. They are judged separately. # Evidence Source: https://docs.shumi.ai/evidence/studies The published studies, what each one tested, and how to check the walk-forward record yourself. Four studies are published at [shumi.ai/studies](https://shumi.ai/studies). The strategy studies list every outcome and the benchmark's scores are in the [studies repository](https://github.com/pxeodev/studies/blob/main/benchmark/data.js). ## What each study tested | Study | Published | What it tested | | - | - | - | | [Spring 2026 Rally: 23 Trades](https://shumi.ai/studies/regime-engine-april-may-rally) | May 13, 2026 | One live window in spring 2026 on Hyperliquid prices, with every closed outcome listed | | [400 Experiments. 3 Survived.](https://shumi.ai/studies/400-experiments) | Mar 25, 2026 | Hundreds of strategy variants, 2021 to 2025, and what real Binance funding costs did to a strong in-sample result | | [Walk-Forward Performance, 2024-2025](https://shumi.ai/studies/walk-forward-performance-2024-2025) | Mar 10, 2026 | Trained on 2021 to 2023, tested on 2024 to 2025, Binance funding charged per entry | | [Crypto AI Benchmark v2](https://shumi.ai/studies/crypto-ai-benchmark-v2) | Mar 11, 2026 | Several AI tools given the same trader questions, scored on a weighted rubric. Shumi was left out of the scored field | The 400-experiments and walk-forward studies tested an early version of the regime state. CoinRotator's current trend rules replaced it. Shumi no longer runs the engine from the spring 2026 rally study. ## Read the walk-forward record `shumi walkforward outcomes` lists the tracked walk-forward outcomes: each entry, each exit and the reason it closed. On 2026-09-23 it held one closed outcome (LINK, long, closed 2026-05-28), so its `summary` is a sample of one. `shumi walkforward signals` lists the entry and exit signals themselves (50 per call). **Terminal** ```bash theme={"dark"} shumi walkforward outcomes ``` **API** ```bash theme={"dark"} curl "https://api.shumi.ai/api/cli/walkforward?action=outcomes" \ -H "Authorization: Bearer shumi_sk_your_key_here" ``` `action` takes `signals`, `positions` or `outcomes`. Each outcome has these fields: | Field | Meaning | | - | - | | `symbol` | The coin | | `direction` | `long` or `short` | | `entryPrice`, `exitPrice` | Price at entry and at exit | | `entryDate`, `exitDate` | When it opened and closed | | `returnPct` | Return in percent | | `holdDays` | Days held | | `exitReason` | Why it closed | A `summary` block counts the total, wins and losses. ## Ask whether a signal has a validated record ```bash theme={"dark"} shumi signal-quality --asset BTC ``` Over the API, `GET /api/cli/signal-quality?asset=BTC`. From an AI agent, the `get_signal_quality` tool. `--signal-type` defaults to `mean_reversion`. The answer says whether a validated record exists for that signal on that asset. On 2026-09-23 BTC came back with `reliability_tier` `INSUFFICIENT_DATA` and the message "No validated edge exists for mean\_reversion BTC. Raw signal only." That reading means the signal has no validated record behind it. ## Recheck the results yourself Every claim on this page can be checked. * **Outcomes.** Every closed outcome in a strategy study is listed with its dates and prices. Pull the same dates from any exchange's price history and recompute the return. * **The walk-forward record.** `shumi walkforward outcomes` carries the same fields. Recompute any return from its entry and exit prices. * **Benchmark scores.** Every tool's score on every question and rubric dimension is in [`data.js`](https://github.com/pxeodev/studies/blob/main/benchmark/data.js) in the studies repository. * **Limits.** The walk-forward study and the benchmark each list their own gaps. # Overview Source: https://docs.shumi.ai/index What Shumi is, where to use it, and how to get your first answer. Shumi answers questions about crypto markets using live data: trend, funding, sentiment, narratives and market breadth. It covers spot markets and perpetual futures on 17 exchanges, led by Binance, Hyperliquid, Bitget, OKX and Bybit, plus the perp DEXes Aster, Variational and Lighter. See [full coverage](/platform/coverage). ## Ways to use Shumi > **[Web](https://shumi.ai/app)** > > Ask on the shumi.ai homepage, or use the full chat at shumi.ai/app. Your first question needs no account. > **[Terminal](/agents/cli)** > > `npm install -g shumi`, then `shumi login`. Needs Node 22 or later. > **[HTTP API](/api-reference/introduction)** > > Keys come from the CLI: install it, run `shumi login`, then `shumi keys create`. Then call `https://api.shumi.ai`. > **[AI agent](/agents/mcp)** > > Add `https://mcp.shumi.ai/mcp` as a connector in your MCP client. Every one of these reads the same data, so you get the same numbers wherever you ask. ## Ask your first question **On the web** **1. Open shumi.ai** Go to [shumi.ai](https://shumi.ai). You can ask your first question without an account. **2. Type a question and send it** Type in the **Ask a market question** box, for example "is BTC funding crowded?", and click **Run query**. Shumi fetches the data and writes the answer. **3. Continue in the full app** Under the answer, click **Continue in app** (or **Open app** next to the box). On [shumi.ai/app](https://shumi.ai/app), sign in with your email or a crypto wallet. A free account gets 10 questions, then 1 per day. **In the terminal** **1. Install the Shumi CLI** Needs Node 22 or later. ```bash theme={"dark"} npm install -g shumi ``` **2. Sign in** ```bash theme={"dark"} shumi login ``` **3. Get Shumi's verdict on a coin** ```bash theme={"dark"} shumi BTC ``` You get a verdict from bullish to bearish, the evidence behind it and its coverage: how many of its inputs answered. It is scored from trend, funding and sentiment. **4. Ask a question in plain words** ```bash theme={"dark"} shumi ask "is BTC funding crowded?" ``` To use Shumi from your own code or an AI agent, see the [API Quickstart](/quickstart). ## Terminal commands to try | You want to know | Command | Read more | | - | - | - | | What is Shumi's verdict on this coin? | `shumi signal SOL` | [Signals](/trade-decisions/signals) | | How many coins are trending up, sideways or down? | `shumi market health` | [Market State](/research/market-health) | | Where is funding crowded? | `shumi funding momentum` | [Funding](/trade-decisions/funding-momentum) | | Which coins match my filters? | `shumi scan` | [Market Screener](/research/market-screener) | | Which pairs could I trade against each other? | `shumi pairs suggestions` | [Pairs and Delta Neutral](/trade-decisions/pair-trading) | | Anything else, in plain words | `shumi ask "…"` | [Shumi Chat](/research/shumi-chat) | On the web, ask any of these as a normal question. ## Plans **Subscription** | Plan | Price | What you get | | - | - | - | | Free | Free | 10 questions to start, then 1 per day | | Plus | \$20 / month | 50 per day in the web chat | | Pro | \$200 / month | No limit | | Genesis | \$500 once | Same as Pro, for life | On the free plan, each terminal or API command also counts as one question. The daily question resets at 00:00 UTC. The first 10 never refill. **Pay per call** No subscription needed. Fund a wallet with USDC on Base, and each API call pays for itself: 0.005 USDC for a data call, 0.05 for a question, `pairs` or `walkforward`. A call that fails on our side is not charged. [Pay Per Call](/agents/payments) has the setup. [Plans and Quotas](/platform/access) has the details. ## Check the data and the method > **[How fresh is the data?](/platform/coverage#how-fresh-the-data-is)** > > Most responses show their age: `shumi signal BTC --agent | jq .meta.data_age_seconds`. Check it before you act on a funding rate or a price. Coverage lists the refresh schedule. > **[Does the method work?](/evidence/studies)** > > The studies publish every tracked outcome, the sample size, the test window and the losses. ## CoinRotator [coinrotator.app](https://coinrotator.app) is the screener. It applies fixed rules to the market data, so the same data always gives the same trend, streak and ranking. Shumi reads that data together with funding, sentiment and narratives, and weighs them into an answer. When an answer names a coin, it links to that coin's page on coinrotator.app, so you can see the numbers it started from. [CoinRotator](/coinrotator) lists the screener's pages. # Plans and Quotas Source: https://docs.shumi.ai/platform/access What each plan gives you, how the free counter works, and what you see when it runs out. Pick a plan, see how many questions it gives you, and check what you have left. Every question you ask Shumi uses one question from your plan. ## Plans | Plan | Price | Questions | | - | - | - | | Free | Free | 10 to start, then 1 per day | | Plus | \$20 / month | 50 per day, one budget shared by the web chat, the CLI and the API | | Pro | \$200 / month | No limit | | Genesis | \$500 once | Same as Pro, for life | On Plus, a web question uses one of the 50, and so does a CLI or API call when it writes a fresh AI answer or reading. [Run a bot or dashboard](/agents/cli#run-a-bot-or-dashboard) lists the ones that never do. Compare and buy plans at [shumi.ai/pricing](https://shumi.ai/pricing). ## How the free counter works A free account starts with 10 questions. They never refill. When they are gone you get 1 question per day, and the day resets at 00:00 UTC. On the web you can ask one question with no account, on each device. After that the page asks you to sign in. Email or a crypto wallet both work. On the free plan, every data call from the terminal, the API or an AI agent takes one question from the same counter. `shumi billing tier` never counts. ## What you see when you run out | Where | What happens | | - | - | | Web chat | "You've used your 10 free queries. Upgrade to keep going." Once the daily question is spent: "You've used today's 1 query. Resets at 00:00 UTC." A **See plans β†’** button sits under the message. | | Terminal, API, AI agent | The call answers `402 Payment Required` with an offer to pay for that one call in USDC. Live streams (`shumi watch`) run while you have questions left. Once the quota is spent they answer `429 RATE_LIMITED` instead, and a stream cannot be paid per call. | ## Check your plan ```bash theme={"dark"} shumi billing tier ``` Over the API, call `GET https://api.shumi.ai/api/cli/billing/tier` with your Bearer token. The call is free and works when your quota is spent. ```json theme={"dark"} { "schemaVersion": 1, "data": { "tier": "pro", "source": "manual", "expiresAt": null }, "meta": { "route": "billing/tier" } } ``` In `data`, `tier` is your plan (Plus shows as `access`), `source` is how you got it, and `expiresAt` is when it ends. `null` means no end date. ## Pay per call No subscription needed. Fund a wallet with USDC on Base (`shumi wallet create`, then `shumi wallet fund`) and each call pays for itself: 0.005 USDC for a data call, 0.05 for a plain-word question, `pairs` or `walkforward`. A call that fails on our side is not charged. `--auto-pay` pays without a prompt, up to \$0.10 per call by default. [Pay Per Call](/agents/payments) has the price table and the wallet setup. # Changelog Source: https://docs.shumi.ai/platform/changelog Updates to Shumi Chat, the CLI, the API and CoinRotator. **2026-09-27** The docs at docs.shumi.ai are rewritten task-first, with the commands and screens you use for each job. **2026-09-27** Search groups results into coins, on-chain, RWA perps, categories and pages, with filter chips and a `/` page menu. **2026-09-27** The percentage from the all-time low shows the rise over the low, on coin pages and in the screener. **2026-09-27** The RWA drawer says "7 contracts on 5 venues" when a venue lists the same asset more than once. **2026-09-27** 4h trends cover the full top 1,000 coins, using a major exchange's candles where the coin is listed there. **2026-09-26** RWA venue counts include only contracts with open interest or volume, and the drawer lists every one of them. **2026-09-26** Trade buttons on a coin's Derivatives rows open that market on 27 exchanges. **2026-09-26** Coin pages chart tokens on newer chains, and draw other coins' charts from an exchange that lists them. **2026-09-25** Funding APR uses each market's own settlement interval, so 4h perps show the full annual rate. **2026-09-25** Open interest, futures volume, funding and APR on a coin all come from the latest hourly reading. **2026-09-25** Web answers read pages live and check a page's dates and prices against today before quoting them. **2026-09-25** Shumi's market breadth covers the full top 1,000 coins at any hour, including while the nightly update runs. **2026-09-25** Shumi checks a coin's live price against three or more exchanges before quoting it or ranking it as a mover. **2026-09-25** Shumi compares a coin's current streak with its past runs of the same trend, including the median and longest run. **2026-09-25** `shumi ask` answers open with a full sentence and prefer short prose to tables. **2026-09-24** `shumi scan --sort` ranks coins by 24h or 7d move, streak or price, so the biggest movers come first. **2026-09-24** Coin lookups show the current trend, since when and for how many days. **2026-09-24** `shumi scan` filters by category and market cap, and category names match whatever the case or spacing. **2026-09-24** Ask what is pumping or dumping and the answer starts from the coins that moved most in 24h or 7d. **2026-09-22** Band levels and band position no longer appear in coin answers, the coin endpoints or the CLI schemas. **2026-09-03** Genesis is a one-time \$500 purchase. **2026-09-01** Recent coin and category searches are stored on your device. **2026-08-30** Chat stops scrolling for you when you scroll up during an answer. **2026-08-26** Applied CEX and DEX filters stay visible. Unfiltered tables keep coins that have no exchange data. **2026-08-25** Real-world assets that trade as perps on Binance are included in coverage. **2026-08-24** The real-world asset screener adds ticker search, filters, 4h, 24h and 7d price changes, and trend labels. **2026-08-19** Funding rates show the interval and the APR. Market pairs add a copy button for the contract address. **2026-08-19** You can give feedback under an answer. **2026-08-18** Streaming answers render tables, code blocks and Markdown. **2026-08-15** `https://api.shumi.ai` is the API hostname. **2026-08-12** `@shumi-ai/mcp` is on npm with 31 tools. **2026-08-12** An API reference for every endpoint, with the response envelope, error codes, authentication and quotas. **2026-08-11** The CLI warns before a session expires. **2026-08-11** Walk-forward tables say why they are empty. **2026-08-11** Aster and Lighter markets are covered, with 1h, 4h and 1d candles. **2026-08-11** Stale exchange quotes are left out of prices, and a ticker listed on more than one venue resolves by its asset name. **2026-08-10** The /ask page shows a worked example and explains what you get before you sign in. **2026-08-10** Coins without a market-cap rank keep their price history, and coins with no current price stay listed. **2026-08-07** Your account is ready as soon as you sign up. **2026-08-05** Real-world asset candles carry the timeframe they were built on. **2026-08-03** Rate limits count your own usage. Visitors who share a network address no longer share a limit. **2026-08-02** Mobile visitors can use the free question again, and two visitors no longer share one free question. **2026-08-01** New /upgrade page for comparing and buying plans. **2026-08-01** Signing in lands you in the app. **2026-08-01** Real-world assets can be found by company name as well as by ticker. **2026-08-01** Tickers written with punctuation or spaces resolve. **2026-08-01** Authentication failures return a machine-readable reason. **2026-08-01** Funding momentum is available for every perpetual we cover. **2026-08-01** Pair suggestions carry only the risk labels their backtest supports. **2026-07-30** Marketing pages load reliably. **2026-07-29** Narrative labels that differ only in punctuation count as one narrative. **2026-07-29** Different names for one real-world asset resolve to the same asset in trend and attention data. **2026-07-23** New /ask page, a direct entry point to Shumi. **2026-07-23** Crypto lookups no longer return tokenized stocks. **2026-07-22** Categories show 24h breadth and a trend indicator. **2026-07-22** Typo correction leaves crypto names and tickers as typed. **2026-07-19** Real-world asset lookups by company name tolerate typos. **2026-07-19** Company names resolve to their tickers in symbol lookups. **2026-07-19** Pair suggestions come only from trend setups, and describe each pair without a tier ranking. **2026-07-14** shumi.ai has a new design and rewritten copy. The pricing page shows signal receipts and studies above the plans. **2026-07-11** Ask Shumi about stocks, ETFs, metals and commodities, with funding on their perps. **2026-07-08** Free accounts get 10 questions to start, then 1 a day. **2026-07-04** `shumi rwa` covers real-world assets (RWA): stocks, ETFs, metals, commodities, indices and FX as perps. **2026-07-03** Shumi has a new logo across shumi.ai, the chat and CoinRotator. **2026-06-26** `shumi help` lists every command, and typing a ticker on its own, like `shumi BTC`, looks it up. **2026-06-24** Starter suggestions in Shumi Chat are hand-picked and shown in a set order, as compact chips above the question box. **2026-06-13** The Market Health page shows the current market state as a badge above the breadth chart. **2026-06-03** Shumi has paid plans. Compare them on the new pricing page. Free questions continue. **2026-05-18** The Shumi CLI has 90+ commands with stable JSON for agents, and `shumi watch` streams funding and regime changes. **2026-05-14** New study: How Shumi Tracked the Spring 2026 Rally. **2026-05-01** Coin pages show the 1h, 24h and 7d change next to the price, and search shows a live 24h change. **2026-04-03** Hover a live price in any screener to see its 1h and 24h change. **2026-04-03** Coin page charts follow the coin's most liquid on-chain pool, so small and new coins get a chart. **2026-03-28** 4h Alerts tag each coin with its narrative and the current market regime. **2026-03-28** Shumi documentation is live at docs.shumi.ai. **2026-03-27** The screener opens with a market bar: 24h market health change, BTC's 4h trend and Hot Narratives. **2026-03-25** New Studies section on shumi.ai, starting with the film "Who Said It". **2026-03-12** Ask Shumi on the shumi.ai homepage and watch each step of the answer as it runs. **2026-02-21** Create API keys to use Shumi from the CLI, your own servers and bots. **2026-02-20** The Shumi CLI is out. Run `npx shumi` to ask Shumi from your terminal. **2026-02-10** Sign in to Shumi with email, a social account or a wallet. **2026-02-02** shumi.ai is live, with Shumi Chat at shumi.ai/app. **2026-01-22** Ask your first question without signing in. **2026-01-12** Every answer ends with suggested follow-up questions you can tap. **2025-11-14** Search results show each coin's current trend and trend streak. **2025-07-28** Shumi reads social media sentiment for a coin and summarizes what people are saying. **2025-07-03** Meet Shumi, CoinRotator's AI assistant. Ask about any coin, trend or category at coinrotator.app/shumi. **2025-07-03** Screeners and coin pages show open interest, funding rate and futures volume, plus a CEX and DEX filter. **2024-12-20** New Coins screener for recently listed coins. **2024-04-22** The category list covers many more categories, so more coins sit in a narrative you can filter by. **2024-01-09** 4h Alerts list coins as their 4-hour trend changes, with the time of each change. **2023-10-26** Futures screeners for BingX, Bitget, KuCoin, MEXC and OKX. **2023-08-09** Prices update live in the screeners and on coin pages. **2023-06-30** New Categories page to compare the trend of every category in one table. **2023-03-28** New screeners: Binance and KuCoin spot, Binance and Bybit futures, Solana, low caps and trends. **2023-03-28** CoinRotator's new layout adds a sidebar, a watchlist, a page per category and a trend streak column. **2023-03-28** The CoinRotator TradingView indicator is linked from the menu. **2022-11-06** Market Health charts how many coins are in an uptrend, downtrend or HODL each day. **2022-10-21** Search for any coin or category from the header. **2022-10-11** Coin pages are split into Analysis, Price data and Trade tabs, with spot and derivatives markets listed under Trade. **2022-10-06** Dark mode. **2022-09-23** Choose the trend flavor behind the signals, including a Classic setting. **2022-09-10** The screener shows where each coin trades, on spot exchanges and derivatives venues, and filters by exchange. **2022-05-23** Coin pages show the launch date, launch price and return since launch. **2022-04-24** The screener shows the weekly trend beside the daily one, and filtered views can be shared by link. **2022-03-23** Coin pages show a description, contract addresses you can copy on every chain, and each coin's trend history. **2022-03-08** Switch the screener between daily and weekly signals. **2022-01-21** Filter the screener by category. **2022-01-08** Every coin has its own page with a price chart, its trend and the exchanges that list it. **2021-12-10** Filter the screener by trend type, market cap and trend length, and read how the signals work on the new FAQ page. **2021-10-22** CoinRotator launches: a screener that labels the top coins by market cap with their current trend. # Coverage Source: https://docs.shumi.ai/platform/coverage What you can look up with Shumi: any listed coin, any token with a DEX pool, perps on 17 exchanges, and real-world assets (RWA). You can look up almost any crypto asset. Every coin with a market listing works by ticker or name. Any token with a DEX pool works by its contract address, including a token launched minutes ago. Shumi also covers perpetual futures on 17 exchanges and real-world assets (RWA): stocks, ETFs, metals, commodities, indices and FX that trade as perps. ## Coins and tokens | You have | Use | You get | | - | - | - | | A ticker or a name | Ask in chat, or `shumi coin lookup PEPE`, `shumi coin by-name Pepe` | Price, market cap, supply and trend history. For the coins Shumi tracks in depth, also the 4h, 24h and 7d moves, funding and open interest | | A contract address | Ask in chat, or `shumi coin by-contract 0x… --chain base` | The same as a ticker lookup for a listed coin. For a token that trades only in DEX pools: price, 24h change, volume, liquidity, its top pool and the number of buys and sells | Contract lookups take `--chain`: `ethereum`, `bsc`, `solana`, `base` and more. [Coin Lookup](/research/coin-analysis) shows every way to find a coin. The market-wide trend counts in [Market State](/research/market-health) and the [screener](/research/market-screener) cover the 1,000 or so largest coins, 991 on 2026-09-23. ## Perpetual futures Shumi reads funding rates and open interest across 17 exchanges. The main ones, largest first: | Kind | Exchanges | | - | - | | Centralised | Binance, Bitget, OKX, Bybit, MEXC, Gate.io, HTX, KuCoin, BingX, Deribit, Kraken, Crypto.com | | Perp DEXes | Hyperliquid, Aster, Variational, Lighter | ## Real-world assets (RWA) Stocks, ETFs, metals, commodities, indices and FX are covered as perpetual futures on Hyperliquid, Binance, Aster, Lighter and Variational. On 2026-09-23 the full list held 272 assets. `shumi rwa list` shows the first 200; `GET /api/cli/rwa/assets?top=1000` returns them all. Look one up with `shumi stock AAPL` or `shumi commodity GOLD`. Some tickers name both a coin and a real-world asset. GOLD is one. [Coin Lookup](/research/coin-analysis) shows how to say which one you mean. ## Kinds of data | Kind | Command | | - | - | | Verdict on one coin | `shumi signal BTC` | | Coin facts, risk, history | `shumi coin lookup BTC`, `coin risk BTC`, `coin historical BTC` | | Market breadth and global figures | `shumi market health`, `market global` | | Funding rates and alerts | `shumi funding momentum`, `funding alerts` | | Regime signal log | `shumi regime signals`, `regime history BTC` | | Sentiment and narratives | `shumi sentiment coin BTC`, `shumi narratives` | | Categories | `shumi category list` | | Screener | `shumi scan --trend UP` | | Pair trades, delta-neutral setups | `shumi pairs suggestions`, `pairs delta-neutral` | | Large holders, tracked wallets | `shumi holders watchlist`, `shumi wallets watchlist` | | Podcast and call transcripts | `shumi transcripts highlights` | | Real-world assets | `shumi rwa list` | | Signal record | `shumi walkforward signals`, `shumi walkforward outcomes`, `shumi signal-quality --asset BTC` | ## How fresh the data is Most responses carry two fields in `meta`: `as_of`, when the data was last refreshed, and `data_age_seconds`, how old it was when you asked. ```json theme={"dark"} "meta": { "route": "funding/momentum/BTC", "as_of": "2026-09-23T13:46:56.725Z", "data_age_seconds": 3 } ``` Each kind refreshes on this schedule: | Data | Refresh | | - | - | | Prices | Live | | Market health, global figures | Every 5 minutes | | Signal, funding momentum, coin risk, coin lookup, resolve, futures, real-world assets, sentiment, narratives, holders, wallets | Every hour | | Screener, trends | Every 4 hours | | Coin history, signal quality, pairs | Daily | | Regime | When the regime flips | # FAQ Source: https://docs.shumi.ai/platform/faq Short answers to the questions traders ask most about Shumi. > **How do I ask about a position I hold?** > > Tell Shumi the coin and your side, long or short, and it answers for that position. [Shumi Chat](/research/shumi-chat) has tips for asking. > **Why did it pick the wrong GOLD?** > > Some tickers name more than one asset. GOLD is both a crypto token and the metal. Run `shumi resolve GOLD` to see every match. [Coin Lookup](/research/coin-analysis) shows the other ways to pin an asset down. > **Why is today's answer different from yesterday's?** > > The inputs moved. A verdict is built from the daily and weekly trend, funding and sentiment; the regime read only affects coverage, the count of inputs that answered. Most of those refresh every hour. Two calls a few seconds apart can differ if an input refreshed in between. [Signals](/trade-decisions/signals) shows how the score is put together. > **I ran out of questions. What now?** > > On the free plan you get 10 questions to start, then 1 per day, and the day resets at 00:00 UTC. Wait for the reset, buy a plan at [shumi.ai/pricing](https://shumi.ai/pricing), or, in the terminal and API, pay per call in USDC. [Plans and Quotas](/platform/access) has the prices. > **How fresh is the data?** > > Most responses carry `meta.data_age_seconds`, the age of the data in seconds when you asked. Prices are live, funding and signals refresh every hour, and the screener every 4 hours. [Coverage](/platform/coverage) has the full refresh table. > **Where can I see how the signals performed?** > > The published studies at [shumi.ai/studies](https://shumi.ai/studies) list every outcome and every limit. [Evidence](/evidence/studies) explains how to read both. > **Can I use Shumi from my own code or an AI agent?** > > Yes. Keys come from the CLI: install it, run `shumi login`, then `shumi keys create`. Call `https://api.shumi.ai` with the key, or add `https://mcp.shumi.ai/mcp` as a connector in your MCP client. The [API Quickstart](/quickstart) walks through both. # API Quickstart Source: https://docs.shumi.ai/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 ` 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). # Coin Lookup Source: https://docs.shumi.ai/research/coin-analysis Price, market cap, trend history and the risk picture for one coin, and the same for a stock or commodity. Look up one coin by ticker, name, id or contract address and get its price, market cap, supply, trend history and perpetual funding. On the web, ask in chat: "tell me about SOL". ## Find the coin **Terminal** ```bash theme={"dark"} shumi coin lookup SOL shumi coin by-name Solana shumi coin by-id solana shumi coin by-contract 0xdAC17F958D2ee523a2206206994597C13D831ec7 --chain ethereum ``` A contract address needs `--chain` (ethereum, bsc, solana, base and others). **API** ```bash theme={"dark"} curl "https://api.shumi.ai/api/cli/coin/lookup?symbol=SOL" \ -H "Authorization: Bearer shumi_sk_your_key_here" ``` Also `/api/cli/coin/by-name/{name}`, `/api/cli/coin/by-id/{id}` and `/api/cli/coin/by-contract/{address}?chain=ethereum`. **AI agent** Use the `lookup_coin` tool with `by` set to `symbol`, `name`, `id` or `contract`. ## Read the current trend `currentTrend` is the coin's daily trend now. `shumi coin lookup SOL` prints it on its first line: ``` current trend UP since 2026-09-19 (8 days, as of 2026-09-26) ``` In JSON: ```json theme={"dark"} "currentTrend": { "trend": "UP", "since": "2026-09-19", "days": 8, "asOf": "2026-09-26", "incompleteDayExcluded": false, "awaitingDailyUpdate": false, "legsIncomplete": false } ``` | Field | Meaning | | - | - | | `trend` | `UP`, `DOWN` or `HODL` | | `since`, `days` | The day the trend started, and how many days from `since` to `asOf`, both counted | | `asOf` | The last complete day the trend is measured on | | `incompleteDayExcluded`, `awaitingDailyUpdate` | `true` between 00:00 and 03:00 UTC while today's trend is still being built. The value shown is yesterday's | | `legsIncomplete` | `true` when the newest day was built from less data than usual. Treat the trend as provisional | The daily trend updates shortly after 00:00 UTC. With both update flags `false` and `since` equal to today, the trend flipped today. `currentTrend` is `null` when the coin has no recent trend data. It needs CLI 0.9.0 or later. ## Read price, supply and trend history `trends` is the history of trend runs, oldest first. `coin.deltas` gives the 4h, 24h and 7d moves. | Field | Meaning | | - | - | | `coin.currentPrice`, `coin.priceSource` | Latest price and the exchange it came from | | `coin.marketCap`, `coin.circulatingSupply`, `coin.totalSupply` | Size and supply | | `coin.ath`, `coin.atl` | All-time high and low | | `coin.deltas` | Price change over 4h, 24h and 7d, in percent | | `coin.futuresData` | Open interest, 24h futures volume and funding APR on the perpetual | | `trends` | Daily trend runs, each UP, DOWN or HODL (the coin's trend disagrees across quote currencies, so it counts as sideways), with `start`, `end` and `streak` in days | ## Get the risk picture in one call ```bash theme={"dark"} shumi coin risk SOL ``` `shumi coin risk BTC ETH SOL` returns a list, with shorter field names. Over the API: `/api/cli/coin/risk/{symbol}`. In an agent: `get_coin_risk`. | Field | Meaning | | - | - | | `price`, `price_source`, `price_as_of` | Latest price, where from, when | | `funding_rate`, `funding_interval_hours` | Funding per interval, in percent, and the interval length | | `funding_apr` | The same rate as a yearly percentage | | `funding_paying_side` | `longs` or `shorts`: who pays right now | | `carry_if_long`, `carry_if_short` | What a perpetual position pays or receives, as a sentence | | `trend_daily`, `trend_weekly` | `bullish` or `bearish`, with `trend_daily_since` and `trend_weekly_since` | | `sentiment_stance`, `sentiment_summary` | The crowd's stance, such as `accumulation`, and a one-line summary. `null` when Shumi has no read on the coin | | `btc_correlation` | How closely the coin moves with BTC (DOGE 0.8). `null` for BTC itself | Funding applies to perpetual positions only. ## When a ticker names two assets Some tickers belong to a coin and to a stock or commodity. `shumi resolve GOLD` returns both: ```json theme={"dark"} "matches": [ {"id": "cyberdragon-gold", "name": "CyberDragon Gold", "assetType": "crypto"}, {"id": "xyz:GOLD", "name": "GOLD", "assetType": "commodity"} ] ``` Coin commands take the crypto match. For the metal, use `shumi commodity GOLD`. `resolve` matches the ticker first and the name only when no ticker matches. So `shumi resolve Ethereum` finds a token whose ticker is `ethereum`. Pass `ETH` instead, or look up a name with `shumi coin by-name Ethereum`. Over the API: `/api/cli/resolve?q=GOLD`. In an agent: `resolve_coin`. ## Look up a stock or commodity ```bash theme={"dark"} shumi stock AAPL shumi commodity GOLD ``` Both return the asset's price, its trend and the funding on the perpetual that tracks it. | Field | Meaning | | - | - | | `price`, `priceAsOf` | Latest price and when it was taken | | `trend.daily`, `trend.weekly` | `UP`, `DOWN` or `HODL` on the daily and weekly chart | | `funding.apr` | Funding on the perpetual, as a yearly percentage. The stock or metal itself pays none | | `funding.openInterest` | Open interest on the perpetual | | `funding.markPx` | The perpetual's mark price | | Where | How | | - | - | | API | `GET /api/cli/rwa/symbol/{symbol}` | | AI agent | `get_rwa_asset` | | Every asset | `shumi rwa list` prints the first 200. `GET /api/cli/rwa/assets?top=1000` returns all of them. [Coverage](/platform/coverage#real-world-assets-rwa) lists the venues | # Market State Source: https://docs.shumi.ai/research/market-health 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 **Terminal** ```bash theme={"dark"} shumi market health ``` Add `--context` for the fuller bundle described below. **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. **AI agent** Connect the [MCP server](/agents/mcp) and call `get_market_health`, with `context: true` for the fuller bundle. 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 | Ask it in chat: [Is the market getting stronger or weaker this week, and is BTC leading or lagging it?](https://shumi.ai/app?q=Is%20the%20market%20getting%20stronger%20or%20weaker%20this%20week%2C%20and%20is%20BTC%20leading%20or%20lagging%20it%3F\&cta=docs-market-health) ## 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 **Terminal** ```bash theme={"dark"} shumi regime signals shumi regime history BTC ``` Bare `shumi regime` prints help only. **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. **AI agent** Call `get_regime` with `view: "signals"`, or with `symbol` for one coin's history. 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. # Market Screener Source: https://docs.shumi.ai/research/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 **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} ``` **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" ``` **AI agent** Use the `scan_coins` tool with `sort_by: "change24h"`. Add `sort_order: "asc"` for the losers. 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. # Sentiment and Narratives Source: https://docs.shumi.ai/research/sentiment 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 **Terminal** ```bash theme={"dark"} shumi sentiment coin BTC shumi sentiment market shumi sentiment slopes ``` Other views: `latest`, `summary`, `narratives`, `categories`, `health`, `entity-slopes`, `category `, `narrative `. **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`. **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. ## 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`. # Shumi Chat Source: https://docs.shumi.ai/research/shumi-chat Ask about any coin, sector, narrative or the whole market, and get one read that weighs trend, funding, sentiment and positioning together. Shumi is a crypto market analyst you talk to. Ask about a coin, a sector, a narrative or the whole market. Shumi works out which readings your question needs and pulls them from 40 live data tools. Then it weighs them into one answer: where the trend stands, what funding and positioning show, what people are saying and what has changed. When an answer names a coin, it links to that coin's page on [CoinRotator](/coinrotator), so you can see the numbers behind it. ## What you can ask | Ask about | For example | What Shumi reads | | - | - | - | | One coin | "Is SOL's uptrend still healthy?" | The daily trend (and weekly when you ask), how long it has run, funding, open interest and sentiment | | A token by contract | "What is 0x6982…1933 on Ethereum?" | The token behind the address, then the same read as any coin | | The whole market | "Is the market risk-on right now?" | How many coins trend up, sideways or down, whether that recently flipped, BTC dominance and market stress | | Today's movers | "What's pumping today?" | The biggest 24h and 7d gainers and losers | | Sectors | "Which categories are heating up?" | Trend, movers and sentiment for each category | | Narratives | "Which narratives are gaining attention?" | Narrative momentum and the coins behind each theme | | Funding and positioning | "Which coins have the highest funding right now?" | Perp funding ranked across the market, and the market's funding temperature | | Pairs and carry | "Give me a pair trade for this week" | [Pair](/trade-decisions/pair-trading) setups and funding spreads across 17 exchanges | | Engine signals | "What are Shumi's engines signalling on BTC?" | Open tracked entries in the regime and trend engines, the regime engine's recent signals and its record on the coin, and the futures signal log | | Stocks, metals and indices | "How is gold doing?" | Real-world assets that trade as perps, with price, trend and funding | | Smart money | "What are tracked wallets buying?" | Moves by tracked holders and wallets | | What people are saying | "What are the shows saying about ETH?" | Highlights from crypto show transcripts, recent posts on X and a live web search | Ask a follow-up in the same chat and Shumi keeps the context: "and how does that compare with last month?" works. ## Where you can ask **Web** Ask your first question in the **Ask a market question** box on [shumi.ai](https://shumi.ai) and click **Run query**. No account needed. To keep asking, click **Continue in app** under the answer and sign in with your email or a crypto wallet. Answers stream in with tables, code and formatting. If you scroll up while an answer is streaming, the page stops scrolling for you. **Terminal** ```bash theme={"dark"} shumi ask "how is BTC funding looking?" ``` You get text in the terminal, or JSON when you pipe the output. **API** ```bash theme={"dark"} curl -X POST "https://api.shumi.ai/api/cli" \ -H "Authorization: Bearer shumi_sk_your_key_here" \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"how is BTC funding looking?"}]}' ``` The answer streams back. The [API Quickstart](/quickstart#get-an-api-key) shows how to create a key. **AI agent** Connect the [MCP server](/agents/mcp) and use the `ask_shumi` tool. The data is the same wherever you ask. Only the layout changes. ## In the full chat at shumi.ai/app | You want to | Do this | | - | - | | Start over | Click **New chat** next to the send button, or in the **History** panel | | Open an old conversation | Open the **History** panel | | Stop an answer half-way | Click **Stop** | | Ask a follow-up | Type it in the same chat. Shumi keeps the context of the conversation | | Use a suggested question | Click it. It is sent as a new question | | Report a bad answer | Under the answer, click **Give feedback** next to "Something wrong or missing?" | ## What a question costs Each chat question uses one question from your plan. | Plan | Questions | | - | - | | No account | 1 | | Free | 10 to start, then 1 per day | | Plus | 50 per day in the web chat | | Pro and Genesis | No limit | When you run out, the web shows "You've used your 10 free queries. Upgrade to keep going." or "You've used today's 1 query. Resets at 00:00 UTC.", with a **See plans β†’** button. Over the API you get `402 Payment Required` instead, and you can pay 0.05 USDC per question. [Plans and Quotas](/platform/access) explains both. > [!TIP] > > Use a command for facts with an exact answer. "What is ETH funding right now?" is `shumi funding momentum --symbol ETH`, which is faster and gives you the figures without the wording. Use chat for questions that need judgement, such as "Is ETH funding higher than last month?" ## Getting a good answer * **Name the coin.** Some tickers belong to more than one asset. `GOLD` is both a token and the metal. If you are unsure, run `shumi resolve GOLD` first. * **Ask several things at once if you like.** Shumi plans the data for each part and fetches it in parallel. * **Ask for specific data.** "What is the funding and trend picture on SOL?" gets a sharper answer than "Should I buy SOL?". * **Want the raw figures?** Use a command such as `shumi signal SOL` for the numbers without the write-up. # Funding Source: https://docs.shumi.ai/trade-decisions/funding-momentum Perp funding per coin as an APR, ranked against every perp in the market, plus market temperature and funding alerts. Funding is what perp longs and shorts pay each other to hold a position. Shumi turns each coin's rate into a yearly APR, ranks it against every perp it tracks, and gives the whole market a temperature. ## Get funding for one coin or the market **Terminal** ```bash theme={"dark"} shumi funding momentum --symbol BTC shumi funding momentum ``` Bare `shumi funding` prints help only. **API** ```bash theme={"dark"} curl "https://api.shumi.ai/api/cli/funding/momentum?symbol=BTC" \ -H "Authorization: Bearer shumi_sk_your_key_here" ``` **AI agent** Connect the [MCP server](/agents/mcp) and call `get_funding_momentum`, with `symbol` for one coin. ## Read one coin ```json theme={"dark"} {"symbol":"BTC","apr":11,"ratePct":0.0013,"intervalH":1,"source":"hyperliquid","tier":"neutral","percentile":0.65} ``` | Field | Meaning | | - | - | | `apr` | Funding as a yearly rate, in percent. `11` means 11% a year | | `ratePct` | The raw rate per funding interval, in percent | | `intervalH` | Hours between funding payments on the source venue | | `source` | The venue the rate came from | | `percentile` | Where this APR sits among every perp in the snapshot (616 in the example). `0.65` means higher than 65% of them | | `tier` | The percentile as a label | The tier uses the exact percentile; the response shows it rounded to two decimals, so a displayed `0.80` can still be `neutral`. | Percentile | Tier | | - | - | | 0.90 and above | `hot` | | 0.80 to 0.89 | `warm` | | 0.21 to 0.79 | `neutral` | | 0.11 to 0.20 | `cool` | | 0.10 and below | `cold` | `--symbol` answers for any perp in the snapshot. The market-wide call returns: * a fixed watch list of large coins, 43 in the example, sorted by APR * `market`: the market `temperature`, such as `neutral`, and the median APR it is read from * `distribution`: `p10` to `p90`, `min`, `max` and `totalAssets` ## Read the market temperature `market.temperature` reads the median perp's funding against the resting rate. Hyperliquid and Variational charge a fixed interest component, so about 10.95% APR is what a perp pays with no crowding at all. Only funding above or below that is positioning. `medianPremiumApr` is that difference: | `medianPremiumApr` | Temperature | | - | - | | 20 or more | `hot` | | 5 to 20 | `warm` | | -5 to 5 | `neutral` | | -20 to -5 | `cool` | | below -20 | `cold` | For example: `"temperature":"neutral","medianApr":11,"medianPremiumApr":0`. `positive`, `negative` and `total` count the coins on the watch list. Quote `medianApr` as the market level, not `avgApr`: one broken market can pull the average anywhere. Ask it in chat: [Which perps have the highest and lowest funding APR right now, and where does BTC rank?](https://shumi.ai/app?q=Which%20perps%20have%20the%20highest%20and%20lowest%20funding%20APR%20right%20now%2C%20and%20where%20does%20BTC%20rank%3F\&cta=docs-funding) ## What positive and negative funding cost you Positive funding: longs pay, shorts receive. Negative funding: shorts pay, longs receive. `shumi coin risk BTC` spells it out for the coin in `funding_paying_side`, `carry_if_long` and `carry_if_short`, for example "Long perpetual positions pay funding at +11.0% APR." > [!NOTE] > > Funding applies to perpetual positions only. A spot position pays and receives nothing. Funding tells you who is crowded and what a held position costs. For timing, pair it with the trend in a [signal](/trade-decisions/signals). ## See funding alerts ```bash theme={"dark"} shumi funding alerts ``` API: `GET /api/cli/funding/alerts`. Agent tool: `get_funding_alerts`. | Field | Meaning | | - | - | | `asset` | The coin | | `triggerZone` | The zone funding entered, for example `negative` | | `fundingAtTrigger`, `fundingIntervalH` | The rate when it fired, and the funding interval in hours | | `source` | The exchange | | `firedAt` | When it fired | # Pairs and Delta Neutral Source: https://docs.shumi.ai/trade-decisions/pair-trading Long one coin against another, or the same coin long on one venue and short on another to collect the funding gap. `shumi pairs` covers two trades. A pair trade is long one coin and short a related one, so you earn on the ratio between them. A delta neutral trade is the same coin long on one venue and short on another, so price cancels out and you keep the funding gap. ## Get pair suggestions **Terminal** ```bash theme={"dark"} shumi pairs suggestions shumi pairs suggestions --symbol ETH --limit 5 ``` Bare `shumi pairs` prints help only. **API** ```bash theme={"dark"} curl "https://api.shumi.ai/api/cli/pairs?action=suggestions" \ -H "Authorization: Bearer shumi_sk_your_key_here" ``` On pay per call ([Pay Per Call](/agents/payments)) this route costs 0.05 USDC. It refreshes daily. **AI agent** Connect the [MCP server](/agents/mcp) and call `get_pair_suggestions`. Its `mode` parameter picks `suggestions`, `delta-neutral`, `history` or `signal`. You get 10 suggestions (`--limit` changes that) out of `totalPairsAnalyzed` (for example 200), plus `gateStats` (pairs per gate outcome) and `concentrationWarnings` (a coin repeated across suggestions). ## Read one suggestion Read `description` for the trade, for example `"Long TAO / Short ETH"`. Read `signalState.daysActive` and `isNew` for how long it has been on, and `ratioTrend.bandPosition` for how stretched the ratio already is (near 1 means most of the move has happened). Then the fields: | Field | Meaning | | - | - | | `long`, `short` | Each leg: `symbol`, `name`, `currentTrend` (UP, [HODL](/research/market-health#count-the-coins-trending-up-sideways-or-down) or DOWN) and `trendStreak` in days | | `ratioTrend.summary` | Who is winning, e.g. "TAO outperforming ETH" | | `ratioTrend.canonicalRatio` | The price ratio the trend is measured on. `canonicalBasis` says which way round | | `ratioTrend.bandPosition` | Where the ratio sits in its band: 0 at the lower band, 1 at the upper | | `signalState` | `isNew`, `daysActive`, `entryRatio`, `currentRatio`, `unrealizedPnl` (a fraction since entry) and `bandDrift` | | `status`, `reason` | `ACTIVE` with "All 6 gates passed" for every listed pair | | `sharedCategories`, `commonExchanges`, `commonExchangeCount` | What the two coins have in common and where both trade | | `backtest` | `tier`, `sharpe`, `trades`, `backtestDate` from a fit on past data | | `riskMetrics` | `maxDrawdown`, `profitFactor`, `avgHoldDays` from the same fit | Two fields carry their own warning in every response. `backtest.sharpeBasis`: the Sharpe is an in-sample fit dated January 2026, often on fewer than 10 closed outcomes, so do not rank pairs by it. `riskMetrics.maxDrawdownBasis`: drawdown counts closed outcomes only, so a position that sat near its stop for weeks and recovered records 0. Real drawdown is larger. `priceRatioLongOverShort` is the long coin's price over the short coin's, for charting the pair. Ask it in chat: [Which pair trades are active right now, and how stretched is each ratio?](https://shumi.ai/app?q=Which%20pair%20trades%20are%20active%20right%20now%2C%20and%20how%20stretched%20is%20each%20ratio%3F\&cta=docs-pair-trading) ## Check one pair or the history ```bash theme={"dark"} shumi pairs signal --token-a eth --token-b sol shumi pairs history ``` `pairs signal` returns `status`, `reason` and a `signal` with `long` and `short`. ETH and SOL came back long SOL, short ETH: the data sets the direction, whichever order you type the tokens. `pairs history` returns daily `snapshots`. Each has `pairCount` and a `pairs[]` list, and each pair has: | Field | Meaning | | - | - | | `long`, `short` | Each side's `symbol`, `priceChange24h` and `trend` | | `metrics.matchDays` | Consecutive days the two coins' trends have matched | | `metrics.spreadPct` | The price spread between the two, in percent | | `metrics.compositeScore` | 0 to 100: 30% from `matchDays`, 70% from `spreadPct` | ## Get delta neutral suggestions ```bash theme={"dark"} shumi pairs delta-neutral shumi pairs delta-neutral --symbol RUNE --exchange binance --limit 5 ``` Add `--dex-only` to keep only decentralised venues. API: `GET /api/cli/pairs?action=delta-neutral`. Each item: | Field | Meaning | | - | - | | `strategy.long`, `strategy.short` | Per venue: `exchange`, `funding_interval`, `funding_rate_apr`, `funding_rate_1h`, `next_funding_time`, `volume_24h` | | `expected_net_apr` | Short-leg APR minus long-leg APR, if both rates held all year | | `spread_1h` | The same gap per hour, in percent | | `projected_30day_return` | `expected_net_apr` scaled to 30 days | | `liquidity.oi_rank` | Open-interest rank of the coin | | `description` | The trade in one sentence | For example: "Go long RUNE on Binance (8h funding) and short RUNE on Kraken (1h funding) for a net APR of 4361.60%." Before the APR, read `volume_24h` on both legs (Kraken RUNE: \$474k) and `next_funding_time`. An extreme rate on a thin book can be gone at the next payment. ## What a two-venue trade puts at risk > [!WARNING] > > Each leg has its own margin account. A sharp move puts one leg deep in profit and the other deep in loss, and the losing venue liquidates it without knowing you are hedged elsewhere. * Funding on either venue can change sign at any interval, so the gap can close or invert. * You pay four fills: in and out on each venue. On a small `spread_1h` that can exceed the carry. * Both legs are yours to place. Until the second fills you hold a plain directional position. # Signals Source: https://docs.shumi.ai/trade-decisions/signals One verdict per coin, from bullish to bearish, with the evidence behind it and its coverage. `shumi signal BTC` gives one verdict for a coin, built from four readings: trend on the daily and weekly chart, funding, sentiment and the regime read. The first three set the score. The fourth counts toward coverage only. You get the verdict, the score behind it, its coverage and the evidence as plain sentences. ## Get a verdict **Terminal** ```bash theme={"dark"} shumi signal SOL ``` Bare `shumi SOL` does the same. Add `--agent` for JSON. **API** ```bash theme={"dark"} curl "https://api.shumi.ai/api/cli/signal/SOL" \ -H "Authorization: Bearer shumi_sk_your_key_here" ``` **AI agent** Connect the [MCP server](/agents/mcp) and call `get_signal` with `symbol`. An unknown ticker returns `404` with "Check the ticker, or use /api/cli/resolve to find it." `shumi resolve ` finds the right symbol. ## What comes back | Field | Meaning | | - | - | | `verdict` | `strong-bull`, `bull`, `neutral`, `bear` or `strong-bear` | | `score` | The number the verdict is cut from, in steps of 0.5 | | `confidence` | Coverage: `high`, `medium` or `low`, by how many of the four readings answered. The field keeps its API name. | | `evidence` | Plain sentences describing the readings, including some that did not change the score (funding at 0, a neutral stance, BTC correlation) | | `sources` | Whether `risk_context`, `funding_momentum`, `regime_active` and `sentiment_coin` each came back `fulfilled` or `rejected` | | `as_of` | Time of the freshest reading used | A real evidence list for BTC: ```json theme={"dark"} "evidence": [ "trend (daily) is bullish since 2026-09-19T00:00:00.000Z", "trend (weekly) is bullish since 2026-08-16T00:00:00.000Z", "sentiment stance (from risk-context): accumulation", "funding APR 11.00% (percentile 0.65, tier neutral)" ] ``` Ask it in chat: [What is the signal verdict on SOL right now, and what evidence is behind it?](https://shumi.ai/app?q=What%20is%20the%20signal%20verdict%20on%20SOL%20right%20now%2C%20and%20what%20evidence%20is%20behind%20it%3F\&cta=docs-signals) ## How the score is built The score starts at 0. Each reading adds to it or subtracts from it. | Reading | Effect on score | | - | - | | Daily trend | up +1, down -1, sideways 0 | | Weekly trend | up +1, down -1, sideways 0 | | Sentiment stance | accumulation +1, capitulation +0.5, exhaustion -0.5, distribution or euphoria -1, neutral 0 | | Funding APR | above 30% -1, above 10% +0.5, below -10% +1, otherwise 0 | Trend is the same UP, HODL or DOWN state the [market breadth counts](/research/market-health#count-the-coins-trending-up-sideways-or-down) use, read on the daily and on the weekly chart. An UP or DOWN trend adds an evidence line that says bullish or bearish, with the date the current state began. A HODL trend adds no line. A stance appears only when sentiment has set one; [Sentiment and Narratives](/research/sentiment) explains the words. Regime counts toward coverage and does not move the score. | Score | Verdict | | - | - | | 2.5 or more | `strong-bull` | | 0.5 to 2 | `bull` | | above -0.5 and below 0.5 | `neutral` | | -2 to -0.5 | `bear` | | -2.5 or less | `strong-bear` | Coverage (the `confidence` field) is `high` when all four readings answered, `medium` for two or three, `low` for fewer. It says how much of the evidence came back, not how likely the verdict is to be right. The readings refresh on their own schedules, so two calls minutes apart can give different scores. Read `as_of`. For the carry behind the funding line, see [Funding](/trade-decisions/funding-momentum).