API Overview - Shumi Docs

The Shumi API returns market data and verdicts as JSON over HTTPS. The CLI and the MCP server 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.

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,
    "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 lists how often each kind of data refreshes.

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

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 shows the challenge and how to answer it. Plans and Quotas covers the plans. 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.

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.

​Authenticate a request

​Read the response

​Handle an error

​Know what a call costs

​Stream live data

Authenticate a request

Read the response

Handle an error

Know what a call costs

Stream live data