openapi: 3.1.0
info:
  title: Breeze Admin User Data 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: User Data
  description: User balance and yield data
paths:
  /user-balances/{fund_user}:
    get:
      tags:
      - User Data
      operationId: get_user_balances
      parameters:
      - name: fund_user
        in: path
        description: Fund user identifier
        required: true
        schema:
          type: string
      - name: asset
        in: query
        description: Filter by specific asset
        required: false
        schema:
          type: string
      - name: sort_by
        in: query
        description: Sort by balance
        required: false
        schema:
          type: string
      - name: sort_order
        in: query
        description: 'Sort order: ''asc'' or ''desc'''
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: limit
        in: query
        description: Items per page
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      responses:
        '200':
          description: User balances retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
  /user-yield/{fund_user}:
    get:
      tags:
      - User Data
      operationId: get_user_yield
      parameters:
      - name: fund_user
        in: path
        description: Fund user identifier
        required: true
        schema:
          type: string
      - name: fund_id
        in: query
        description: Filter by specific fund
        required: false
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: limit
        in: query
        description: Items per page
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      responses:
        '200':
          description: User yield data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - api_key: []
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.)
    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
    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