openapi: 3.0.3
info:
  title: Trading Platform API
  description: |
    Complete API documentation for the Trading Platform backend.
    Provides endpoints for authentication, trading, education, investment management, and more.
  version: 1.0.0
  contact:
    name: Trading Platform Team
    email: support@tradingplatform.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3080/api/v1
    description: Local development server
  - url: https://api.tradingplatform.com/api/v1
    description: Production server

tags:
  - name: auth
    description: Authentication and authorization operations
  - name: trading
    description: Trading operations, bots, signals, and positions
  - name: investment
    description: Investment account management
  - name: education
    description: Educational courses and learning materials
  - name: portfolio
    description: Portfolio management and allocations
  - name: payments
    description: Payment processing and subscriptions
  - name: ml
    description: Machine learning predictions and signals

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login endpoint

  schemas:
    # Common schemas
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
            - message
            - code
          properties:
            message:
              type: string
              example: "Resource not found"
            code:
              type: string
              example: "NOT_FOUND"
            field:
              type: string
              example: "userId"

    Success:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
        message:
          type: string

    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 100
        totalPages:
          type: integer
          example: 5

    # Auth schemas
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        role:
          type: string
          enum: [user, trader, analyst, admin, super_admin]
        emailVerified:
          type: boolean
        twoFactorEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time

    UserSession:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        ipAddress:
          type: string
        userAgent:
          type: string
        lastActivityAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        isCurrent:
          type: boolean

    # Trading schemas
    TradingBot:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        strategyType:
          type: string
        riskLevel:
          type: string
          enum: [low, medium, high]
        status:
          type: string
          enum: [active, paused, stopped, error]
        performance:
          type: object
          properties:
            totalReturn:
              type: number
            winRate:
              type: number
            sharpeRatio:
              type: number

    Signal:
      type: object
      properties:
        id:
          type: string
          format: uuid
        symbol:
          type: string
        signalType:
          type: string
          enum: [entry_long, entry_short, exit_long, exit_short, hold]
        confidence:
          type: string
          enum: [low, medium, high, very_high]
        price:
          type: number
        targetPrice:
          type: number
        stopLoss:
          type: number
        createdAt:
          type: string
          format: date-time

    Position:
      type: object
      properties:
        id:
          type: string
          format: uuid
        symbol:
          type: string
        side:
          type: string
          enum: [buy, sell]
        quantity:
          type: number
        entryPrice:
          type: number
        currentPrice:
          type: number
        unrealizedPnl:
          type: number
        status:
          type: string
          enum: [open, closed, liquidated]

    # Investment schemas
    InvestmentAccount:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        tradingAgent:
          type: string
          enum: [atlas, orion, nova]
        initialCapital:
          type: number
        currentBalance:
          type: number
        accumulatedProfit:
          type: number
        riskProfile:
          type: string
          enum: [conservative, moderate, aggressive]
        status:
          type: string
          enum: [pending_kyc, active, suspended, closed]

    # Education schemas
    Course:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        slug:
          type: string
        shortDescription:
          type: string
        thumbnailUrl:
          type: string
        difficultyLevel:
          type: string
          enum: [beginner, intermediate, advanced, expert]
        durationMinutes:
          type: integer
        status:
          type: string
          enum: [draft, published, archived]
        isFree:
          type: boolean
        priceUsd:
          type: number

    Enrollment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        courseId:
          type: string
          format: uuid
        status:
          type: string
          enum: [active, completed, expired, cancelled]
        progressPercentage:
          type: number
        enrolledAt:
          type: string
          format: date-time

    # Portfolio schemas
    Portfolio:
      type: object
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        name:
          type: string
        riskProfile:
          type: string
          enum: [conservative, moderate, aggressive]
        totalValue:
          type: number
        unrealizedPnl:
          type: number
        isPrimary:
          type: boolean

    PortfolioAllocation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        portfolioId:
          type: string
          format: uuid
        asset:
          type: string
        targetPercent:
          type: number
        currentPercent:
          type: number
        quantity:
          type: number
        value:
          type: number

paths:
  # AUTH ENDPOINTS
  /auth/sessions:
    get:
      tags:
        - auth
      summary: List user sessions
      description: Get all active sessions for the current user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of user sessions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/UserSession'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/sessions/{sessionId}:
    delete:
      tags:
        - auth
      summary: Revoke session
      description: Revoke a specific session by ID
      security:
        - bearerAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Session revoked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/2fa/backup-codes:
    get:
      tags:
        - auth
      summary: Get 2FA backup codes
      description: Retrieve backup codes for two-factor authentication
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Backup codes retrieved
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          codes:
                            type: array
                            items:
                              type: string

  /auth/phone/send:
    post:
      tags:
        - auth
      summary: Send phone verification code
      description: Send a verification code to user's phone number
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phoneNumber
              properties:
                phoneNumber:
                  type: string
                  example: "+1234567890"
      responses:
        '200':
          description: Code sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /auth/phone/verify:
    post:
      tags:
        - auth
      summary: Verify phone number
      description: Verify phone number with the code sent
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - code
              properties:
                code:
                  type: string
                  example: "123456"
      responses:
        '200':
          description: Phone verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  # TRADING ENDPOINTS
  /trading/bots:
    get:
      tags:
        - trading
      summary: List trading bots
      description: Get a list of all available trading bots
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [active, paused, stopped, error]
      responses:
        '200':
          description: List of trading bots
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/TradingBot'
                      meta:
                        $ref: '#/components/schemas/PaginationMeta'

  /trading/bots/{botId}:
    get:
      tags:
        - trading
      summary: Get bot details
      description: Get detailed information about a specific trading bot
      security:
        - bearerAuth: []
      parameters:
        - name: botId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Bot details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/TradingBot'

  /trading/bots/{botId}/subscribe:
    post:
      tags:
        - trading
      summary: Subscribe to bot
      description: Subscribe to a trading bot's signals
      security:
        - bearerAuth: []
      parameters:
        - name: botId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '201':
          description: Successfully subscribed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /trading/signals:
    get:
      tags:
        - trading
      summary: List trading signals
      description: Get recent trading signals
      security:
        - bearerAuth: []
      parameters:
        - name: symbol
          in: query
          schema:
            type: string
        - name: signalType
          in: query
          schema:
            type: string
            enum: [entry_long, entry_short, exit_long, exit_short, hold]
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of signals
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Signal'

  /trading/signals/{signalId}:
    get:
      tags:
        - trading
      summary: Get signal details
      description: Get detailed information about a specific signal
      security:
        - bearerAuth: []
      parameters:
        - name: signalId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Signal details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Signal'

  /trading/signals/{signalId}/execute:
    post:
      tags:
        - trading
      summary: Execute signal
      description: Execute a trading signal
      security:
        - bearerAuth: []
      parameters:
        - name: signalId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quantity:
                  type: number
                accountId:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Signal executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /trading/positions:
    get:
      tags:
        - trading
      summary: List positions
      description: Get all open positions
      security:
        - bearerAuth: []
      parameters:
        - name: symbol
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [open, closed, liquidated]
      responses:
        '200':
          description: List of positions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Position'

  /trading/positions/{positionId}:
    get:
      tags:
        - trading
      summary: Get position details
      description: Get detailed information about a specific position
      security:
        - bearerAuth: []
      parameters:
        - name: positionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Position details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Position'

  /trading/positions/{positionId}/close:
    post:
      tags:
        - trading
      summary: Close position
      description: Close an open position
      security:
        - bearerAuth: []
      parameters:
        - name: positionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Position closed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /trading/history:
    get:
      tags:
        - trading
      summary: Get trading history
      description: Get historical trading data
      security:
        - bearerAuth: []
      parameters:
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Trading history
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                      meta:
                        $ref: '#/components/schemas/PaginationMeta'

  /trading/my-subscriptions:
    get:
      tags:
        - trading
      summary: List bot subscriptions
      description: Get user's bot subscriptions
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object

  /trading/portfolio:
    get:
      tags:
        - trading
      summary: Get trading portfolio
      description: Get user's trading portfolio summary
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Portfolio summary
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          totalValue:
                            type: number
                          totalPnl:
                            type: number
                          positions:
                            type: integer

  # INVESTMENT ENDPOINTS
  /investment/accounts:
    get:
      tags:
        - investment
      summary: List investment accounts
      description: Get all investment accounts for the user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of accounts
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/InvestmentAccount'

    post:
      tags:
        - investment
      summary: Create investment account
      description: Create a new investment account
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tradingAgent
                - initialCapital
                - riskProfile
              properties:
                tradingAgent:
                  type: string
                  enum: [atlas, orion, nova]
                initialCapital:
                  type: number
                  minimum: 100
                riskProfile:
                  type: string
                  enum: [conservative, moderate, aggressive]
      responses:
        '201':
          description: Account created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/InvestmentAccount'

  /investment/accounts/{accountId}:
    get:
      tags:
        - investment
      summary: Get account details
      description: Get detailed information about an investment account
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/InvestmentAccount'

    put:
      tags:
        - investment
      summary: Update investment account
      description: Update account settings
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                riskProfile:
                  type: string
                  enum: [conservative, moderate, aggressive]
      responses:
        '200':
          description: Account updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /investment/accounts/connect:
    post:
      tags:
        - investment
      summary: Connect trading account
      description: Connect external trading account (Binance, MT4, etc.)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - provider
                - credentials
              properties:
                provider:
                  type: string
                  enum: [binance, mt4, mt5]
                credentials:
                  type: object
      responses:
        '201':
          description: Account connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /investment/performance:
    get:
      tags:
        - investment
      summary: Get performance metrics
      description: Get performance metrics for all accounts
      security:
        - bearerAuth: []
      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [week, month, quarter, year, all]
            default: month
      responses:
        '200':
          description: Performance metrics
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          totalReturn:
                            type: number
                          winRate:
                            type: number
                          sharpeRatio:
                            type: number

  /investment/analytics:
    get:
      tags:
        - investment
      summary: Get analytics data
      description: Get detailed analytics and insights
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Analytics data
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: object

  # EDUCATION ENDPOINTS
  /education/courses/featured:
    get:
      tags:
        - education
      summary: Get featured courses
      description: Get list of featured courses
      responses:
        '200':
          description: Featured courses
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Course'

  /education/courses/search:
    get:
      tags:
        - education
      summary: Search courses
      description: Search for courses by title or description
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: level
          in: query
          schema:
            type: string
            enum: [beginner, intermediate, advanced, expert]
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Course'

  /education/courses/{courseId}/enroll:
    post:
      tags:
        - education
      summary: Enroll in course
      description: Enroll the current user in a course
      security:
        - bearerAuth: []
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '201':
          description: Successfully enrolled
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Enrollment'

  /education/courses/{courseId}/progress:
    get:
      tags:
        - education
      summary: Get course progress
      description: Get user's progress in a specific course
      security:
        - bearerAuth: []
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Course progress
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          progressPercentage:
                            type: number
                          completedLessons:
                            type: integer
                          totalLessons:
                            type: integer

  /education/lessons/{lessonId}/complete:
    post:
      tags:
        - education
      summary: Mark lesson complete
      description: Mark a lesson as completed
      security:
        - bearerAuth: []
      parameters:
        - name: lessonId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Lesson marked complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /education/my-courses:
    get:
      tags:
        - education
      summary: List enrolled courses
      description: Get all courses user is enrolled in
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of enrolled courses
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/Course'
                            - type: object
                              properties:
                                enrollment:
                                  $ref: '#/components/schemas/Enrollment'

  # PORTFOLIO ENDPOINTS
  /portfolio/{portfolioId}/allocations:
    get:
      tags:
        - portfolio
      summary: Get portfolio allocations
      description: Get all allocations for a portfolio
      security:
        - bearerAuth: []
      parameters:
        - name: portfolioId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of allocations
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/PortfolioAllocation'

  /portfolio/{portfolioId}/performance:
    get:
      tags:
        - portfolio
      summary: Get portfolio performance
      description: Get performance metrics for a portfolio
      security:
        - bearerAuth: []
      parameters:
        - name: portfolioId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: period
          in: query
          schema:
            type: string
            enum: [week, month, 3months, year, all]
            default: month
      responses:
        '200':
          description: Performance data
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                            value:
                              type: number
                            pnl:
                              type: number

  /portfolio/{portfolioId}/goals:
    get:
      tags:
        - portfolio
      summary: List portfolio goals
      description: Get all goals for a portfolio
      security:
        - bearerAuth: []
      parameters:
        - name: portfolioId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of goals
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object