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

# Current Regime

> Current HMM-detected market regime with enrichment

<Note>
  To use the playground, enter your API key in the **X-API-Key** field above.
  Don't have a key? [Get one free →](/api-reference/keys/generate)
</Note>

**Tier:** Free ✅
**Cache TTL:** 300 seconds (5 min)

## Regime States

| Regime               | Description                        |
| -------------------- | ---------------------------------- |
| `BULL_TRENDING`      | Strong uptrend with momentum       |
| `BEAR_TRENDING`      | Strong downtrend with distribution |
| `HIGH_VOLATILITY`    | Elevated vol — reduced sizing      |
| `DISTRIBUTION`       | Smart money offloading             |
| `WHALE_ACCUMULATION` | Large entity accumulation          |
| `RISK_ON`            | Risk appetite elevated             |
| `LOW_VOLATILITY`     | Compression — breakout pending     |
| `ACCUMULATION`       | Stealth accumulation at support    |

## Response Fields

| Field                      | Type              | Description                                                        |
| -------------------------- | ----------------- | ------------------------------------------------------------------ |
| `regime`                   | string            | Current regime label                                               |
| `confidence`               | float             | HMM confidence score (0–1)                                         |
| `btc_price`                | float \| null     | BTC price at detection time                                        |
| `detected_at`              | datetime \| null  | When the regime was detected                                       |
| `cached`                   | bool              | Whether response is from cache                                     |
| `cache_ttl_seconds`        | int               | Seconds remaining in cache                                         |
| `strength`                 | string \| null    | `STRONG` / `MODERATE` / `WEAK` based on confidence                 |
| `sub_regime`               | string \| null    | Granular sub-classification (e.g. `MOMENTUM_CONFIRMED`)            |
| `volatility_state`         | string \| null    | `EXPANDING` / `COMPRESSED` / `NORMAL` / `ELEVATED` / `CONTRACTING` |
| `chop_score`               | float \| null     | Market choppiness 0.0 (trending) → 1.0 (choppy)                    |
| `breakout_imminent`        | bool \| null      | `true` when `LOW_VOLATILITY` + confidence ≥ 0.70                   |
| `compatible_strategies`    | string\[] \| null | Strategy types that suit this regime                               |
| `incompatible_strategies`  | string\[] \| null | Strategy types to avoid in this regime                             |
| `transition_probabilities` | object \| null    | Probability of transitioning to each next regime                   |
| `regime_age_hours`         | float \| null     | Hours the current regime has been active                           |

<RequestExample>
  ```bash curl theme={null}
  curl https://api.aioka.io/v1/regime/current \
    -H "X-API-Key: aik_free_your_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "regime": "BULL_TRENDING",
    "confidence": 0.84,
    "btc_price": 67124.0,
    "detected_at": "2026-04-03T10:00:00Z",
    "cached": true,
    "cache_ttl_seconds": 290,
    "strength": "STRONG",
    "sub_regime": "MOMENTUM_CONFIRMED",
    "volatility_state": "NORMAL",
    "chop_score": 0.22,
    "breakout_imminent": false,
    "compatible_strategies": ["momentum", "trend_following", "breakout", "dip_buying"],
    "incompatible_strategies": ["short_momentum", "mean_reversion"],
    "transition_probabilities": {
      "BULL_TRENDING": 0.72,
      "WHALE_ACCUMULATION": 0.18,
      "HIGH_VOLATILITY": 0.10
    },
    "regime_age_hours": 4.5
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/regime/current
openapi: 3.1.0
info:
  title: AIOKA Intelligence API
  description: |

    ## AI-powered crypto market intelligence

    AIOKA Intelligence API provides real-time access to our AI Council verdicts,
    market signals, regime detection, and Ghost Trader entry signals.

    ### Tiers
    - **Free**: 100 calls/day — Verdict + Regime
    - **Basic** ($49/mo): 1,000 calls/day — + Signals
    - **Pro** ($199/mo): 10,000 calls/day — + Council + Ghost

    ### Authentication
    Pass your API key in the `X-API-Key` header:

    ```
    X-API-Key: aik_free_xxxxxxxxxxxx
    ```

    ### Get your API key
    `POST /v1/keys/generate` (free tier, no credit card)
  contact:
    name: AIOKA Support
    url: https://docs.aioka.io/
    email: api@aioka.io
  license:
    name: Commercial
    url: https://aioka.io/terms
  version: 1.0.0
servers:
  - url: https://api.aioka.io
    description: Production — AIOKA Intelligence API
security: []
paths:
  /v1/regime/current:
    get:
      tags:
        - Regime
      summary: Current Market Regime
      description: |-
        Returns the current HMM-detected market regime.

        AIOKA uses a Hidden Markov Model trained on 8 regime states to classify
        the current BTC market structure.

        **Tier:** Free ✅
        **Cache TTL:** 300 seconds (5 min)
        **Rate limit:** 100 calls/day, 2/minute

        ### Regime states
        - `BULL_TRENDING` — Strong uptrend
        - `BEAR_TRENDING` — Strong downtrend
        - `HIGH_VOLATILITY` — Elevated vol
        - `DISTRIBUTION` — Smart money selling
        - `WHALE_ACCUMULATION` — Large accumulation
        - `RISK_ON` — Risk-on environment
        - `LOW_VOLATILITY` — Compression
        - `ACCUMULATION` — Stealth accumulation
      operationId: get_regime_current_v1_regime_current_get
      responses:
        '200':
          description: Current regime
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegimeCurrentResponse'
        '401':
          description: Invalid or missing API key
        '429':
          description: Rate limit exceeded
      security:
        - APIKeyHeader: []
components:
  schemas:
    RegimeCurrentResponse:
      properties:
        regime:
          type: string
          title: Regime
        confidence:
          type: number
          title: Confidence
        btc_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Btc Price
        detected_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Detected At
        cached:
          type: boolean
          title: Cached
        cache_ttl_seconds:
          type: integer
          title: Cache Ttl Seconds
        strength:
          anyOf:
            - type: string
            - type: 'null'
          title: Strength
        sub_regime:
          anyOf:
            - type: string
            - type: 'null'
          title: Sub Regime
        volatility_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Volatility State
        chop_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Chop Score
        breakout_imminent:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Breakout Imminent
        compatible_strategies:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Compatible Strategies
        incompatible_strategies:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Incompatible Strategies
        transition_probabilities:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Transition Probabilities
        regime_age_hours:
          anyOf:
            - type: number
            - type: 'null'
          title: Regime Age Hours
        regime_v2:
          anyOf:
            - type: string
            - type: 'null'
          title: Regime V2
        regime_v2_compatible_strategies:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Regime V2 Compatible Strategies
      type: object
      required:
        - regime
        - confidence
        - btc_price
        - detected_at
        - cached
        - cache_ttl_seconds
      title: RegimeCurrentResponse
      example:
        breakout_imminent: false
        btc_price: 67124
        cache_ttl_seconds: 290
        cached: true
        chop_score: 0.22
        compatible_strategies:
          - momentum
          - trend_following
          - breakout
          - dip_buying
        confidence: 0.84
        detected_at: '2026-04-03T10:00:00Z'
        incompatible_strategies:
          - mean_reversion
          - range_trading
        regime: BULL_TRENDING
        regime_age_hours: 4.5
        strength: STRONG
        sub_regime: BULL_TRENDING_EARLY
        transition_probabilities:
          BULL_TRENDING: 0.72
          HIGH_VOLATILITY: 0.18
          OTHER: 0.1
        volatility_state: NORMAL
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: 'Your AIOKA Intelligence API key (format: aik_{tier}_{random})'
      in: header
      name: X-API-Key

````