openapi: 3.0.3
info:
  title: Kraken Trader API
  version: 1.0.0
  description: API for managing market data subscriptions and prompts

paths:
  /health:
    get:
      summary: Health check
      operationId: getHealth
      tags:
        - System
      responses:
        '200':
          description: Health check response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

  /subscriptions:
    get:
      summary: List active subscriptions with full details
      operationId: listSubscriptions
      tags:
        - Subscriptions
      responses:
        '200':
          description: List of active subscriptions with details
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubscriptionDetail'
                  count:
                    type: integer

    post:
      summary: Add a new subscription
      operationId: addSubscription
      tags:
        - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - symbol
              properties:
                symbol:
                  type: string
                  example: BTC/USD
      responses:
        '200':
          description: Subscription added
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  symbol:
                    type: string
        '400':
          description: Bad request
        '409':
          description: Already subscribed

  /subscriptions/delete:
    post:
      summary: Remove a subscription
      operationId: deleteSubscription
      tags:
        - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - symbol
              properties:
                symbol:
                  type: string
                  example: 1INCH/USD
      responses:
        '200':
          description: Subscription removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  symbol:
                    type: string
        '400':
          description: Bad request
        '404':
          description: Not found

  /prompts:
    get:
      summary: List recent prompts
      operationId: listPrompts
      tags:
        - Prompts
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of prompts
          content:
            application/json:
              schema:
                type: object
                properties:
                  prompts:
                    type: array
                    items:
                      $ref: '#/components/schemas/PromptRecord'
                  count:
                    type: integer

  /loglevel:
    get:
      summary: Get current log level
      operationId: getLogLevel
      tags:
        - System
      responses:
        '200':
          description: Current log level
          content:
            application/json:
              schema:
                type: object
                properties:
                  level:
                    type: string
                    enum: [trace, debug, info, warn, error]

    post:
      summary: Set console log level
      operationId: setLogLevel
      tags:
        - System
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - level
              properties:
                level:
                  type: string
                  enum: [trace, debug, info, warn, error]
      responses:
        '200':
          description: Log level updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  level:
                    type: string
        '400':
          description: Invalid log level

  /assets:
    get:
      summary: Get tradable assets
      operationId: getAssets
      tags:
        - Market
      parameters:
        - name: enabled_only
          in: query
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: List of tradable assets
          content:
            application/json:
              schema:
                type: object
                properties:
                  assets:
                    type: array
                    items:
                      $ref: '#/components/schemas/AssetInfo'
                  count:
                    type: integer

  /pairs:
    get:
      summary: Get available trading pairs for subscriptions
      operationId: getPairs
      tags:
        - Market
      responses:
        '200':
          description: List of available trading pairs
          content:
            application/json:
              schema:
                type: object
                properties:
                  pairs:
                    type: array
                    items:
                      $ref: '#/components/schemas/TradingPair'
                  count:
                    type: integer

  /ticker/{symbol}:
    get:
      summary: Get current ticker for a symbol
      operationId: getTicker
      tags:
        - Market
      parameters:
        - name: symbol
          in: path
          required: true
          schema:
            type: string
            example: BTC/USD
      responses:
        '200':
          description: Current ticker data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickerData'

  /history/{symbol}:
     get:
       summary: Get historical OHLC data for a symbol
       operationId: getHistory
       tags:
         - Market
       parameters:
         - name: symbol
           in: path
           required: true
           schema:
             type: string
             example: BTC/USD
         - name: timeframe
           in: query
           schema:
             type: string
             enum: [1h, 4h, 1d, 1w]
             default: 1d
             description: Timeframe for OHLC aggregation
         - name: limit
           in: query
           schema:
             type: integer
             default: 100
             minimum: 1
             maximum: 1000
             description: Maximum number of data points to return
       responses:
         '200':
           description: Historical OHLC data
           content:
             application/json:
               schema:
                 type: object
                 properties:
                   symbol:
                     type: string
                   timeframe:
                     type: string
                   data:
                     type: array
                     items:
                       $ref: '#/components/schemas/OHLCData'
                   count:
                     type: integer
         '400':
           description: Invalid parameters
         '404':
           description: Symbol not found

  /dashboard:
    get:
      summary: Get consolidated dashboard overview
      operationId: getDashboard
      tags:
        - Dashboard
      responses:
        '200':
          description: Dashboard overview data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardOverview'

  /signals:
    get:
      summary: Get PRISM technical signal summaries
      operationId: getSignals
      tags:
        - Dashboard
      responses:
        '200':
          description: Signal summaries for all subscribed pairs
          content:
            application/json:
              schema:
                type: object
                properties:
                  signals:
                    type: array
                    items:
                      $ref: '#/components/schemas/SignalSummary'
                  count:
                    type: integer

  /news:
    get:
      summary: Get recent news articles
      operationId: getNews
      tags:
        - Dashboard
      responses:
        '200':
          description: Recent news articles
          content:
            application/json:
              schema:
                type: object
                properties:
                  news:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsItem'
                  count:
                    type: integer

  /trades:
    get:
      summary: Get trade execution history
      operationId: getTrades
      tags:
        - Dashboard
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 500
      responses:
        '200':
          description: Trade execution history
          content:
            application/json:
              schema:
                type: object
                properties:
                  trades:
                    type: array
                    items:
                      $ref: '#/components/schemas/TradeRecord'
                  count:
                    type: integer

components:
  schemas:
    TickerData:
      type: object
      properties:
        symbol:
          type: string
        bid:
          type: number
        ask:
          type: number
        last:
          type: number
        volume:
          type: number
        updated_at:
          type: string
          format: date-time

    OHLCData:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        open:
          type: number
        high:
          type: number
        low:
          type: number
        close:
          type: number
        volume:
          type: number

    AssetInfo:
      type: object
      properties:
        aclass:
          type: string
        altname:
          type: string
        decimals:
          type: integer
        display_decimals:
          type: integer
        status:
          type: string
        margin_rate:
          type: string
        collateral_value:
          type: number

    TradingPair:
      type: object
      properties:
        symbol:
          type: string
          description: Trading pair symbol (e.g., BTCUSD)
        altname:
          type: string
          description: Alternative name (e.g., XBT/USD)
        ws_name:
          type: string
          description: WebSocket pair name (e.g., BTC/USD)

    SubscriptionDetail:
      type: object
      properties:
        symbol:
          type: string
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        last_data:
          type: string
          format: date-time
        last_error:
          type: string

    PromptRecord:
      type: object
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: date-time
        type:
          type: string
        pair:
          type: string
        raw_prompt:
          type: string
        raw_answer:
          type: string
        answer:
          type: string
        action:
          type: string
        size_pct:
          type: number
        confidence:
          type: number
        success:
          type: boolean

    DashboardOverview:
      type: object
      properties:
        portfolio:
          $ref: '#/components/schemas/PortfolioSummary'
        market_snapshot:
          type: array
          items:
            $ref: '#/components/schemas/MarketSnapshot'
        subscription_health:
          $ref: '#/components/schemas/SubscriptionHealth'
        recent_decisions:
          type: array
          items:
            $ref: '#/components/schemas/PromptRecord'
        recent_alerts:
          type: array
          items:
            $ref: '#/components/schemas/PriceAlert'

    PortfolioSummary:
      type: object
      properties:
        total_value_usd:
          type: number
        balances:
          type: object
          additionalProperties:
            type: number
        open_positions:
          type: integer
        updated_at:
          type: string
          format: date-time

    MarketSnapshot:
      type: object
      properties:
        pair:
          type: string
        bid:
          type: number
        ask:
          type: number
        last:
          type: number
        volume_24h:
          type: number
        updated_at:
          type: string
          format: date-time
        sparkline:
          type: array
          items:
            type: number

    SubscriptionHealth:
      type: object
      properties:
        active:
          type: integer
        stale:
          type: integer
        errored:
          type: integer
        errors:
          type: object
          additionalProperties:
            type: string

    PriceAlert:
      type: object
      properties:
        pair:
          type: string
        change_pct:
          type: number
        current:
          type: number
        previous:
          type: number
        updated_at:
          type: string
          format: date-time
        direction:
          type: string

    SignalSummary:
      type: object
      properties:
        symbol:
          type: string
        momentum_signal:
          type: string
        breakout_signal:
          type: string
        volume_signal:
          type: string
        updated_at:
          type: string
          format: date-time

    NewsItem:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        summary:
          type: string
        source:
          type: string
        timestamp:
          type: string
          format: date-time

    TradeRecord:
      type: object
      properties:
        pair:
          type: string
        action:
          type: string
        order_type:
          type: string
        size:
          type: number
        price:
          type: number
        cost:
          type: number
        fee:
          type: number
        mode:
          type: string
        reasoning:
          type: string
        confidence:
          type: number
        timestamp:
          type: string
          format: date-time