API Overview

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 and the MCP server both call it.

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.

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.

{
  "schemaVersion": 1,
  "data": {
    "symbol": "BTC",
    "verdict": "strong-bull",
    "score": 3.5,
    "coverage": "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. Prices are live, funding and signals refresh every hour and the screener every 4 hours. Coverage has the full table.

​

Handle an error

A failed call replaces data with error.

{
  "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	Quota used up on a call that cannot be paid per call: a paid plan’s daily limit, a live stream, or a Free account when pay-per-call is unavailable
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.

POST /api/cli, the plain-word question route, returns { "text": "...", "steps": [...] } and 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. Plus is $20 a month for 50 questions a day; Pro is $200 a month with no limit.

To see which plan the API applies to your token:

curl https://api.shumi.ai/api/cli/billing/tier \
  -H "Authorization: Bearer $SHUMI_TOKEN"

{ "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 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

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.