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

# Regime Performance Stats

> Historical Ghost Trader win rate and P&L aggregated by market regime

<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)
**Rate limit:** Free 100/day, 2/min. Basic 1,000/day, 30/min. Pro 10,000/day, 100/min.

Historical Ghost Trader performance broken down by HMM market regime. Only
`is_valid=TRUE` validated trades since the 2026-04-12 clean-slate cutoff are
counted. Regimes are sorted by win rate descending so the best-performing
regime always appears first.

Use this endpoint to understand which market conditions AIOKA's Ghost Trader
performs best in — and which regimes to watch out for.

## Response Fields

| Field               | Type           | Description                                            |
| ------------------- | -------------- | ------------------------------------------------------ |
| `regimes`           | array          | Per-regime stats sorted by `win_rate` DESC             |
| `best_regime`       | string \| null | Regime with the highest win rate (null when no trades) |
| `worst_regime`      | string \| null | Regime with the lowest win rate (null when no trades)  |
| `total_trades`      | int            | Total validated closed trades across all regimes       |
| `overall_win_rate`  | float          | Win rate across all regimes (0–100)                    |
| `since`             | string         | Clean-slate cutoff date (ISO 8601)                     |
| `generated_at`      | string         | Human-readable Prague CEST/CET timestamp               |
| `cached`            | bool           | Whether the response was served from cache             |
| `cache_ttl_seconds` | int            | Remaining cache TTL in seconds                         |

### RegimeStatsItem fields

| Field            | Type   | Description                                               |
| ---------------- | ------ | --------------------------------------------------------- |
| `regime`         | string | HMM regime name (e.g. `BULL_TRENDING`, `HIGH_VOLATILITY`) |
| `trades`         | int    | Total trades recorded in this regime                      |
| `wins`           | int    | Winning trades (total P\&L > 0)                           |
| `losses`         | int    | Losing trades (total P\&L ≤ 0)                            |
| `win_rate`       | float  | Win rate 0–100                                            |
| `avg_pnl_pct`    | float  | Average P\&L % per trade                                  |
| `avg_hold_hours` | float  | Average hold time in hours                                |
| `total_pnl_usd`  | float  | Cumulative USD P\&L for this regime                       |

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "regimes": [
      {
        "regime": "BULL_TRENDING",
        "trades": 5,
        "wins": 4,
        "losses": 1,
        "win_rate": 80.0,
        "avg_pnl_pct": 2.14,
        "avg_hold_hours": 18.3,
        "total_pnl_usd": 1240.50
      },
      {
        "regime": "ACCUMULATION",
        "trades": 3,
        "wins": 2,
        "losses": 1,
        "win_rate": 66.7,
        "avg_pnl_pct": 1.08,
        "avg_hold_hours": 12.5,
        "total_pnl_usd": 485.20
      }
    ],
    "best_regime": "BULL_TRENDING",
    "worst_regime": "HIGH_VOLATILITY",
    "total_trades": 8,
    "overall_win_rate": 62.5,
    "since": "2026-04-12",
    "generated_at": "24 Apr 2026, 10:00 CEST",
    "cached": false,
    "cache_ttl_seconds": 300
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/regime/stats
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/stats:
    get:
      tags:
        - Regime
      summary: Regime Performance Stats
      description: >-
        Historical Ghost Trader win rate and P&L aggregated by market regime.


        Only validated trades (`is_valid=TRUE`) since the clean-slate date

        (2026-04-12) are counted. Regimes are sorted by win rate descending so

        the best-performing regime always appears first.


        **Tier:** Free ✅

        **Cache TTL:** 300 seconds (5 min)

        **Rate limit:** Free 100/day, 2/min. Basic 1,000/day, 30/min. Pro
        10,000/day, 100/min.


        ### Response fields

        | Field | Type | Description |

        |-------|------|-------------|

        | `regimes` | array | Per-regime stats sorted by win_rate DESC |

        | `best_regime` | string \| null | Regime with highest win rate (null
        when no trades) |

        | `worst_regime` | string \| null | Regime with lowest win rate (null
        when no trades) |

        | `total_trades` | int | Total validated closed trades |

        | `overall_win_rate` | float | Win rate across all regimes (0-100) |

        | `since` | string | Clean-slate cutoff date (ISO 8601) |

        | `generated_at` | string | Prague CEST/CET timestamp |

        | `cached` | bool | Whether response was served from cache |

        | `cache_ttl_seconds` | int | Cache TTL in seconds |


        ### RegimeStatsItem fields

        | Field | Type | Description |

        |-------|------|-------------|

        | `regime` | string | HMM regime name |

        | `trades` | int | Total trades in this regime |

        | `wins` | int | Winning trades (pnl > 0) |

        | `losses` | int | Losing trades (pnl ≤ 0) |

        | `win_rate` | float | Win rate 0-100 |

        | `avg_pnl_pct` | float | Average P&L % per trade |

        | `avg_hold_hours` | float | Average hold time in hours |

        | `total_pnl_usd` | float | Cumulative USD P&L in this regime |
      operationId: get_regime_stats_v1_regime_stats_get
      responses:
        '200':
          description: Per-regime Ghost Trader performance statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegimeStatsResponse'
        '401':
          description: Invalid or missing API key
        '429':
          description: Rate limit exceeded
      security:
        - APIKeyHeader: []
components:
  schemas:
    RegimeStatsResponse:
      properties:
        regimes:
          items:
            $ref: '#/components/schemas/RegimeStatsItem'
          type: array
          title: Regimes
        best_regime:
          anyOf:
            - type: string
            - type: 'null'
          title: Best Regime
        worst_regime:
          anyOf:
            - type: string
            - type: 'null'
          title: Worst Regime
        total_trades:
          type: integer
          title: Total Trades
        overall_win_rate:
          type: number
          title: Overall Win Rate
        since:
          type: string
          title: Since
        generated_at:
          type: string
          title: Generated At
        cached:
          type: boolean
          title: Cached
        cache_ttl_seconds:
          type: integer
          title: Cache Ttl Seconds
      type: object
      required:
        - regimes
        - best_regime
        - worst_regime
        - total_trades
        - overall_win_rate
        - since
        - generated_at
        - cached
        - cache_ttl_seconds
      title: RegimeStatsResponse
      example:
        best_regime: BULL_TRENDING
        cache_ttl_seconds: 290
        cached: true
        generated_at: 12 Apr 2026, 10:00 CEST
        overall_win_rate: 62.5
        regimes:
          - avg_hold_hours: 18.3
            avg_pnl_pct: 2.14
            losses: 1
            regime: BULL_TRENDING
            total_pnl_usd: 1240.5
            trades: 5
            win_rate: 80
            wins: 4
        since: '2026-04-12'
        total_trades: 8
        worst_regime: HIGH_VOLATILITY
    RegimeStatsItem:
      properties:
        regime:
          type: string
          title: Regime
        trades:
          type: integer
          title: Trades
        wins:
          type: integer
          title: Wins
        losses:
          type: integer
          title: Losses
        win_rate:
          type: number
          title: Win Rate
        avg_pnl_pct:
          type: number
          title: Avg Pnl Pct
        avg_hold_hours:
          type: number
          title: Avg Hold Hours
        total_pnl_usd:
          type: number
          title: Total Pnl Usd
      type: object
      required:
        - regime
        - trades
        - wins
        - losses
        - win_rate
        - avg_pnl_pct
        - avg_hold_hours
        - total_pnl_usd
      title: RegimeStatsItem
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: 'Your AIOKA Intelligence API key (format: aik_{tier}_{random})'
      in: header
      name: X-API-Key

````