> ## Documentation Index
> Fetch the complete documentation index at: https://shumi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask a natural-language question

> Answers a question in plain words. Shumi picks the data the question needs, fetches it and writes the answer. Paid per call, it costs 0.05 USDC.

The answer comes back as one JSON object with `text` and `steps`. This route does not use the standard envelope: its errors are a bare `{ "error": "..." }` object.



## OpenAPI

````yaml /api-reference/openapi.json post /api/cli
openapi: 3.1.0
info:
  title: Shumi API
  description: >-
    Market data, verdicts and plain-word answers for crypto and real-world
    assets. Data routes return a versioned envelope that holds either `data` or
    `error`.


    The `shumi` CLI and the `@shumi-ai/mcp` MCP server call the same routes.
  version: 1.0.0
servers:
  - url: https://api.shumi.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Ask
    description: Questions in plain words, answered by Shumi.
  - name: Coins
    description: Single-asset lookup, risk context, sentiment, and history.
  - name: Market
    description: Market-wide prices, breadth, and baselines.
  - name: Categories
    description: Category listings, membership, and sentiment.
  - name: Sentiment
    description: Crowd sentiment and narrative momentum.
  - name: Trade decisions
    description: Regime, funding, futures, pairs, and per-coin verdicts.
  - name: Unlocks
    description: Scheduled token unlocks for one coin or across the market.
  - name: Tracking
    description: Watched holders, wallets, baskets, and transcripts.
  - name: RWA
    description: >-
      Real-world assets that trade as perps: stocks, ETFs, metals, commodities,
      indices and FX.
  - name: Streaming
    description: Live NDJSON streams.
  - name: Account
    description: Your plan.
paths:
  /api/cli:
    post:
      tags:
        - Ask
      summary: Ask a natural-language question
      description: >-
        Answers a question in plain words. Shumi picks the data the question
        needs, fetches it and writes the answer. Paid per call, it costs 0.05
        USDC.


        The answer comes back as one JSON object with `text` and `steps`. This
        route does not use the standard envelope: its errors are a bare `{
        "error": "..." }` object.
      operationId: ask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                messages:
                  type: array
                  description: >-
                    Conversation history. The last message must have role
                    `user`.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                      content:
                        type: string
                raw:
                  type: boolean
                  default: false
                  description: >-
                    Return only `steps`, the data Shumi fetched, without a
                    written answer.
            examples:
              simple:
                summary: One-shot question
                value:
                  messages:
                    - role: user
                      content: Is BTC funding crowded right now?
      responses:
        '200':
          description: The answer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: The written answer. Absent when `raw` is true.
                  steps:
                    type: array
                    description: The data Shumi fetched to answer.
                    items: {}
        '400':
          $ref: '#/components/responses/PlainError'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/PlainError'
        '429':
          $ref: '#/components/responses/PlainError'
components:
  responses:
    PlainError:
      description: Error. This route returns a bare { error } object.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    PaymentRequired:
      description: >-
        Your free questions are used up. The body is an x402 challenge: pay for
        this one call in USDC on Base and resend it with the `X-PAYMENT` header.
        A data call costs 0.005 USDC; a plain-word question, `pairs` or
        `walkforward` 0.05 USDC.
      content:
        application/json:
          schema:
            type: object
            properties:
              x402Version:
                type: integer
              accepts:
                type: array
                items:
                  type: object
                  properties:
                    scheme:
                      type: string
                    network:
                      type: string
                    maxAmountRequired:
                      type: string
                      description: >-
                        Price in USDC's smallest unit (6 decimals): `5000` is
                        0.005 USDC.
                    resource:
                      type: string
                    payTo:
                      type: string
                    asset:
                      type: string
                      description: USDC contract on Base.
                    maxTimeoutSeconds:
                      type: integer
                    extra:
                      type: object
          example:
            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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key (`shumi_sk_…`) or a session JWT. Create a key with `shumi
        login` and `shumi keys create`.

````

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