---
openapi: 3.0.1
info:
  title: Marketdata API v1
  description: APIs related to AI-powered market recommendations
  version: v1
paths:
  /marketdata/api/v1/ai-recommendation/{marketId}:
    get:
      tags:
        - AiRecommendationController
      summary: Get AI recommendation for a market
      description: >
        Returns AI-generated trading recommendation for the specified market,
        including price forecasts, sentiment analysis, and market triggers.


        Requires the `TradingUi` operation and is rate limited per account.
      operationId: getAiRecommendation
      parameters:
        - name: marketId
          in: path
          required: true
          description: Market identifier (e.g., spot.btc_usdt, cfd.eth_eur)
          schema:
            type: string
          example: spot.btc_usdt
        - name: language
          in: query
          required: false
          description: Language code for localized content
          schema:
            type: string
            default: en
          example: en
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.Platform.Http.ErrorData'
        '404':
          description: Not Found - Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.Platform.Http.ErrorData'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.Platform.Http.ErrorData'
  /marketdata/api/v1/guest/ai-recommendation/{marketId}:
    get:
      tags:
        - GuestAiWidgetControllerV1
      summary: Get AI recommendation for a market (anonymous)
      description: >
        Anonymous counterpart of GET
        /marketdata/api/v1/ai-recommendation/{marketId}. No authentication and no
        required operations. Returns the same schema. An unknown market symbol
        returns 400.


        Rate limited independently of the authenticated endpoint's per-account
        limit.
      operationId: getGuestAiRecommendation
      parameters:
        - name: marketId
          in: path
          required: true
          description: Market identifier (e.g., spot.btc_usdt, cfd.eth_eur)
          schema:
            type: string
          example: spot.btc_usdt
        - name: language
          in: query
          required: false
          description: Language code for localized content
          schema:
            type: string
            default: en
          example: en
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.Platform.Http.ErrorData'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BBP.Platform.Http.ErrorData'
components:
  schemas:
    BBP.Platform.Http.ErrorData:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          $ref: '#/components/schemas/BBP.Platform.Http.ErrorData.ErrorDetails'
      additionalProperties: false
    BBP.Platform.Http.ErrorData.ErrorDetails:
      type: object
      properties:
        source:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        stackTrace:
          type: string
          nullable: true
      additionalProperties: false
    BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Response:
      type: object
      required:
        - marketId
        - baseAssetId
        - recommendationScore
        - suggestedActions
        - metrics
        - triggers
        - generatedAt
      properties:
        marketId:
          type: string
          description: Market identifier, echoed from the request
          example: spot.btc_usdt
        baseAssetId:
          type: string
          description: Base asset the recommendation applies to
          example: btc
        forecastPriceOneYear:
          type: string
          description: Forecasted price in one year (decimal as string)
          nullable: true
          example: "55000"
        recommendationScore:
          type: integer
          format: int32
          description: AI recommendation score
          minimum: 0
          maximum: 100
          example: 85
        forecastChangeRatio:
          type: string
          description: Forecasted relative price change ratio (decimal as string)
          nullable: true
          example: "-0.15"
        sentimentBullishRatio:
          type: string
          description: Bullish sentiment ratio
          nullable: true
          example: "0.72"
        suggestedActions:
          type: array
          description: List of suggested trading actions
          items:
            type: string
          example:
            - "Consider partial profit-taking"
            - "Maintain conservative position sizing"
            - "Monitor support levels around $60,000"
        metrics:
          $ref: '#/components/schemas/BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Metrics'
        triggers:
          $ref: '#/components/schemas/BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Triggers'
        generatedAt:
          type: string
          format: date-time
          description: Timestamp when the recommendation was generated (UTC)
          example: "2026-02-06T09:29:31.5578089Z"
      additionalProperties: false
    BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Metrics:
      type: object
      description: Market metrics for the asset
      properties:
        allTimeHighUsd:
          type: string
          description: All-time high price in USD (decimal as string)
          example: "126080"
        allTimeHighFromCurrentRatio:
          type: string
          description: Ratio from current price to all-time high (decimal as string)
          example: "0.92"
        allTimeLowUsd:
          type: string
          description: All-time low price in USD (decimal as string)
          example: "67.81"
        allTimeLowFromCurrentRatio:
          type: string
          description: Ratio from current price to all-time low (decimal as string)
          example: "-0.95"
        marketCapUsd:
          type: string
          description: Market capitalization in USD (decimal as string)
          example: "1306865102251"
        volume24HUsd:
          type: string
          description: 24-hour trading volume in USD (decimal as string)
          example: "163712263392"
      additionalProperties: false
    BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Triggers:
      type: object
      description: Market triggers categorized by type
      properties:
        technical:
          type: array
          description: Technical analysis triggers (RSI, Moving Averages)
          items:
            $ref: '#/components/schemas/BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Trigger'
        onChain:
          type: array
          description: On-chain triggers (active addresses, TVL)
          items:
            $ref: '#/components/schemas/BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Trigger'
        sentiment:
          type: array
          description: Sentiment triggers (social mentions)
          items:
            $ref: '#/components/schemas/BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Trigger'
      additionalProperties: false
    BBP.TradingServer.MarketDataApi.Models.v1.ApiAiRecommendation.Trigger:
      type: object
      description: Individual trigger with description and market impact
      required:
        - description
        - impact
      properties:
        description:
          type: string
          description: Description of the trigger
          example: "Market cap remains robust at $1.3 trillion"
        impact:
          type: string
          description: Market impact assessment
          enum:
            - Bullish
            - Bearish
            - Neutral
          example: Neutral
      additionalProperties: false
