openapi: 3.0.3
info:
  title: MyCryptoMonitor API
  description: |
    Public REST API for MyCryptoMonitor.

    All responses are JSON. Endpoints support pagination via `page` and `limit`
    query parameters where applicable.
  version: 1.0.0
tags:
  - name: Coins
    description: Tracked coins, prices, and AI analysis
  - name: Trending
    description: Trending coins with multi-timeframe sentiment
  - name: Influencers
    description: Ranked YouTube, Telegram, and X (Twitter) influencer data
  - name: Social
    description: Latest social posts with AI scoring
  # --- Market Data endpoints are offered as enterprise / custom APIs.
  #     See the "Contact us" prompt on the docs page. ---

paths:
  /api/influencers/youtube:
    get:
      tags: [Influencers]
      summary: List ranked YouTube influencers
      description: Ranked YouTube influencer data with AI scores, star ratings, win rates, and ROI.
      parameters:
        - $ref: '#/components/parameters/Timeframe'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/Quarter'
        - $ref: '#/components/parameters/Rating'
      responses:
        '200':
          description: Paginated list of influencers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfluencerListResponse'

  /api/influencers/telegram:
    get:
      tags: [Influencers]
      summary: List ranked Telegram channels
      parameters:
        - $ref: '#/components/parameters/Timeframe'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/Quarter'
        - $ref: '#/components/parameters/Rating'
      responses:
        '200':
          description: Paginated list of channels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfluencerListResponse'

  /api/influencers/twitter:
    get:
      tags: [Influencers]
      summary: List ranked X (Twitter) influencers
      parameters:
        - $ref: '#/components/parameters/Timeframe'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/Quarter'
        - $ref: '#/components/parameters/Rating'
      responses:
        '200':
          description: Paginated list of influencers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfluencerListResponse'

  /api/influencers/youtube/channel/{id}:
    get:
      tags: [Influencers]
      summary: Get a single YouTube influencer
      parameters:
        - $ref: '#/components/parameters/ChannelId'
      responses:
        '200':
          description: Influencer detail with full post history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Influencer'

  /api/influencers/telegram/channel/{id}:
    get:
      tags: [Influencers]
      summary: Get a single Telegram channel
      parameters:
        - $ref: '#/components/parameters/ChannelId'
      responses:
        '200':
          description: Channel detail with full post history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Influencer'

  /api/influencers/twitter/channel/{id}:
    get:
      tags: [Influencers]
      summary: Get a single X (Twitter) influencer
      parameters:
        - $ref: '#/components/parameters/ChannelId'
      responses:
        '200':
          description: Influencer detail with full post history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Influencer'

  /api/social/latest-posts:
    get:
      tags: [Social]
      summary: Latest social posts with AI scoring
      parameters:
        - in: query
          name: platform
          schema: { type: string, enum: [all, youtube, telegram, twitter] }
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Latest posts grouped by platform
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialPostsResponse'

  /api/trending/coin-centric:
    get:
      tags: [Trending]
      summary: Trending coins with multi-timeframe sentiment
      parameters:
        - in: query
          name: type
          schema: { type: string, enum: [all, meme] }
      responses:
        '200':
          description: Trending coins with live price + multi-timeframe changes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendingResponse'

  # --- Market Data endpoints (top-pairs, exchange-info, tickers, ticker/{symbol})
  #     are no longer published here. They are offered as enterprise / custom APIs;
  #     the docs page shows a "Contact us" prompt in their place. ---

components:
  parameters:
    Page:
      in: query
      name: page
      schema: { type: integer, default: 1, minimum: 1 }
    Limit:
      in: query
      name: limit
      schema: { type: integer, default: 50, minimum: 1, maximum: 1000 }
    Timeframe:
      in: query
      name: timeframe
      schema: { type: string, enum: [all, 1_hour, 24_hours, 7_days, 30_days, 60_days, 90_days, 180_days, 1_year] }
      description: Rolling window for performance metrics
    Year:
      in: query
      name: year
      schema: { type: string, enum: [all, "2022", "2023", "2024", "2025", "2026"] }
      description: Calendar year
    Quarter:
      in: query
      name: quarter
      schema: { type: string, enum: [all, Q1, Q2, Q3, Q4] }
      description: Quarter (ignored when year = all)
    Rating:
      in: query
      name: rating
      schema: { type: integer, enum: [1, 2, 3, 4, 5] }
      description: Filter by minimum star rating (1-4, e.g. rating=4 means 4 stars and above)
    ChannelId:
      in: path
      name: id
      required: true
      schema: { type: string }
      description: Channel / influencer id

  schemas:
    AiScoring:
      type: object
      description: >-
        AI-derived average post-quality scores (0–10). Each metric also has a
        matching `<metric>_percentile` (0–100) field comparing this influencer
        against all others.
      properties:
        avg_overall_score: { type: number, format: float, example: 6.76 }
        avg_credibility_score: { type: number, format: float, example: 6.54 }
        avg_clarity_of_analysis: { type: number, format: float, example: 7.2 }
        avg_recommendations: { type: number, format: float, example: 6.78 }
        avg_view_on_coins: { type: number, format: float, example: 7.15 }
        avg_risk_management: { type: number, format: float, example: 4.89 }
        avg_educational_purpose: { type: number, format: float, example: 6.93 }
        avg_actionable_insights: { type: number, format: float, example: 7.23 }
        avg_overall_score_percentile: { type: number, format: float, example: 73.98 }

    Influencer:
      type: object
      description: A ranked influencer / channel with AI scores, star ratings, win rate and ROI.
      properties:
        channel_id: { type: string, example: "UCboO9lZEbjfBHvQrAvwBUaQ" }
        rank: { type: integer, example: 1 }
        influencer_name: { type: string, example: "Crypto Archie" }
        subs: { type: integer, example: 87700, description: Subscriber / follower count }
        total_posts: { type: integer, example: 654 }
        current_rating: { type: number, format: float, example: 3.5, description: Current star rating (1–5) }
        win_percentage: { type: number, format: float, example: 31.08, description: Win rate (%) }
        prob_weighted_returns: { type: number, format: float, example: 4116.99, description: Probability-weighted ROI (%) }
        final_score: { type: number, format: float, example: 0.53 }
        percentile: { type: number, format: float, example: 99.15 }
        channel_thumbnails:
          type: object
          description: Avatar image URLs (default / medium / high), each `{ url, width, height }`.
        yearly_post_counts:
          type: object
          description: Post count per calendar year.
          additionalProperties: { type: integer }
          example: { "2024": 58, "2025": 267, "2026": 184 }
        star_rating_yearly:
          type: object
          description: >-
            Star rating nested by year → timeframe (1_hour, 24_hours, 7_days,
            30_days, 60_days, 90_days, 180_days, 1_year).
        score_yearly_timeframes:
          type: object
          description: Composite score nested by year → timeframe.
        ai_scoring_overall:
          $ref: '#/components/schemas/AiScoring'
        ai_scoring_yearly:
          type: object
          description: The same AI scoring breakdown, keyed by year.

    InfluencerListResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        results:
          type: array
          items: { $ref: '#/components/schemas/Influencer' }
        total_ranked: { type: integer, example: 117, description: Influencers matching the applied filters }
        total_available: { type: integer, example: 223, description: Total influencers tracked on this platform }
        ranking_criteria:
          type: object
          description: The timeframe / year / quarter / rating filters that were applied.
        message: { type: string }

    CoinMention:
      type: object
      description: A coin referenced in a social post, with the influencer's call on it.
      properties:
        symbol: { type: string, example: BTC }
        name: { type: string, example: bitcoin }
        mcm_source_id: { type: string, example: bitcoin }
        sentiment: { type: string, example: bullish }
        view: { type: string, example: bullish }
        action: { type: string, example: buy }
        tradingCall: { type: string }
        cryptoRecommendationType: { type: string }
        outlook: { type: string, example: long_term }
        lifeCycle: { type: string }
        entryStrategy: { type: string }
        exitStrategy: { type: string }
        longTermHoldingPeriod: { type: string }
        price: { type: number }

    SocialPost:
      type: object
      description: A single social post with AI quality scores (0–10) and coin mentions.
      properties:
        type: { type: string, enum: [youtube, telegram, twitter], description: Source platform }
        channel_name: { type: string, example: "The Moon Show" }
        channelID: { type: string }
        title: { type: string }
        videoID: { type: string, description: YouTube videos only }
        publishedAt: { type: string, format: date-time }
        date: { type: string, example: "2026-06-17" }
        time: { type: string, example: "08:38:45" }
        summary: { type: string }
        marketingContent: { type: string }
        marketingContentAvailable: { type: boolean }
        mentioned:
          type: array
          items: { $ref: '#/components/schemas/CoinMention' }
        overallScore: { type: number, example: 4 }
        credibilityScore: { type: number, example: 3 }
        clarityOfAnalysis: { type: number, example: 6 }
        recommendations: { type: number, example: 0 }
        viewOnCoins: { type: number, example: 3 }
        riskManagement: { type: number, example: 0 }
        educationalPurpose: { type: number, example: 4 }
        actionableInsights: { type: number, example: 2 }
        exitStrategyScore: { type: number, example: 0 }
        buyingPriceZone: { type: number, example: 0 }

    SocialPostsResponse:
      type: object
      description: Latest posts grouped per platform, plus a merged `combined` feed.
      properties:
        success: { type: boolean, example: true }
        metadata:
          type: object
          properties:
            lastUpdatedDate: { type: string, format: date-time }
            nextUpdateDate: { type: string, format: date-time }
            dateRange:
              type: object
              properties:
                from: { type: string, format: date-time }
                to: { type: string, format: date-time }
        youtube: { type: array, items: { $ref: '#/components/schemas/SocialPost' } }
        telegram: { type: array, items: { $ref: '#/components/schemas/SocialPost' } }
        twitter: { type: array, items: { $ref: '#/components/schemas/SocialPost' } }
        combined: { type: array, items: { $ref: '#/components/schemas/SocialPost' } }

    TrendingCoin:
      type: object
      description: A trending coin with live price, multi-timeframe price changes and whitepaper analysis.
      properties:
        symbol: { type: string, example: BTC }
        coin_name: { type: string, example: bitcoin }
        source_id: { type: string, example: bitcoin }
        mem_coin: { type: boolean, example: false }
        market_cap_rank: { type: integer, example: 1 }
        image_large: { type: string }
        image_small: { type: string }
        image_thumb: { type: string }
        binance:
          type: object
          description: >-
            Live price plus price-change and returns across timeframes — each as
            `<tf>_price`, `<tf>_price_change`, `<tf>_price_returns` for base,
            1_hour, 24_hours, 7_days, 30_days, …
          properties:
            last_available_price: { type: number, example: 65748.42 }
            last_available_timestamp: { type: string, format: date-time }
        whitepaper_analysis:
          type: object
          description: AI whitepaper review — fundamental_score plus technology / team / market_fit / tokenomics breakdowns.
          properties:
            fundamental_score: { type: number, example: 7.5 }
            core_concept: { type: string }

    TrendingResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        all_coins: { type: array, items: { $ref: '#/components/schemas/TrendingCoin' } }
        mem_coins: { type: array, items: { $ref: '#/components/schemas/TrendingCoin' } }
        notifications: { type: array, items: { type: object } }
        meta: { type: object }
        lastUpdateAt: { type: string, format: date-time }
        nextUpdateAt: { type: string, format: date-time }