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

# Resolve the caller's entitlement

> Reports the tier the gate will actually apply to this credential, so a client never has to guess why a request was refused.



## OpenAPI

````yaml /api-reference/openapi.json get /api/cli/billing/tier
openapi: 3.1.0
info:
  title: Shumi API
  description: >-
    Typed crypto trade-intelligence endpoints. Every response is wrapped in a
    versioned envelope, so a client can tell a successful payload from an error
    without inspecting HTTP status alone.


    The same surface backs the `shumi` CLI and the `@shumi-ai/mcp` MCP server.
  version: 1.0.0
servers:
  - url: https://api.shumi.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Ask
    description: Natural-language queries answered by the Shumi engine.
  - 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 signal synthesis.
  - name: Tracking
    description: Watched holders, wallets, baskets, and transcripts.
  - name: RWA
    description: 'Real-world assets: equities, metals, and commodities.'
  - name: Streaming
    description: Long-lived NDJSON streams.
  - name: Account
    description: Entitlement and tier.
paths:
  /api/cli/billing/tier:
    get:
      tags:
        - Account
      summary: Resolve the caller's entitlement
      description: >-
        Reports the tier the gate will actually apply to this credential, so a
        client never has to guess why a request was refused.
      operationId: getTier
      responses:
        '200':
          description: Entitlement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
              example:
                schemaVersion: 1
                data:
                  tier: pro
                  source: manual
                  expiresAt: null
                  identity:
                    kind: apiKey
                    userId: 42
                    walletAddress: null
                meta:
                  ts: '2026-08-11T15:22:43.000Z'
        '403':
          $ref: '#/components/responses/AuthRequired'
components:
  schemas:
    Envelope:
      type: object
      description: >-
        Success envelope. `schemaVersion` only changes on a breaking shape
        change, so a pinned client can detect one.
      required:
        - schemaVersion
        - data
        - meta
      properties:
        schemaVersion:
          type: integer
          example: 1
        data:
          description: Route-specific payload.
        meta:
          type: object
          properties:
            ts:
              type: string
              format: date-time
              description: When this response was produced.
            as_of:
              type: string
              format: date-time
              description: Timestamp of the underlying data, when it carries one.
            data_age_seconds:
              type: integer
              description: Age of the underlying data. Present alongside `as_of`.
    Error:
      type: object
      required:
        - schemaVersion
        - error
      properties:
        schemaVersion:
          type: integer
          example: 1
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - BAD_REQUEST
                - AUTH_REQUIRED
                - AUTH_INVALID
                - RATE_LIMITED
                - UPSTREAM_4XX
                - UPSTREAM_5XX
                - NETWORK
                - INTERNAL
            message:
              type: string
            details:
              description: Present when the route can say something more specific.
  responses:
    AuthRequired:
      description: No credential presented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            schemaVersion: 1
            error:
              code: AUTH_REQUIRED
              message: 'Authentication required. Run: shumi login'
  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.