openapi: 3.1.0
info:
  title: Breeze Admin Yield Sources API
  description: A comprehensive API for managing yield farming operations, funds, and user authentication
  contact:
    name: Breeze Team
    email: support@breeze.com
  license:
    name: Proprietary
    url: https://breeze.com/license
  version: 1.0.0
servers:
- url: http://localhost:8080
  description: Local development server
- url: https://api.breeze.com
  description: Production server
tags:
- name: Yield Sources
  description: Yield source information and statistics
paths:
  /assets/apy:
    post:
      tags:
      - Yield Sources
      summary: Get maximum APY for a list of asset mints
      operationId: get_assets_apy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetsApyRequest'
        required: true
      responses:
        '200':
          description: Maximum APY for the given mints
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetsApyResponse'
        '400':
          description: Invalid request - mints array is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /yield-source/{yield_source_id}:
    get:
      tags:
      - Yield Sources
      summary: Get a specific yield source by its ID with basic stats
      operationId: get_yield_source
      parameters:
      - name: yield_source_id
        in: path
        description: Yield source identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Yield source retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YieldSourceResponse'
        '404':
          description: Yield source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
  /yield-sources:
    get:
      tags:
      - Yield Sources
      summary: Get yield sources with optional base asset filter and pagination
      operationId: get_yield_sources
      parameters:
      - name: base_asset
        in: query
        description: Base asset identifier to filter by (e.g., USDC, SOL, ETH)
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: 'Page number for pagination (default: 1)'
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: per_page
        in: query
        description: 'Items per page (default: 20, max: 100)'
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      responses:
        '200':
          description: Yield sources retrieved successfully grouped by protocol
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer_auth: []
components:
  schemas:
    ApiYieldSource:
      type: object
      required:
      - pubkey
      - source
      - yield_type
      - current_apy
      - risk
      - updated_at_timestamp
      - base_assets
      properties:
        base_assets:
          type: array
          items:
            type: string
          description: List of supported base assets
        current_apy:
          type: number
          format: double
          description: Current annual percentage yield
        pubkey:
          type: string
          description: Unique identifier for the yield source
        risk:
          type: integer
          format: int32
          description: Risk level (0-255, lower is safer)
          minimum: 0
        source:
          type: string
          description: Protocol/source name (e.g., "kamino", "marginfi", "drift")
        updated_at_timestamp:
          type: integer
          format: int64
          description: Timestamp when the data was last updated
          minimum: 0
        yield_type:
          type: string
          description: Type of yield source (e.g., "Lending", "TokenStaking", etc.)
    YieldSourceResponse:
      type: object
      required:
      - yield_source
      properties:
        yield_source:
          $ref: '#/components/schemas/ApiYieldSource'
          description: Yield source information
    PaginationMeta:
      type: object
      description: Pagination metadata
      required:
      - page
      - per_page
      - total
      - total_pages
      - has_more
      properties:
        has_more:
          type: boolean
          description: Whether there are more pages
        page:
          type: integer
          format: int32
          description: Current page number
          minimum: 0
        per_page:
          type: integer
          format: int32
          description: Number of items per page
          minimum: 0
        total:
          type: integer
          format: int64
          description: Total number of items
          minimum: 0
        total_pages:
          type: integer
          format: int32
          description: Total number of pages
          minimum: 0
    AssetsApyRequest:
      type: object
      description: Request body for assets APY endpoint
      required:
      - mints
      properties:
        mints:
          type: array
          items:
            type: string
          description: Array of asset mint addresses to get APY for
    AssetsApyResponse:
      type: object
      description: Response for assets APY endpoint
      required:
      - apy
      properties:
        apy:
          type: string
          description: Maximum APY percentage across all yield sources for the given mints (e.g., "5.25")
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message description
    PaginatedResponse:
      type: object
      description: Paginated response wrapper
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolYieldSources'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
          description: Pagination metadata
    ProtocolYieldSources:
      type: object
      required:
      - protocol
      - yield_sources
      - count
      properties:
        count:
          type: integer
          description: Number of yield sources in this protocol
          minimum: 0
        protocol:
          type: string
          description: Protocol/source name (e.g., "kamino", "marginfi", "drift")
        yield_sources:
          type: array
          items:
            $ref: '#/components/schemas/ApiYieldSource'
          description: List of yield sources for this protocol
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT