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

# Performance by Regime (Multi-Asset)

> Ghost Trader win rate and P&L aggregated by market regime across all 7 councils

## Overview

Returns Ghost Trader performance aggregated by market regime across **all 7
councils** — BTC, ETH, SOL, ADA, TAO, Gold, EUR/USD. Each validated closed
trade carries the regime label that was persisted at entry time; the endpoint
UNIONs every per-asset table and groups by regime so the aioka.io
"Performance by Regime" widget can paint a single chart spanning the whole
system.

**Tier:** Public ✅ — No API key required
**Cache TTL:** 300 seconds (5 min)
**Rate limit:** 60 calls / IP / minute

<Note>
  Only validated closed trades with a non-NULL regime are counted. Legacy
  rows that lack a regime label simply do not appear in any bucket — they do
  not break the response. Each asset writes its **own native** regime: BTC /
  ETH / SOL / ADA / TAO read from `regime_history`; Gold writes Gold-native
  regimes (`SAFE_HAVEN_DEMAND`, `INFLATION_HEDGE`, …) via its dedicated
  detector; EUR/USD writes the same way.
</Note>

## Response Fields

| Field               | Type             | Description                                                                       |
| ------------------- | ---------------- | --------------------------------------------------------------------------------- |
| `regimes`           | array            | Per-regime rows, sorted by `trades` DESC, then `win_rate` DESC                    |
| `total_trades`      | integer          | Sum of trades across all regimes (excludes NULL-regime trades)                    |
| `assets_included`   | array of strings | Asset tables that contributed (`["BTC","ETH","SOL","ADA","TAO","GOLD","EURUSD"]`) |
| `since`             | string           | Clean-slate cutoff date (`"2026-04-12"`)                                          |
| `generated_at`      | string           | UTC ISO timestamp                                                                 |
| `cached`            | boolean          | Whether response was served from cache                                            |
| `cache_ttl_seconds` | integer          | Cache TTL                                                                         |

### Per-regime row

| Field         | Type    | Description                                               |
| ------------- | ------- | --------------------------------------------------------- |
| `regime`      | string  | Regime label (e.g. `BULL_TRENDING`, `SAFE_HAVEN_DEMAND`)  |
| `trades`      | integer | Total trades closed in this regime                        |
| `wins`        | integer | Trades with `pnl > 0`                                     |
| `losses`      | integer | Trades with `pnl <= 0`                                    |
| `win_rate`    | float   | **Fraction 0.0–1.0** (e.g. `0.833` = 83.3%)               |
| `avg_pnl_pct` | float   | Mean PnL per trade as percentage points (`1.24` = +1.24%) |
| `total_pnl`   | float   | Cumulative USD PnL within this regime                     |

<Warning>
  `win_rate` is a fraction (0.0–1.0), not a percentage (0–100). Multiply by
  100 for display. This differs from `/v1/regime/stats` which returns the
  percentage form for BTC-only.
</Warning>

<RequestExample>
  ```bash curl theme={null}
  curl https://api.aioka.io/v1/ghost/regime-performance
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.get("https://api.aioka.io/v1/ghost/regime-performance")
  for row in resp.json()["regimes"]:
      print(f"{row['regime']:<22} trades={row['trades']:>3}  "
            f"win_rate={row['win_rate'] * 100:5.1f}%  "
            f"pnl=${row['total_pnl']:>8.2f}")
  ```

  ```typescript TypeScript (Next.js SSR) theme={null}
  export const revalidate = 300;  // ISR — W-1 compliant

  export default async function Page() {
    const data = await fetch(
      "https://api.aioka.io/v1/ghost/regime-performance",
      { next: { revalidate: 300 } },
    ).then(r => r.json());
    return <RegimeChart data={data} />;
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "regimes": [
      {
        "regime": "BULL_TRENDING",
        "trades": 12,
        "wins": 10,
        "losses": 2,
        "win_rate": 0.833,
        "avg_pnl_pct": 1.24,
        "total_pnl": 847.50
      },
      {
        "regime": "WHALE_ACCUMULATION",
        "trades": 4,
        "wins": 3,
        "losses": 1,
        "win_rate": 0.75,
        "avg_pnl_pct": 0.92,
        "total_pnl": 312.10
      },
      {
        "regime": "SAFE_HAVEN_DEMAND",
        "trades": 2,
        "wins": 2,
        "losses": 0,
        "win_rate": 1.0,
        "avg_pnl_pct": 1.85,
        "total_pnl": 124.40
      }
    ],
    "total_trades": 18,
    "assets_included": ["BTC", "ETH", "SOL", "ADA", "TAO", "GOLD", "EURUSD"],
    "since": "2026-04-12",
    "generated_at": "2026-05-13T10:00:00Z",
    "cached": false,
    "cache_ttl_seconds": 300
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/ghost/regime-performance
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/ghost/regime-performance:
    get:
      tags:
        - Ghost Trader
      summary: Multi-asset Performance by Regime
      description: >-
        Returns Ghost Trader performance aggregated by market regime across
        **all 7

        councils** (BTC, ETH, SOL, ADA, TAO, Gold, EUR/USD).


        Each closed validated trade carries the regime label persisted at entry.
        The

        endpoint UNIONs every per-asset table and groups by regime so the
        aioka.io

        "Performance by Regime" widget can paint a single chart spanning the
        whole

        system.


        **Tier:** Free (public, no API key required) ✅

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

        **Rate limit:** 60 calls / IP / minute (SEC-5)


        ### Response fields

        | Field | Type | Description |

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

        | `regimes` | array | Per-regime rows, sorted by trades DESC then
        win_rate DESC |

        | `total_trades` | int | Sum of trades across all regimes (excludes NULL
        regime) |

        | `assets_included` | array | Asset tables that contributed (always the
        7 councils) |

        | `since` | string | Clean-slate cutoff date (ISO 8601, 2026-04-12) |

        | `generated_at` | string | UTC ISO timestamp |

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

        | `cache_ttl_seconds` | int | Cache TTL |


        ### Per-regime row

        | Field | Type | Description |

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

        | `regime` | string | Regime label (e.g. `BULL_TRENDING`,
        `SAFE_HAVEN_DEMAND`) |

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

        | `wins` | int | Trades with pnl > 0 |

        | `losses` | int | Trades with pnl <= 0 |

        | `win_rate` | float | Fraction 0.0-1.0 (0.833 = 83.3%) |

        | `avg_pnl_pct` | float | Mean PnL per trade as percentage points |

        | `total_pnl` | float | Cumulative USD PnL within this regime |
      operationId: get_ghost_regime_performance_v1_ghost_regime_performance_get
      responses:
        '200':
          description: Multi-asset regime performance aggregation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GhostRegimePerformanceResponse'
        '429':
          description: Rate limit exceeded
      security: []
components:
  schemas:
    GhostRegimePerformanceResponse:
      properties:
        regimes:
          items:
            $ref: '#/components/schemas/GhostRegimePerformanceItem'
          type: array
          title: Regimes
        total_trades:
          type: integer
          title: Total Trades
        assets_included:
          items:
            type: string
          type: array
          title: Assets Included
        since:
          type: string
          title: Since
        generated_at:
          type: string
          format: date-time
          title: Generated At
        cached:
          type: boolean
          title: Cached
        cache_ttl_seconds:
          type: integer
          title: Cache Ttl Seconds
      type: object
      required:
        - regimes
        - total_trades
        - assets_included
        - since
        - generated_at
        - cached
        - cache_ttl_seconds
      title: GhostRegimePerformanceResponse
      example:
        assets_included:
          - BTC
          - ETH
          - SOL
          - TAO
          - ADA
          - GOLD
          - EURUSD
        cache_ttl_seconds: 300
        cached: false
        generated_at: '2026-05-13T10:00:00Z'
        regimes:
          - avg_pnl_pct: 1.24
            losses: 2
            regime: BULL_TRENDING
            total_pnl: 847.5
            trades: 12
            win_rate: 0.833
            wins: 10
          - avg_pnl_pct: 0.92
            losses: 1
            regime: WHALE_ACCUMULATION
            total_pnl: 312.1
            trades: 4
            win_rate: 0.75
            wins: 3
        since: '2026-04-12'
        total_trades: 16
    GhostRegimePerformanceItem:
      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
        total_pnl:
          type: number
          title: Total Pnl
      type: object
      required:
        - regime
        - trades
        - wins
        - losses
        - win_rate
        - avg_pnl_pct
        - total_pnl
      title: GhostRegimePerformanceItem
      description: Per-regime aggregated performance row.

````