openapi.yml

openapi: 3.0.3
info:
  title: ShelterFlex Backend API
  description: API for ShelterFlex backend service
  version: 0.1.0
  contact:
    name: ShelterFlex Team
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:4000
    description: Development server
  - url: https://api.shelterflex.io
    description: Production server

paths:
  /health:
    get:
      summary: Health check endpoint
      description: Returns the current health status and basic service information
      operationId: getHealth
      tags:
        - Health
      security: []
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - version
                  - uptimeSeconds
                properties:
                  status:
                    type: string
                    enum: [ok]
                    example: ok
                  version:
                    type: string
                    example: "0.1.0"
                  uptimeSeconds:
                    type: number
                    format: int64
                    example: 3600
        "429":
          $ref: "#/components/responses/TooManyRequests"
        default:
          $ref: "#/components/responses/Error"

  /api/auth/request-otp:
    post:
      summary: Request OTP for email login
      description: Sends a one-time password (OTP) to the provided email address.
      operationId: requestOtp
      tags:
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
      responses:
        "200":
          description: OTP request accepted
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    example: OTP sent to your email
        "429":
          $ref: "#/components/responses/TooManyRequests"
        default:
          $ref: "#/components/responses/Error"

  /api/auth/verify-otp:
    post:
      summary: Verify OTP and create session
      description: Verifies the OTP for the email and returns a session token (Bearer).
      operationId: verifyOtp
      tags:
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - otp
              properties:
                email:
                  type: string
                  format: email
                otp:
                  type: string
                  minLength: 6
                  maxLength: 6
      responses:
        "200":
          description: OTP verified successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - user
                properties:
                  token:
                    type: string
                    description: "Session token to be used as Authorization: Bearer <token>"
                  user:
                    $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/ValidationError"
        default:
          $ref: "#/components/responses/Error"

  /api/auth/logout:
    post:
      summary: Logout
      description: Invalidates the current session token.
      operationId: logout
      tags:
        - Auth
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Logged out successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
                    example: Logged out
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/auth/me:
    get:
      summary: Get current authenticated user
      description: Returns the current user associated with the Bearer session token.
      operationId: getMe
      tags:
        - Auth
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current user
          content:
            application/json:
              schema:
                type: object
                required:
                  - user
                properties:
                  user:
                    $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/v1/user/preferences/notifications/messages-email:
    patch:
      summary: Update message email preference
      description: Opt in or out of delayed message email notifications.
      operationId: updateMessageEmailPreference
      tags:
        - User Preferences
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - enabled
              properties:
                enabled:
                  type: boolean
      responses:
        "200":
          description: Preference updated
          content:
            application/json:
              schema:
                type: object
                required:
                  - messageEmailsEnabled
                properties:
                  messageEmailsEnabled:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/auth/wallet/challenge:
    post:
      summary: Create wallet login challenge
      description: Returns a Stellar SEP-10 style challenge XDR for the wallet to sign.
      operationId: walletChallenge
      tags:
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletChallengeRequest'
      responses:
        "200":
          description: Challenge created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletChallengeResponse'
        "400":
          $ref: "#/components/responses/ValidationError"
        default:
          $ref: "#/components/responses/Error"

  /api/auth/wallet/verify:
    post:
      summary: Verify wallet login signature
      description: Verifies a signed challenge XDR and creates a session token.
      operationId: walletVerify
      tags:
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WalletVerifyRequest'
      responses:
        "200":
          description: Wallet verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        "400":
          $ref: "#/components/responses/ValidationError"
        default:
          $ref: "#/components/responses/Error"

  /api/risk/state:
    get:
      summary: Get current user risk state
      description: Returns whether the authenticated user is frozen and any freeze reason.
      operationId: getRiskState
      tags:
        - Risk
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Risk state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskStateResponse'
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/admin/jobs/health:
    get:
      summary: Scheduled job and worker health
      description: >-
        Health of every scheduled job and background worker: what it does, when
        it last ran, how long that run took, how many records it processed, and
        whether it is overdue. A job that has stopped being scheduled reports
        state "overdue" (or "never_ran") so a missing run is detectable as an
        absence rather than only as an error. Requires the x-admin-secret header
        when MANUAL_ADMIN_SECRET is configured.
      operationId: getJobHealth
      tags:
        - Admin
      security:
        - adminSecret: []
      responses:
        "200":
          description: Job health report
          content:
            application/json:
              schema:
                type: object
                required: [capturedAt, overdueCount, failingCount, jobs]
                properties:
                  capturedAt:
                    type: string
                    format: date-time
                  overdueCount:
                    type: integer
                  failingCount:
                    type: integer
                  jobs:
                    type: array
                    items:
                      type: object
                      required: [name, module, does, expectedIntervalMs, state, overdue]
                      properties:
                        name:
                          type: string
                        module:
                          type: string
                        does:
                          type: string
                        expectedIntervalMs:
                          type: integer
                        ifItDoesNotRun:
                          type: string
                        healthy:
                          type: string
                        state:
                          type: string
                          enum: [healthy, failing, overdue, never_ran]
                        overdue:
                          type: boolean
                        secondsSinceLastRun:
                          type: integer
                          nullable: true
                        lastSuccessAt:
                          type: string
                          format: date-time
                          nullable: true
                        consecutiveFailures:
                          type: integer
                        lastRun:
                          type: object
                          nullable: true
                          properties:
                            startedAt:
                              type: string
                              format: date-time
                            finishedAt:
                              type: string
                              format: date-time
                            durationMs:
                              type: integer
                            outcome:
                              type: string
                              enum: [completed, failed, skipped_overrun]
                            recordsProcessed:
                              type: integer
                            correlationId:
                              type: string
                              nullable: true
                            error:
                              type: string
        "403":
          description: Invalid admin secret
        default:
          $ref: "#/components/responses/Error"

  /api/admin/receipts:
    get:
      summary: Query indexed receipts
      description: >-
        Query receipts indexed off-chain (no Soroban call). Note: despite the
        /admin path prefix, this endpoint only requires an authenticated
        session (authenticateToken) — the route handler does not check for an
        admin role.
      operationId: queryReceipts
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - name: dealId
          in: query
          required: false
          schema:
            type: string
        - name: txType
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: Paged receipts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedReceipts'
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/deals/{dealId}/receipts:
    get:
      summary: List receipts for a deal
      description: >-
        Returns all receipts for a deal. Note: the route has no auth
        middleware today (see PR description — code/spec mismatch finding).
      operationId: listDealReceipts
      tags:
        - Deals
      security: []
      parameters:
        - name: dealId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Receipt list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealReceiptsResponse'
        "404":
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          $ref: "#/components/responses/Error"

  /api/support/messages:
    post:
      summary: Submit a public support inquiry
      description: Accepts and stores a public contact/support message for later handling.
      operationId: createSupportMessage
      tags:
        - Support
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSupportMessageRequest"
      responses:
        "201":
          description: Message accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSupportMessageResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        default:
          $ref: "#/components/responses/Error"

  /api/whistleblower/ratings:
    post:
      summary: Submit a whistleblower rating (tenant)
      description: Authenticated tenant submits a rating (1-5) and optional review text.
      operationId: createWhistleblowerRating
      tags:
        - Whistleblower
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWhistleblowerRatingRequest"
      responses:
        "201":
          description: Rating created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateWhistleblowerRatingResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        "409":
          $ref: "#/components/responses/Error"
        default:
          $ref: "#/components/responses/Error"

  /api/whistleblower/{id}/ratings:
    get:
      summary: List whistleblower ratings
      description: Public list of ratings for profile/dashboard display.
      operationId: listWhistleblowerRatings
      tags:
        - Whistleblower
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Ratings list
          content:
            application/json:
              schema:
                type: object
                required: [success, ratings]
                properties:
                  success:
                    type: boolean
                  ratings:
                    type: array
                    items:
                      $ref: "#/components/schemas/WhistleblowerRating"
        "400":
          $ref: "#/components/responses/ValidationError"
        default:
          $ref: "#/components/responses/Error"

  /api/whistleblower/{id}/ratings/aggregate:
    get:
      summary: Get whistleblower rating aggregate
      description: Public aggregate trust metrics (count, average, breakdown).
      operationId: getWhistleblowerRatingAggregate
      tags:
        - Whistleblower
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Aggregate metrics
          content:
            application/json:
              schema:
                type: object
                required: [success, aggregate]
                properties:
                  success:
                    type: boolean
                  aggregate:
                    $ref: "#/components/schemas/WhistleblowerRatingAggregate"
        "400":
          $ref: "#/components/responses/ValidationError"
        default:
          $ref: "#/components/responses/Error"

  /api/epoch-rewards/stake:
    post:
      summary: Stake tokens in epoch rewards contract
      description: Stake tokens to participate in epoch rewards program.
      operationId: epochStake
      tags:
        - Epoch Rewards
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount:
                  type: string
                  description: Amount to stake as string (to handle large numbers)
                  example: "1000000"
      responses:
        "200":
          description: Stake submitted successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, txHash]
                properties:
                  success:
                    type: boolean
                    example: true
                  txHash:
                    type: string
                    description: Stellar transaction hash
                    example: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/epoch-rewards/unstake:
    post:
      summary: Unstake tokens from epoch rewards contract
      description: Unstake previously staked tokens from epoch rewards program.
      operationId: epochUnstake
      tags:
        - Epoch Rewards
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount:
                  type: string
                  description: Amount to unstake as string
                  example: "500000"
      responses:
        "200":
          description: Unstake submitted successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, txHash]
                properties:
                  success:
                    type: boolean
                    example: true
                  txHash:
                    type: string
                    description: Stellar transaction hash
                    example: "b4f3d2e5f6a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/epoch-rewards/claim:
    post:
      summary: Claim epoch rewards
      description: Claim available rewards from the epoch rewards contract.
      operationId: epochClaim
      tags:
        - Epoch Rewards
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Rewards claimed successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, claimedAmount]
                properties:
                  success:
                    type: boolean
                    example: true
                  claimedAmount:
                    type: string
                    description: Amount claimed as string
                    example: "1000"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/epoch-rewards/claimable:
    get:
      summary: Get claimable rewards amount
      description: Query the amount of rewards available to claim for the authenticated user.
      operationId: epochGetClaimable
      tags:
        - Epoch Rewards
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Claimable amount retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, claimable]
                properties:
                  success:
                    type: boolean
                    example: true
                  claimable:
                    type: string
                    description: Amount available to claim as string
                    example: "500"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/epoch-rewards/epoch/{epochNumber}:
    get:
      summary: Get epoch information
      description: Retrieve detailed information about a specific epoch.
      operationId: epochGetEpoch
      tags:
        - Epoch Rewards
      security:
        - bearerAuth: []
      parameters:
        - name: epochNumber
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: The epoch number to query
      responses:
        "200":
          description: Epoch information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/EpochInfo"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/Error"
        default:
          $ref: "#/components/responses/Error"

  /api/epoch-rewards/current-epoch:
    get:
      summary: Get current epoch number
      description: Retrieve the current epoch number from the epoch rewards contract.
      operationId: epochGetCurrentEpoch
      tags:
        - Epoch Rewards
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current epoch number retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, currentEpoch]
                properties:
                  success:
                    type: boolean
                    example: true
                  currentEpoch:
                    type: integer
                    description: Current epoch number
                    example: 1
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/epoch-rewards/total-staked:
    get:
      summary: Get total staked amount
      description: Retrieve the total amount of tokens staked in the epoch rewards contract.
      operationId: epochGetTotalStaked
      tags:
        - Epoch Rewards
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Total staked amount retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, totalStaked]
                properties:
                  success:
                    type: boolean
                    example: true
                  totalStaked:
                    type: string
                    description: Total staked amount as string
                    example: "1000000"
        "401":
          $ref: "#/components/responses/Unauthorized"
        default:
          $ref: "#/components/responses/Error"

  /api/property-issue-reports:
    post:
      summary: Submit a property issue report
      description: Accepts and stores an issue report from the property detail report dialog.
      operationId: createPropertyIssueReport
      tags:
        - Risk
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePropertyIssueReportRequest"
      responses:
        "201":
          description: Report accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePropertyIssueReportResponse"
        "400":
          $ref: "#/components/responses/ValidationError"
        default:
          $ref: "#/components/responses/Error"

  /soroban/config:
    get:
      summary: Get Soroban configuration
      description: Returns the current Soroban blockchain configuration
      operationId: getSorobanConfig
      tags:
        - Soroban
      security: []
      responses:
        "200":
          description: Soroban configuration retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - rpcUrl
                  - networkPassphrase
                  - contractId
                properties:
                  rpcUrl:
                    type: string
                    format: uri
                    example: "https://soroban-testnet.stellar.org"
                  networkPassphrase:
                    type: string
                    example: "Test SDF Network ; September 2015"
                  contractId:
                    type: string
                    nullable: true
                    example: null
        "429":
          $ref: "#/components/responses/TooManyRequests"
        default:
          $ref: "#/components/responses/Error"

  /api/whistleblower/{id}/earnings:
    get:
      summary: Get whistleblower earnings
      description: Returns aggregated earnings totals and detailed history of individual rewards for a whistleblower
      operationId: getWhistleblowerEarnings
      tags:
        - Whistleblower
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the whistleblower
          schema:
            type: string
            minLength: 1
          example: "wb-123e4567-e89b-12d3-a456-426614174000"
      responses:
        "200":
          description: Earnings data retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EarningsResponse"
              examples:
                mixedStatus:
                  summary: Whistleblower with mixed payout statuses
                  value:
                    totals:
                      totalNgn: 750000
                      pendingNgn: 450000
                      paidNgn: 300000
                      totalUsdc: 500
                      pendingUsdc: 300
                      paidUsdc: 200
                    history:
                      - rewardId: "rw-001"
                        listingId: "lst-456"
                        dealId: "deal-789"
                        amountNgn: 300000
                        amountUsdc: 200
                        status: "paid"
                        createdAt: "2024-01-15T10:30:00Z"
                        paidAt: "2024-01-20T14:45:00Z"
                      - rewardId: "rw-002"
                        listingId: "lst-457"
                        dealId: "deal-790"
                        amountNgn: 225000
                        amountUsdc: 150
                        status: "pending"
                        createdAt: "2024-01-10T08:15:00Z"
                      - rewardId: "rw-003"
                        listingId: "lst-458"
                        dealId: "deal-791"
                        amountNgn: 225000
                        amountUsdc: 150
                        status: "payable"
                        createdAt: "2024-01-05T16:20:00Z"
                allPending:
                  summary: Whistleblower with all pending rewards
                  value:
                    totals:
                      totalNgn: 600000
                      pendingNgn: 600000
                      paidNgn: 0
                      totalUsdc: 400
                      pendingUsdc: 400
                      paidUsdc: 0
                    history:
                      - rewardId: "rw-004"
                        listingId: "lst-459"
                        dealId: "deal-792"
                        amountNgn: 300000
                        amountUsdc: 200
                        status: "pending"
                        createdAt: "2024-02-01T12:00:00Z"
                      - rewardId: "rw-005"
                        listingId: "lst-460"
                        dealId: "deal-793"
                        amountNgn: 300000
                        amountUsdc: 200
                        status: "pending"
                        createdAt: "2024-01-28T09:30:00Z"
        "400":
          description: Invalid request - whistleblower ID format is invalid
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  code: "VALIDATION_ERROR"
                  message: "Whistleblower ID is required"
                  details:
                    field: "id"
        "404":
          description: Whistleblower not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  code: "NOT_FOUND"
                  message: "Whistleblower not found"
                  details:
                    whistleblowerId: "wb-nonexistent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error:
                  code: "INTERNAL_ERROR"
                  message: "Failed to retrieve earnings data"

  /api/whistleblower/listings:
    post:
      summary: Create a new listing
      description: |
        Create a new property listing. 
        
        Rules:
        - Address is required
        - Annual rent must be greater than 0
        - At least 3 photos are required
        - Maximum 2 listings per whistleblower per month
      operationId: createListing
      tags:
        - Whistleblower
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateListingRequest'
      responses:
        '201':
          description: Listing created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - listing
                properties:
                  success:
                    type: boolean
                    example: true
                  listing:
                    $ref: '#/components/schemas/Listing'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingPhotos:
                  summary: Missing required photos
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request data
                      details:
                        fields:
                          - field: photos
                            message: At least 3 photos are required
                invalidRent:
                  summary: Invalid annual rent
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request data
                      details:
                        fields:
                          - field: annualRentNgn
                            message: Annual rent must be greater than 0
        '429':
          description: Monthly limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CONFLICT
                  message: Monthly listing limit reached
                  details:
                    currentCount: 2
                    maxAllowed: 2
                    message: You have reached the maximum of 2 listings per month
        default:
          $ref: '#/components/responses/Error'

    get:
      summary: List listings
      description: Get a paginated list of listings with optional filters
      operationId: listListings
      tags:
        - Whistleblower
      security: []
      parameters:
        - name: status
          in: query
          description: Filter by listing status
          required: false
          schema:
            $ref: '#/components/schemas/ListingStatus'
        - name: query
          in: query
          description: Search term for address, city, area, or description
          required: false
          schema:
            type: string
            example: Lagos
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 1
        - name: pageSize
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            example: 20
      responses:
        '200':
          description: Listings retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - listings
                  - pagination
                properties:
                  success:
                    type: boolean
                    example: true
                  listings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Listing'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/wallet/ngn/withdraw/initiate:
    post:
      summary: Initiate NGN withdrawal
      description: Initiates a withdrawal request and moves funds from available to held.
      operationId: initiateNgnWithdrawal
      tags:
        - NGN Wallet
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
      responses:
        '201':
          description: Withdrawal initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/wallet/ngn/withdrawals:
    get:
      summary: List NGN withdrawals
      description: Returns the authenticated user's NGN withdrawal history.
      operationId: listNgnWithdrawals
      tags:
        - NGN Wallet
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Withdrawal list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalHistoryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/admin/withdrawals/{id}/approve:
    post:
      summary: Approve NGN withdrawal
      description: Approves a pending withdrawal and executes provider payout. Idempotent if already approved/confirmed.
      operationId: approveNgnWithdrawal
      tags:
        - Admin
      # requirePermission('payouts', 'trigger') in code — admin-tier RBAC permission,
      # not just an authenticated session. See bearerAdminAuth description.
      security:
        - bearerAdminAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Withdrawal approved/confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Caller is authenticated but lacks the payouts:trigger permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/admin/withdrawals/{id}/reject:
    post:
      summary: Reject NGN withdrawal
      description: Rejects a pending withdrawal and releases held funds back to available. Idempotent if already rejected/failed.
      operationId: rejectNgnWithdrawal
      tags:
        - Admin
      # requirePermission('payouts', 'trigger') in code — admin-tier RBAC permission,
      # not just an authenticated session. See bearerAdminAuth description.
      security:
        - bearerAdminAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reason
              properties:
                reason:
                  type: string
      responses:
        '200':
          description: Withdrawal rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Caller is authenticated but lacks the payouts:trigger permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/whistleblower/listings/{id}:
    get:
      summary: Get listing by ID
      description: Retrieve a single listing by its ID
      operationId: getListingById
      tags:
        - Whistleblower
      security: []
      parameters:
        - name: id
          in: path
          description: Listing ID
          required: true
          schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Listing retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - listing
                properties:
                  success:
                    type: boolean
                    example: true
                  listing:
                    $ref: '#/components/schemas/Listing'
        '404':
          description: Listing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Listing with ID '550e8400-e29b-41d4-a716-446655440000' not found
        default:
          $ref: '#/components/responses/Error'

  /api/wallet/ngn/topup/initiate:
    post:
      summary: Initiate NGN wallet top-up
      description: Creates a payment intent for NGN wallet top-up. Returns PSP redirect URL or bank transfer details.
      operationId: initiateNgnWalletTopup
      tags:
        - NGN Wallet
      security:
        - bearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: Optional idempotency key for safe retries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amountNgn
                - rail
              properties:
                amountNgn:
                  type: number
                  minimum: 100
                  maximum: 5000000
                rail:
                  type: string
                  enum: [paystack, flutterwave, bank_transfer, manual_admin]
      responses:
        '201':
          description: Top-up initiated
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - depositId
                  - externalRefSource
                  - externalRef
                properties:
                  success:
                    type: boolean
                    example: true
                  depositId:
                    type: string
                    format: uuid
                  externalRefSource:
                    type: string
                    example: paystack
                  externalRef:
                    type: string
                    example: pi_abc123
                  redirectUrl:
                    type: string
                    nullable: true
                  bankDetails:
                    type: object
                    nullable: true
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/payments/confirm:
    post:
      summary: Confirm a payment and write a USDC receipt on-chain
      description: |
        Confirm an off-chain (bank/card/PSP) or on-chain (Stellar) payment and record an
        idempotent USDC receipt on the Soroban ledger.

        **USDC is the canonical accounting unit.** All on-chain receipts are denominated in USDC.
        NGN amounts and FX metadata are optional and stored as off-chain metadata only.

        **Idempotency:** Submitting the same `(externalRefSource, externalRef)` pair twice will
        return the existing receipt without writing a duplicate on-chain.
      operationId: confirmPayment
      tags:
        - Payments
      # NOTE: createPaymentsRouter() applies no auth middleware to this route today (see PR
      # description — code/spec mismatch finding). security:[] reflects the current code.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmPaymentRequest'
            examples:
              tenantRepayment:
                summary: Tenant repayment via Stripe
                value:
                  dealId: "550e8400-e29b-41d4-a716-446655440000"
                  txType: tenant_repayment
                  amountUsdc: "64.52"
                  tokenAddress: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
                  externalRefSource: stripe
                  externalRef: pi_3OZxyz123456
                  amountNgn: 100000
                  fxRateNgnPerUsdc: 1550.00
                  fxProvider: exchangerate-api
              landlordPayout:
                summary: Landlord payout
                value:
                  dealId: "550e8400-e29b-41d4-a716-446655440000"
                  txType: landlord_payout
                  amountUsdc: "774.19"
                  tokenAddress: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
                  externalRefSource: stellar
                  externalRef: "a3f2c1d4e5b6..."
      responses:
        '200':
          description: Payment confirmed and USDC receipt written to chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentConfirmationResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440001"
                txId: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
                status: sent
                message: "Payment confirmed and USDC receipt written to chain"
        '202':
          description: Payment confirmed, USDC receipt queued for retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentConfirmationResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440001"
                txId: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
                status: failed
                message: "Payment confirmed, USDC receipt queued for retry"
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/deals:
    post:
      summary: Create a new deal with repayment schedule
      description: Creates a new financing deal with a deterministic repayment schedule
      operationId: createDeal
      tags:
        - Deals
      # NOTE: createDealsRouter() applies no auth middleware to any /api/deals route today
      # (see PR description — code/spec mismatch finding). security:[] reflects current code.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDealRequest'
      responses:
        '201':
          description: Deal created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/DealWithSchedule'
        '400':
          description: Validation error or listing not approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                validationError:
                  summary: Invalid request data
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request data
                listingNotApproved:
                  summary: Listing not approved
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Listing must be approved to create a deal. Current status pending_review
        '404':
          description: Listing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Listing with ID '550e8400-e29b-41d4-a716-446655440000' not found
        '409':
          description: Listing already rented or linked to another deal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listingRented:
                  summary: Listing already rented
                  value:
                    error:
                      code: LISTING_ALREADY_RENTED
                      message: Listing with ID '550e8400-e29b-41d4-a716-446655440000' is already rented
                listingLinked:
                  summary: Listing already linked to a deal
                  value:
                    error:
                      code: LISTING_ALREADY_RENTED
                      message: Listing with ID '550e8400-e29b-41d4-a716-446655440000' is already linked to deal 550e8400-e29b-41d4-a716-446655440001
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

    get:
      summary: Get deals with optional filtering
      description: Retrieves a paginated list of deals, optionally filtered by tenant, landlord, or status
      operationId: getDeals
      tags:
        - Deals
      security: []
      parameters:
        - name: tenantId
          in: query
          description: Filter by tenant ID
          schema:
            type: string
        - name: landlordId
          in: query
          description: Filter by landlord ID
          schema:
            type: string
        - name: status
          in: query
          description: Filter by deal status
          schema:
            $ref: '#/components/schemas/DealStatus'
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Deals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/PaginatedDeals'
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/deals/{dealId}:
    get:
      summary: Get a specific deal by ID with schedule
      description: Retrieves a single deal including its full repayment schedule
      operationId: getDealById
      tags:
        - Deals
      security: []
      parameters:
        - name: dealId
          in: path
          required: true
          description: ID of the deal to retrieve
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Deal retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/DealWithSchedule'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/deals/{dealId}/status:
    patch:
      summary: Update deal status
      description: Updates the status of a deal (e.g., from draft to active)
      operationId: updateDealStatus
      tags:
        - Deals
      security: []
      parameters:
        - name: dealId
          in: path
          required: true
          description: ID of the deal to update
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDealStatusRequest'
      responses:
        '200':
          description: Deal status updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/DealWithSchedule'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/deals/{dealId}/schedule/{period}:
    patch:
      summary: Update schedule item status
      description: Updates the status of a specific repayment schedule item
      operationId: updateScheduleItemStatus
      tags:
        - Deals
      security: []
      parameters:
        - name: dealId
          in: path
          required: true
          description: ID of the deal
          schema:
            type: string
            format: uuid
        - name: period
          in: path
          required: true
          description: Period number in the repayment schedule
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleItemRequest'
      responses:
        '200':
          description: Schedule item status updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/DealWithSchedule'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          description: |
            Marking this period paid would push accumulated rent-to-own equity
            over the property value (mirrors the rent_to_own contract's
            `EquityOverflow` guard — code `EQUITY_OVERFLOW`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/deals/{dealId}/progress:
    get:
      summary: Get deal payment progress from on-chain receipts
      description: |
        Computes and returns a deal's payment progress by reading `TENANT_REPAYMENT`
        receipts from the on-chain ledger (outbox store).

        Only receipts with status `sent` (confirmed on-chain) are counted.
        USDC is the canonical accounting unit.

        `equityAccumulatedUsdc`/`equityPercentageBps` reflect rent_to_own
        equity that has actually landed on-chain (only `sent`
        `RENT_TO_OWN_EQUITY_PAYMENT` outbox items are counted) — this is
        contract-confirmed state, distinct from `periodsPaid`, which is a raw
        receipt count.
      operationId: getDealProgress
      tags:
        - Deals
      security: []
      parameters:
        - name: dealId
          in: path
          required: true
          description: ID of the deal
          schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Deal progress computed from on-chain receipts
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/DealProgressResponse'
              example:
                success: true
                data:
                  totalPaidUsdc: "129.040000"
                  periodsPaid: 2
                  remainingPeriods: 10
                  nextDueDate: "2024-04-15T00:00:00.000Z"
                  lastPaymentTxId: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
                  lastPaymentExternalRefSource: stripe
                  lastPaymentExternalRef: pi_3OZxyz123456
                  equityAccumulatedUsdc: "80.650000"
                  equityCapUsdc: "600.000000"
                  equityPercentageBps: 1344
                  equityPaymentsConfirmed: 2
        '404':
          description: Deal not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Deal with ID '550e8400-e29b-41d4-a716-446655440000' not found
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/tenant/payments/disputes:
    post:
      summary: File a payment dispute
      description: |
        Files a payment dispute against a deal. Asynchronously (via the
        outbox/worker pattern — never synchronously in this request) enqueues
        an on-chain `challenge_rent_release` call against deal_escrow for the
        given `dealId`, halting any pending rent release within its challenge
        window. If deal_escrow has no pending release for this deal (or the
        challenge window already closed), the on-chain call is rejected and
        the dispute is marked `rejected` with that reason — it is never left
        silently "pending" with no on-chain effect.
      operationId: createPaymentDispute
      tags:
        - Disputes
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentDisputeCreateRequest'
      responses:
        '201':
          description: Dispute filed
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required:
                      - dispute
                    properties:
                      dispute:
                        $ref: '#/components/schemas/PaymentDispute'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'
    get:
      summary: List the authenticated tenant's own disputes
      description: Returns every dispute filed by the authenticated caller, most recent first.
      operationId: listMyPaymentDisputes
      tags:
        - Disputes
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The caller's disputes
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    required:
                      - disputes
                    properties:
                      disputes:
                        type: array
                        items:
                          $ref: '#/components/schemas/PaymentDispute'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/admin/disputes:
    get:
      summary: List payment disputes (admin)
      description: Returns a paginated, filterable list of payment disputes for admin review.
      operationId: listPaymentDisputesAdmin
      tags:
        - Disputes
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/PaymentDisputeStatus'
        - name: userId
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: Paginated dispute list
          content:
            application/json:
              schema:
                type: object
                required:
                  - disputes
                  - total
                  - page
                  - pageSize
                  - totalPages
                properties:
                  disputes:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentDispute'
                  total:
                    type: integer
                  page:
                    type: integer
                  pageSize:
                    type: integer
                  totalPages:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Caller lacks the disputes:view permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/admin/disputes/{disputeId}/resolve:
    post:
      summary: Resolve a payment dispute (admin)
      description: |
        Resolves or rejects a payment dispute and, asynchronously via the
        outbox/worker pattern, enqueues a matching on-chain
        `resolve_rent_dispute` call against deal_escrow (skipped if the
        dispute has no associated dealId).

        Status → SettlementOutcome mapping:
        - `resolved` (the tenant's dispute is upheld) → `RefundToDepositor`
          (the pending rent release is refunded to the tenant, not released
          to the landlord).
        - `rejected` (the dispute is denied) → `ReleaseToRecipient` (the
          originally requested release proceeds to its recipient, e.g. the
          landlord).
      operationId: resolvePaymentDisputeAdmin
      tags:
        - Disputes
      security:
        - bearerAuth: []
      parameters:
        - name: disputeId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum: [resolved, rejected]
                resolution:
                  type: string
      responses:
        '200':
          description: Dispute resolved
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                properties:
                  success:
                    type: boolean
                    example: true
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Caller lacks the disputes:resolve permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'

  /api/admin/rewards/{rewardId}/mark-paid:
    post:
      summary: Mark reward as paid
      description: |
        Mark a whistleblower reward as paid and record receipt on-chain.
        
        Rules:
        - Reward must be in 'payable' status
        - Creates on-chain receipt with WHISTLEBLOWER_REWARD type
        - Idempotent by external reference (duplicate refs return same txId)
        - Receipt contains dealId and listingId
      operationId: markRewardPaid
      tags:
        - Admin
      # NOTE: this handler calls neither requireAdminSecret nor authenticateToken — it is
      # unauthenticated in code today despite being an admin payout action (see PR
      # description — code/spec mismatch finding). security:[] reflects current code.
      security: []
      parameters:
        - name: rewardId
          in: path
          description: Reward ID
          required: true
          schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkRewardPaidRequest'
      responses:
        '200':
          description: Reward marked as paid and receipt written to chain
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - reward
                  - receipt
                  - message
                properties:
                  success:
                    type: boolean
                    example: true
                  reward:
                    type: object
                    required:
                      - rewardId
                      - status
                    properties:
                      rewardId:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum: [paid]
                      paidAt:
                        type: string
                        format: date-time
                      paymentTxId:
                        type: string
                        description: Transaction ID on blockchain
                  receipt:
                    type: object
                    required:
                      - outboxId
                      - txId
                      - status
                    properties:
                      outboxId:
                        type: string
                        format: uuid
                      txId:
                        type: string
                        description: 32-byte transaction ID as hex
                      status:
                        type: string
                        enum: [pending, sent, failed]
                  message:
                    type: string
                    example: Reward marked as paid and receipt written to chain
        '202':
          description: Reward marked as paid, receipt queued for retry
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - reward
                  - receipt
                  - message
                properties:
                  success:
                    type: boolean
                    example: true
                  reward:
                    type: object
                  receipt:
                    type: object
                  message:
                    type: string
                    example: Reward marked as paid, receipt queued for retry
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Reward not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Reward with ID '550e8400-e29b-41d4-a716-446655440000' not found
        '409':
          description: Reward not in payable status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CONFLICT
                  message: Reward cannot be marked as paid. Current status pending
                  details:
                    currentStatus: pending
                    requiredStatus: payable
        default:
          $ref: '#/components/responses/Error'

  /api/admin/whistleblower/listings:
    get:
      summary: List whistleblower listings (admin)
      description: |
        Returns a paginated list of whistleblower listings for admin review.
        Defaults to `status=pending_review` when no status filter is provided.
      operationId: adminListWhistleblowerListings
      tags:
        - Admin
      # NOTE: this handler calls neither requireAdminSecret nor authenticateToken — it is
      # unauthenticated in code today (see PR description — code/spec mismatch finding).
      # security:[] reflects current code.
      security: []
      parameters:
        - name: status
          in: query
          description: Filter by listing status (defaults to pending_review)
          required: false
          schema:
            type: string
            enum: [pending_review, approved, rejected, rented]
            default: pending_review
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Paginated list of listings
          content:
            application/json:
              schema:
                type: object
                required:
                  - listings
                  - pagination
                properties:
                  listings:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminListing'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/ValidationError'
        default:
          $ref: '#/components/responses/Error'

  /api/admin/whistleblower/listings/{id}/approve:
    post:
      summary: Approve a whistleblower listing
      description: |
        Transitions a listing from `pending_review` to `approved`.
        Any other current status results in a 409 conflict.
      operationId: approveWhistleblowerListing
      tags:
        - Admin
      # NOTE: this handler calls neither requireAdminSecret nor authenticateToken — it is
      # unauthenticated in code today (see PR description — code/spec mismatch finding).
      # security:[] reflects current code.
      security: []
      parameters:
        - name: id
          in: path
          description: Listing ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reviewedBy
              properties:
                reviewedBy:
                  type: string
                  minLength: 1
                  description: ID of the admin performing the review
                  example: admin-001
      responses:
        '200':
          description: Listing approved
          content:
            application/json:
              schema:
                type: object
                required:
                  - listing
                properties:
                  listing:
                    $ref: '#/components/schemas/ModerationResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          description: Listing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: "Listing with ID 'abc-123' not found"
        '409':
          description: Invalid state transition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CONFLICT
                  message: "Listing cannot be approved. Current status: approved"
                  details:
                    currentStatus: approved
                    allowedFrom: pending_review
        default:
          $ref: '#/components/responses/Error'

  /api/admin/whistleblower/listings/{id}/reject:
    post:
      summary: Reject a whistleblower listing
      description: |
        Transitions a listing from `pending_review` to `rejected`.
        A `reason` explaining the rejection is required.
        Any other current status results in a 409 conflict.
      operationId: rejectWhistleblowerListing
      tags:
        - Admin
      # NOTE: this handler calls neither requireAdminSecret nor authenticateToken — it is
      # unauthenticated in code today (see PR description — code/spec mismatch finding).
      # security:[] reflects current code.
      security: []
      parameters:
        - name: id
          in: path
          description: Listing ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reviewedBy
                - reason
              properties:
                reviewedBy:
                  type: string
                  minLength: 1
                  description: ID of the admin performing the review
                  example: admin-001
                reason:
                  type: string
                  minLength: 1
                  description: Reason for rejection shown to the whistleblower
                  example: Photos do not match the listed address
      responses:
        '200':
          description: Listing rejected
          content:
            application/json:
              schema:
                type: object
                required:
                  - listing
                properties:
                  listing:
                    allOf:
                      - $ref: '#/components/schemas/ModerationResult'
                      - type: object
                        properties:
                          rejectionReason:
                            type: string
                            example: Photos do not match the listed address
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          description: Listing not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: "Listing with ID 'abc-123' not found"
        '409':
          description: Invalid state transition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: CONFLICT
                  message: "Listing cannot be rejected. Current status: rejected"
                  details:
                    currentStatus: rejected
                    allowedFrom: pending_review
        default:
          $ref: '#/components/responses/Error'

  /api/admin/fraud/slashing/submit-evidence:
    post:
      summary: Submit evidence to slashing module
      description: Queues a submit_evidence operation to the slashing module contract via the outbox pattern.
      operationId: submitSlashingEvidence
      tags:
        - Admin
      security:
        - adminSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - submitter
                - commitment
                - actor
                - offence
              properties:
                submitter:
                  type: string
                  description: Stellar address of the evidence submitter
                  example: "GABC..."
                commitment:
                  type: string
                  description: Commitment hash (hex string)
                  example: "0x123abc..."
                actor:
                  type: string
                  description: Stellar address of the actor being accused
                  example: "GXYZ..."
                offence:
                  type: string
                  description: Type of offence
                  example: "double_signing"
      responses:
        '201':
          description: Evidence submission queued
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - outboxId
                properties:
                  success:
                    type: boolean
                    example: true
                  outboxId:
                    type: string
                    description: Outbox item ID for tracking
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Invalid admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Invalid admin secret
        default:
          $ref: '#/components/responses/Error'

  /api/admin/fraud/slashing/reveal-evidence:
    post:
      summary: Reveal evidence in slashing module
      description: Queues a reveal_evidence operation to the slashing module contract via the outbox pattern.
      operationId: revealSlashingEvidence
      tags:
        - Admin
      security:
        - adminSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - submitter
                - slashId
                - evidence
                - salt
              properties:
                submitter:
                  type: string
                  description: Stellar address of the evidence submitter
                  example: "GABC..."
                slashId:
                  type: integer
                  description: Slash ID from the original submission
                  example: 1
                evidence:
                  type: string
                  description: Evidence data (hex string)
                  example: "0x456def..."
                salt:
                  type: string
                  description: Salt used for commitment (hex string)
                  example: "0x789ghi..."
      responses:
        '201':
          description: Evidence reveal queued
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - outboxId
                properties:
                  success:
                    type: boolean
                    example: true
                  outboxId:
                    type: string
                    description: Outbox item ID for tracking
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Invalid admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Invalid admin secret
        default:
          $ref: '#/components/responses/Error'

  /api/admin/fraud/slashing/propose-slash:
    post:
      summary: Propose a slash in slashing module
      description: Queues a propose_slash operation to the slashing module contract via the outbox pattern.
      operationId: proposeSlash
      tags:
        - Admin
      security:
        - adminSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - submitter
                - actor
                - penaltyBps
              properties:
                submitter:
                  type: string
                  description: Stellar address of the submitter
                  example: "GABC..."
                actor:
                  type: string
                  description: Stellar address of the actor to be slashed
                  example: "GXYZ..."
                penaltyBps:
                  type: integer
                  description: Penalty in basis points (0-10000, where 10000 = 100%)
                  minimum: 0
                  maximum: 10000
                  example: 5000
      responses:
        '201':
          description: Slash proposal queued
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - outboxId
                properties:
                  success:
                    type: boolean
                    example: true
                  outboxId:
                    type: string
                    description: Outbox item ID for tracking
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Invalid admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Invalid admin secret
        default:
          $ref: '#/components/responses/Error'

  /api/admin/fraud/slashing/finalize-slash:
    post:
      summary: Finalize a slash in slashing module
      description: Queues a finalize_slash operation to the slashing module contract via the outbox pattern.
      operationId: finalizeSlash
      tags:
        - Admin
      security:
        - adminSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - caller
                - slashId
              properties:
                caller:
                  type: string
                  description: Stellar address of the caller
                  example: "GABC..."
                slashId:
                  type: integer
                  description: Slash ID to finalize
                  example: 1
      responses:
        '201':
          description: Slash finalization queued
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - outboxId
                properties:
                  success:
                    type: boolean
                    example: true
                  outboxId:
                    type: string
                    description: Outbox item ID for tracking
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Invalid admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Invalid admin secret
        default:
          $ref: '#/components/responses/Error'

  /api/admin/fraud/slashing/cancel-slash:
    post:
      summary: Cancel a slash in slashing module
      description: Queues a cancel_slash operation to the slashing module contract via the outbox pattern.
      operationId: cancelSlash
      tags:
        - Admin
      security:
        - adminSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - admin
                - slashId
              properties:
                admin:
                  type: string
                  description: Stellar address of the admin
                  example: "GABC..."
                slashId:
                  type: integer
                  description: Slash ID to cancel
                  example: 1
      responses:
        '201':
          description: Slash cancellation queued
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - outboxId
                properties:
                  success:
                    type: boolean
                    example: true
                  outboxId:
                    type: string
                    description: Outbox item ID for tracking
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Invalid admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Invalid admin secret
        default:
          $ref: '#/components/responses/Error'

  /api/admin/fraud/bond/deposit:
    post:
      summary: Deposit bond to bond collateral contract
      description: Queues a deposit_bond operation to the bond collateral contract via the outbox pattern.
      operationId: depositBond
      tags:
        - Admin
      security:
        - adminSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - inspector
                - amount
              properties:
                inspector:
                  type: string
                  description: Stellar address of the inspector
                  example: "GABC..."
                amount:
                  type: string
                  description: Bond amount (as string to preserve precision)
                  example: "1000000"
      responses:
        '201':
          description: Bond deposit queued
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - outboxId
                properties:
                  success:
                    type: boolean
                    example: true
                  outboxId:
                    type: string
                    description: Outbox item ID for tracking
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Invalid admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Invalid admin secret
        default:
          $ref: '#/components/responses/Error'

  /api/admin/fraud/bond/withdraw:
    post:
      summary: Withdraw bond from bond collateral contract
      description: Queues a withdraw_bond operation to the bond collateral contract via the outbox pattern.
      operationId: withdrawBond
      tags:
        - Admin
      security:
        - adminSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - inspector
                - amount
              properties:
                inspector:
                  type: string
                  description: Stellar address of the inspector
                  example: "GABC..."
                amount:
                  type: string
                  description: Bond amount to withdraw (as string to preserve precision)
                  example: "1000000"
      responses:
        '201':
          description: Bond withdrawal queued
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - outboxId
                properties:
                  success:
                    type: boolean
                    example: true
                  outboxId:
                    type: string
                    description: Outbox item ID for tracking
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Invalid admin secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: FORBIDDEN
                  message: Invalid admin secret
        default:
          $ref: '#/components/responses/Error'

  /api/staking/stake:
    post:
      summary: Stake USDC tokens
      description: |
        Stake USDC tokens and record the transaction on-chain.
        
        **Idempotency:** Submitting the same `(externalRefSource, externalRef)` pair twice will
        return the existing receipt without writing a duplicate on-chain.
      operationId: stakeTokens
      tags:
        - Staking
      # NOTE: createStakingRouter() applies no auth middleware to this route today (see PR
      # description — code/spec mismatch finding). security:[] reflects current code.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StakeRequest'
            example:
              amountUsdc: "1000.000000"
              externalRefSource: manual
              externalRef: stake-2024-01-15-001
      responses:
        '200':
          description: Staking confirmed and receipt written to chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440001"
                txId: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
                status: sent
                message: Staking confirmed and receipt written to chain
        '202':
          description: Staking confirmed, receipt queued for retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440001"
                txId: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
                status: pending
                message: Staking confirmed, receipt queued for retry
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/unstake:
    post:
      summary: Unstake USDC tokens
      description: |
        Unstake USDC tokens and record the transaction on-chain.
        
        **Idempotency:** Submitting the same `(externalRefSource, externalRef)` pair twice will
        return the existing receipt without writing a duplicate on-chain.
      operationId: unstakeTokens
      tags:
        - Staking
      # NOTE: createStakingRouter() applies no auth middleware to this route today (see PR
      # description — code/spec mismatch finding). security:[] reflects current code.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnstakeRequest'
            example:
              amountUsdc: "500.000000"
              externalRefSource: manual
              externalRef: unstake-2024-01-15-001
      responses:
        '200':
          description: Unstaking confirmed and receipt written to chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440002"
                txId: "b4g3d2e5f6c7g8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3"
                status: sent
                message: Unstaking confirmed and receipt written to chain
        '202':
          description: Unstaking confirmed, receipt queued for retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440002"
                txId: "b4g3d2e5f6c7g8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3"
                status: pending
                message: Unstaking confirmed, receipt queued for retry
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/claim:
    post:
      summary: Claim staking rewards
      description: |
        Claim staking rewards and record the transaction on-chain.
        
        **Idempotency:** Submitting the same `(externalRefSource, externalRef)` pair twice will
        return the existing receipt without writing a duplicate on-chain.
      operationId: claimStakingRewards
      tags:
        - Staking
      # NOTE: createStakingRouter() applies no auth middleware to this route today (see PR
      # description — code/spec mismatch finding). security:[] reflects current code.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimStakeRewardRequest'
            example:
              externalRefSource: manual
              externalRef: claim-2024-01-15-001
      responses:
        '200':
          description: Staking reward claim confirmed and receipt written to chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440003"
                txId: "c5h4e3f6g7d8h9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4"
                status: sent
                message: Staking reward claim confirmed and receipt written to chain
        '202':
          description: Staking reward claim confirmed, receipt queued for retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingResponse'
              example:
                success: true
                outboxId: "550e8400-e29b-41d4-a716-446655440003"
                txId: "c5h4e3f6g7d8h9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4"
                status: pending
                message: Staking reward claim confirmed, receipt queued for retry
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/position:
    get:
      summary: Get staking position
      description: Get current staking position (staked amount and claimable rewards)
      operationId: getStakingPosition
      tags:
        - Staking
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Staking position retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingPositionResponse'
              example:
                success: true
                position:
                  staked: "1000.000000"
                  claimable: "50.250000"
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/mvp-position:
    get:
      summary: Get MVP staking utilization position
      description: Read the additive MVP pool's total, used, unused, and claimable stake.
      operationId: getMvpStakingPosition
      tags:
        - Staking
      security:
        - bearerAuth: []
      responses:
        '200':
          description: MVP staking position retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MvpStakingPositionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/position:
    get:
      summary: Get delegated-staking position
      description: >-
        The caller's position inside the stake_delegation contract: the balance
        that contract holds for them, how much of it is currently delegated, how
        much is free, and the per-delegatee breakdown. This is a separate ledger
        from staking_pool — it is never a slice of /api/staking/position.
      operationId: getDelegationPosition
      tags:
        - Staking
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Delegated-staking position retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationPositionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/delegatee-earnings:
    get:
      summary: Get delegatee earnings
      description: >-
        Net rewards claimable by the caller acting as a delegatee (gross minus
        their commission), plus the accrued commission balance itself.
      operationId: getDelegateeEarnings
      tags:
        - Staking
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Delegatee earnings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegateeEarningsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/delegate:
    post:
      summary: Delegate stake to a delegatee
      description: Routes part of the caller's free stake_delegation balance to a delegatee.
      operationId: delegateStake
      tags:
        - Staking
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegateRequest'
      responses:
        '200':
          description: Stake delegated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationTxResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/undelegate/request:
    post:
      summary: Request undelegation
      description: >-
        Opens the contract's undelegation cooldown. The stake stays delegated
        until the matching complete call succeeds.
      operationId: requestUndelegate
      tags:
        - Staking
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegateRequest'
      responses:
        '202':
          description: Undelegation requested; cooldown started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationTxResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/undelegate/complete:
    post:
      summary: Complete a pending undelegation
      description: >-
        Settles a pending undelegation. The contract rejects this until its
        configured cooldown (7 days by default) has elapsed.
      operationId: completeUndelegate
      tags:
        - Staking
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [delegatee]
              properties:
                delegatee:
                  type: string
                  description: Delegatee whose pending undelegation should be settled
                  example: GBRPYHIL2CI3FNQ4BXLFMNDLFJUNPU2HY3ZMFSHONUCEOASW7QC7OX2H
      responses:
        '200':
          description: Undelegation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationTxResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/commission:
    post:
      summary: Set the caller's delegatee commission
      description: Sets the commission, in basis points, charged on stake delegated to the caller.
      operationId: setDelegateeCommission
      tags:
        - Staking
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rateBps]
              properties:
                rateBps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                  description: Commission in basis points
                  example: 1000
      responses:
        '200':
          description: Commission updated
          content:
            application/json:
              schema:
                type: object
                required: [success, txHash, rateBps]
                properties:
                  success: { type: boolean, example: true }
                  txHash: { type: string }
                  rateBps: { type: integer, example: 1000 }
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/claim-rewards:
    post:
      summary: Claim delegatee rewards
      description: Claims the caller's net delegatee rewards (gross minus their commission).
      operationId: claimDelegateeRewards
      tags:
        - Staking
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Delegatee rewards claimed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationTxResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/delegation/claim-commission:
    post:
      summary: Claim delegatee commission
      description: Claims the caller's accrued commission balance.
      operationId: claimDelegateeCommission
      tags:
        - Staking
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Commission claimed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegationTxResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/quote:
    post:
      summary: Get staking quote
      description: Returns a priced conversion from NGN to USDC for staking. Includes fees, slippage, and expiry window.
      operationId: getStakingQuote
      tags:
        - Staking
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amountNgn
                - paymentRail
              properties:
                amountNgn:
                  type: number
                  description: Amount in Nigerian Naira to stake
                  minimum: 1
                  example: 160000
                paymentRail:
                  type: string
                  enum: [paystack, flutterwave, bank_transfer, manual_admin]
                  description: Payment provider for the deposit
                  example: manual_admin
      responses:
        '201':
          description: Quote created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - quoteId
                  - amountNgn
                  - estimatedAmountUsdc
                  - fxRateNgnPerUsdc
                  - feesNgn
                  - expiresAt
                  - disclaimer
                properties:
                  quoteId:
                    type: string
                    format: uuid
                    description: Unique identifier for the quote
                    example: "550e8400-e29b-41d4-a716-446655440000"
                  amountNgn:
                    type: number
                    description: Original NGN amount
                    example: 160000
                  estimatedAmountUsdc:
                    type: string
                    description: Estimated USDC amount after fees and FX conversion (6 decimal places)
                    pattern: '^\d+(\.\d{1,6})?$'
                    example: "97.560976"
                  fxRateNgnPerUsdc:
                    type: number
                    description: FX rate used (NGN per 1 USDC)
                    example: 1600
                  feesNgn:
                    type: number
                    description: Fees deducted in NGN
                    example: 2400
                  expiresAt:
                    type: string
                    format: date-time
                    description: Quote expiry timestamp (ISO 8601)
                    example: "2024-01-15T10:05:00Z"
                  disclaimer:
                    type: string
                    description: Disclaimer about FX rate fluctuations
                    example: "Final USDC may differ slightly due to FX movements"
        '400':
          description: Validation error (invalid amount, exceeds maximum, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/staking/deposit/initiate:
    post:
      summary: Initiate NGN deposit for staking
      description: >-
        Creates a payment intent for NGN deposit. Returns PSP redirect URL or bank details.
        The x-user-id header is intended for trusted internal/BFF usage only in this MVP flow;
        public clients should prefer authenticated token-based identity.
      operationId: initiateStakingDeposit
      tags:
        - Staking
      # NOTE: identity here comes from the trusted x-user-id header (see description), not a
      # bearer token — the route has no authenticateToken/bearerAuth check (see PR
      # description — code/spec mismatch finding). security:[] reflects current code.
      security: []
      parameters:
        - in: header
          name: x-user-id
          required: true
          schema:
            type: string
            pattern: '^[A-Za-z0-9_-]{3,128}$'
          description: Internal-only user identifier header for trusted callers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - quoteId
                - paymentRail
              properties:
                quoteId:
                  type: string
                paymentRail:
                  type: string
                  enum: [paystack, flutterwave, manual_admin, bank]
                customerMeta:
                  type: object
                  properties:
                    name:
                      type: string
                    phone:
                      type: string
      responses:
        '201':
          description: Deposit initiated
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - depositId
                  - externalRefSource
                  - externalRef
                properties:
                  success:
                    type: boolean
                    example: true
                  depositId:
                    type: string
                    format: uuid
                  externalRefSource:
                    type: string
                    example: psp
                  externalRef:
                    type: string
                    example: pi_abc123
                  redirectUrl:
                    type: string
                    format: uri
                    nullable: true
                  bankDetails:
                    type: object
                    nullable: true
                    properties:
                      accountNumber:
                        type: string
                      bankName:
                        type: string
        '400':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/webhooks/payments/{rail}:
    post:
      summary: Payments webhook
      description: Ingest payment provider webhook. Idempotent by provider event ID plus canonical reference. Signature validation is always enforced in production and can be enabled in non-production with WEBHOOK_SIGNATURE_ENABLED=true.
      operationId: paymentsWebhook
      tags:
        - Webhooks
      security:
        - webhookSignature: []
      parameters:
        - name: rail
          in: path
          required: true
          schema:
            type: string
            enum: [paystack, flutterwave, manual_admin, bank]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - externalRefSource
                - externalRef
              properties:
                externalRefSource:
                  type: string
                externalRef:
                  type: string
                status:
                  type: string
                  enum: [confirmed, failed, reversed]
                  default: confirmed
                providerStatus:
                  type: string
                  description: Provider-specific status code for mapping
      responses:
        '200':
          description: Webhook processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '400':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals:
    get:
      summary: List governance proposals
      description: |
        Lists all stake-weighted governance proposals (contracts/governance), from id 1
        through the on-chain proposal count. Distinct from the timelock admin queue
        (/api/v1/admin-timelock), which is an unrelated contract.
      operationId: listGovernanceProposals
      tags:
        - Governance
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Proposals fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceProposalListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals/{id}:
    get:
      summary: Get a single governance proposal
      operationId: getGovernanceProposal
      tags:
        - Governance
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GovernanceProposalId'
      responses:
        '200':
          description: Proposal fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceProposalResponse'
        '404':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals/prepare:
    post:
      summary: Prepare an unsigned create_proposal transaction
      description: |
        Builds an unsigned Soroban transaction envelope for `create_proposal`, sourced
        from the caller's linked Stellar address. The contract calls `proposer.require_auth()`,
        so this backend cannot sign on the caller's behalf — the connected wallet must sign
        the returned XDR and post it to `/api/v1/governance/proposals/submit`.

        Rejects with 403 if the caller's staked balance is below MIN_STAKE_TO_PROPOSE. This is
        an informational pre-check against the real staking_pool balance; the authoritative
        gate remains the governance contract's own on-chain check.
      operationId: prepareGovernanceProposal
      tags:
        - Governance
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrepareGovernanceProposalRequest'
      responses:
        '200':
          description: Unsigned transaction ready for the caller's wallet to sign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsignedTransactionResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Staked balance is below MIN_STAKE_TO_PROPOSE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals/submit:
    post:
      summary: Submit a wallet-signed create_proposal transaction
      operationId: submitGovernanceProposal
      tags:
        - Governance
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitSignedTransactionRequest'
      responses:
        '200':
          description: Transaction broadcast and confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceTxResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals/{id}/vote/prepare:
    post:
      summary: Prepare an unsigned vote transaction
      description: |
        Builds an unsigned `vote` transaction sourced from the caller's linked Stellar
        address. Vote weight is the voter's stake, snapshotted on-chain at the moment of
        their first vote on this proposal — this backend performs no weight calculation.
      operationId: prepareGovernanceVote
      tags:
        - Governance
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GovernanceProposalId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GovernanceVoteRequest'
      responses:
        '200':
          description: Unsigned transaction ready for the caller's wallet to sign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsignedTransactionResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals/{id}/vote/submit:
    post:
      summary: Submit a wallet-signed vote transaction
      operationId: submitGovernanceVote
      tags:
        - Governance
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GovernanceProposalId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitSignedTransactionRequest'
      responses:
        '200':
          description: Vote transaction broadcast and confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceTxResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals/{id}/finalize:
    post:
      summary: Finalize a proposal after its voting period ends
      description: |
        `finalize_proposal` is permissionless on-chain (no require_auth) — any authenticated
        caller may trigger it once the voting period has elapsed; the backend's operational
        key only pays the fee.
      operationId: finalizeGovernanceProposal
      tags:
        - Governance
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GovernanceProposalId'
      responses:
        '200':
          description: Proposal finalized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceTxResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

  /api/v1/governance/proposals/{id}/execute:
    post:
      summary: Execute a passed proposal after its timelock elapses
      description: |
        `execute_proposal` is permissionless on-chain and has no direct on-chain effect
        beyond flipping the proposal's status and emitting `proposal_executed` — applying
        `proposedValue` to whatever `paramKey` represents is an off-chain/other-contract
        action driven by that event.
      operationId: executeGovernanceProposal
      tags:
        - Governance
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GovernanceProposalId'
      responses:
        '200':
          description: Proposal executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceTxResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'

components:
  parameters:
    GovernanceProposalId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
      description: Governance proposal id (1-based, contracts/governance/src/lib.rs:188)

  schemas:
    User:
      type: object
      required:
        - id
        - email
        - createdAt
        - name
        - role
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time
        name:
          type: string
        role:
          type: string
          enum: [tenant, landlord, agent]

    AuthTokenResponse:
      type: object
      required:
        - token
        - user
      properties:
        token:
          type: string
        user:
          $ref: '#/components/schemas/User'

    WalletChallengeRequest:
      type: object
      required:
        - address
      properties:
        address:
          type: string
          description: Stellar public key (G...)
          pattern: '^G[A-Z0-9]{55}$'

    WalletChallengeResponse:
      type: object
      required:
        - challengeXdr
        - expiresAt
      properties:
        challengeXdr:
          type: string
        expiresAt:
          type: string
          format: date-time

    WalletVerifyRequest:
      type: object
      required:
        - address
        - signedChallengeXdr
      properties:
        address:
          type: string
          description: Stellar public key (G...)
          pattern: '^G[A-Z0-9]{55}$'
        signedChallengeXdr:
          type: string

    RiskStateResponse:
      type: object
      required:
        - isFrozen
        - freezeReason
        - deficitNgn
        - updatedAt
      properties:
        isFrozen:
          type: boolean
        freezeReason:
          type: string
          nullable: true
          enum: [NEGATIVE_BALANCE, MANUAL, COMPLIANCE]
        deficitNgn:
          type: number
        updatedAt:
          type: string
          format: date-time

    IndexedReceipt:
      type: object
      required:
        - txId
        - txType
        - dealId
        - amountUsdc
        - externalRefHash
        - ledger
        - indexedAt
      properties:
        txId:
          type: string
        txType:
          type: string
        dealId:
          type: string
        listingId:
          type: string
        amountUsdc:
          type: string
        amountNgn:
          type: number
        fxRate:
          type: number
        fxProvider:
          type: string
        from:
          type: string
        to:
          type: string
        externalRefHash:
          type: string
        metadataHash:
          type: string
        ledger:
          type: integer
        indexedAt:
          type: string
          format: date-time

    PagedReceipts:
      type: object
      required:
        - data
        - total
        - page
        - pageSize
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/IndexedReceipt'
        total:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer

    DealReceiptsResponse:
      type: object
      required:
        - dealId
        - receipts
        - total
      properties:
        dealId:
          type: string
        receipts:
          type: array
          items:
            $ref: '#/components/schemas/IndexedReceipt'
        total:
          type: integer

    CreateSupportMessageRequest:
      type: object
      required:
        - name
        - email
        - subject
        - message
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
          maxLength: 254
        phone:
          type: string
          nullable: true
          maxLength: 32
        subject:
          type: string
          minLength: 1
          maxLength: 200
        message:
          type: string
          minLength: 1
          maxLength: 5000

    CreateSupportMessageResponse:
      type: object
      required:
        - success
        - messageId
      properties:
        success:
          type: boolean
          example: true
        messageId:
          type: string
          format: uuid

    CreateWhistleblowerRatingRequest:
      type: object
      required: [whistleblowerId, dealId, rating]
      properties:
        whistleblowerId:
          type: string
          minLength: 1
        dealId:
          type: string
          minLength: 1
        rating:
          type: integer
          minimum: 1
          maximum: 5
        reviewText:
          type: string
          nullable: true
          maxLength: 2000

    WhistleblowerRating:
      type: object
      required:
        - ratingId
        - whistleblowerId
        - tenantId
        - dealId
        - rating
        - createdAt
      properties:
        ratingId:
          type: string
          format: uuid
        whistleblowerId:
          type: string
        tenantId:
          type: string
        dealId:
          type: string
        rating:
          type: integer
          minimum: 1
          maximum: 5
        reviewText:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time

    CreateWhistleblowerRatingResponse:
      type: object
      required: [success, rating]
      properties:
        success:
          type: boolean
        rating:
          $ref: "#/components/schemas/WhistleblowerRating"

    WhistleblowerRatingAggregate:
      type: object
      required: [whistleblowerId, count, average, breakdown]
      properties:
        whistleblowerId:
          type: string
        count:
          type: integer
        average:
          type: number
        breakdown:
          type: object
          additionalProperties:
            type: integer

    CreatePropertyIssueReportRequest:
      type: object
      required:
        - propertyId
        - reportCategory
        - reportDetails
      properties:
        propertyId:
          type: string
          minLength: 1
        reportCategory:
          type: string
          minLength: 1
          maxLength: 64
          description: Category selected in the dialog (frontend field name).
        reportDetails:
          type: string
          minLength: 1
          maxLength: 2000
          description: Free-text details entered in the dialog (frontend field name).

    CreatePropertyIssueReportResponse:
      type: object
      required: [success, reportId]
      properties:
        success:
          type: boolean
          example: true
        reportId:
          type: string
          format: uuid

    BankAccountDetails:
      type: object
      required:
        - accountNumber
        - accountName
        - bankName
      properties:
        accountNumber:
          type: string
          minLength: 10
          maxLength: 10
        accountName:
          type: string
        bankName:
          type: string

    WithdrawalRequest:
      type: object
      required:
        - amountNgn
      properties:
        amountNgn:
          type: number
          minimum: 100
          maximum: 1000000
        bankAccountRef:
          type: string
          description: Reference to a saved bank account
        bankAccount:
          $ref: '#/components/schemas/BankAccountDetails'

    WithdrawalResponse:
      type: object
      required:
        - success
        - id
        - amountNgn
        - status
        - bankAccount
        - reference
        - createdAt
        - processedAt
        - failureReason
      properties:
        success:
          type: boolean
        id:
          type: string
        amountNgn:
          type: number
        status:
          type: string
          enum: [pending, approved, rejected, confirmed, failed, reversed]
        bankAccount:
          $ref: '#/components/schemas/BankAccountDetails'
        reference:
          type: string
        createdAt:
          type: string
        processedAt:
          type: string
          nullable: true
        failureReason:
          type: string
          nullable: true

    WithdrawalHistoryResponse:
      type: object
      required:
        - success
        - entries
        - nextCursor
      properties:
        success:
          type: boolean
        entries:
          type: array
          items:
            $ref: '#/components/schemas/WithdrawalResponse'
        nextCursor:
          type: string
          nullable: true

    AdminListing:
      type: object
      required:
        - listingId
        - whistleblowerId
        - address
        - bedrooms
        - bathrooms
        - annualRentNgn
        - photos
        - status
        - createdAt
        - updatedAt
      properties:
        listingId:
          type: string
          format: uuid
        whistleblowerId:
          type: string
        address:
          type: string
        city:
          type: string
        area:
          type: string
        bedrooms:
          type: integer
          minimum: 0
        bathrooms:
          type: integer
          minimum: 0
        annualRentNgn:
          type: integer
          minimum: 1
        description:
          type: string
        photos:
          type: array
          items:
            type: string
            format: uri
        status:
          type: string
          enum: [pending_review, approved, rejected, rented]
        reviewedBy:
          type: string
          description: ID of the admin who reviewed this listing
        reviewedAt:
          type: string
          format: date-time
          description: Timestamp of the review decision
        rejectionReason:
          type: string
          description: Reason provided when the listing was rejected
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    ModerationResult:
      type: object
      required:
        - listingId
        - status
        - reviewedBy
        - reviewedAt
        - updatedAt
      properties:
        listingId:
          type: string
          format: uuid
        status:
          type: string
          enum: [approved, rejected]
        reviewedBy:
          type: string
          example: admin-001
        reviewedAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    PaymentTxType:
      type: string
      enum:
        - tenant_repayment
        - landlord_payout
        - whistleblower_reward
      description: |
        Transaction type for the on-chain USDC receipt.
        - `tenant_repayment` — tenant repaying ShelterFlex financing
        - `landlord_payout` — ShelterFlex paying landlord upfront
        - `whistleblower_reward` — reward paid to a whistleblower

    ConfirmPaymentRequest:
      type: object
      description: |
        Request body for confirming a payment. **USDC is the canonical unit** for all
        on-chain receipts. NGN values (`amountNgn`, `fxRateNgnPerUsdc`, `fxProvider`) are
        optional metadata and are NOT stored on-chain.
      required:
        - dealId
        - txType
        - amountUsdc
        - tokenAddress
        - externalRefSource
        - externalRef
      properties:
        dealId:
          type: string
          description: ID of the deal this payment is associated with
          example: "550e8400-e29b-41d4-a716-446655440000"
        txType:
          $ref: '#/components/schemas/PaymentTxType'
        amountUsdc:
          type: string
          description: |
            Payment amount in USDC (canonical on-chain unit). Decimal string with up to 6 places.
          pattern: '^\d+(\.\d{1,6})?$'
          example: "64.52"
        tokenAddress:
          type: string
          description: USDC token contract address on Stellar
          example: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
        externalRefSource:
          type: string
          description: Payment provider identifier (e.g., stripe, manual, stellar, flutterwave)
          pattern: '^[a-zA-Z0-9_-]+$'
          example: stripe
        externalRef:
          type: string
          description: Provider-specific payment reference string (e.g., charge ID, transaction hash)
          example: pi_3OZxyz123456
        amountNgn:
          type: number
          description: Payment amount in NGN (optional metadata, not stored on-chain)
          example: 100000
        fxRateNgnPerUsdc:
          type: number
          description: FX rate (NGN per 1 USDC) at time of payment (optional metadata)
          example: 1550.00
        fxProvider:
          type: string
          description: FX rate provider name (optional metadata)
          example: exchangerate-api

    PaymentConfirmationResponse:
      type: object
      required:
        - success
        - outboxId
        - txId
        - status
        - message
      properties:
        success:
          type: boolean
          example: true
        outboxId:
          type: string
          format: uuid
          description: Internal outbox item ID
          example: "550e8400-e29b-41d4-a716-446655440001"
        txId:
          type: string
          description: Deterministic SHA-256 transaction ID (BytesN<32> as hex). Same (externalRefSource, externalRef) always yields the same txId.
          example: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
        status:
          type: string
          enum: [pending, sent, failed]
          example: sent
        message:
          type: string
          example: "Payment confirmed and USDC receipt written to chain"

    ListingStatus:
      type: string
      enum:
        - pending_review
        - approved
        - rejected
        - rented
      example: pending_review

    CreateListingRequest:
      type: object
      required:
        - whistleblowerId
        - address
        - bedrooms
        - bathrooms
        - annualRentNgn
        - photos
      properties:
        whistleblowerId:
          type: string
          description: ID of the whistleblower creating the listing
          example: wb-001
        address:
          type: string
          description: Full address of the property
          minLength: 1
          example: 123 Main Street, Ikeja, Lagos
        city:
          type: string
          description: City where the property is located
          example: Lagos
        area:
          type: string
          description: Specific area or neighborhood
          example: Ikeja
        bedrooms:
          type: integer
          description: Number of bedrooms
          minimum: 0
          example: 2
        bathrooms:
          type: integer
          description: Number of bathrooms
          minimum: 0
          example: 2
        annualRentNgn:
          type: integer
          description: Annual rent in Nigerian Naira
          minimum: 1
          example: 1200000
        description:
          type: string
          description: Optional description of the property
          example: Beautiful 2-bedroom apartment with modern amenities
        photos:
          type: array
          description: Array of photo URLs (minimum 3, maximum 20)
          minItems: 3
          maxItems: 20
          items:
            type: string
            format: uri
            example: https://example.com/photo1.jpg

    Listing:
      type: object
      required:
        - listingId
        - whistleblowerId
        - address
        - bedrooms
        - bathrooms
        - annualRentNgn
        - photos
        - status
        - createdAt
        - updatedAt
      properties:
        listingId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        whistleblowerId:
          type: string
          example: wb-001
        address:
          type: string
          example: 123 Main Street, Ikeja, Lagos
        city:
          type: string
          nullable: true
          example: Lagos
        area:
          type: string
          nullable: true
          example: Ikeja
        bedrooms:
          type: integer
          example: 2
        bathrooms:
          type: integer
          example: 2
        annualRentNgn:
          type: integer
          example: 1200000
        description:
          type: string
          nullable: true
          example: Beautiful 2-bedroom apartment
        photos:
          type: array
          items:
            type: string
            format: uri
          example:
            - https://example.com/photo1.jpg
            - https://example.com/photo2.jpg
            - https://example.com/photo3.jpg
        status:
          $ref: '#/components/schemas/ListingStatus'
        createdAt:
          type: string
          format: date-time
          example: 2024-01-15T10:00:00Z
        updatedAt:
          type: string
          format: date-time
          example: 2024-01-15T10:00:00Z
        rejectionReason:
          type: string
          nullable: true
          description: Reason for rejection (only present if status is rejected)
          example: Insufficient photo quality
        dealId:
          type: string
          format: uuid
          nullable: true
          description: ID of the deal this listing is linked to (only present if status is rented)
          example: 550e8400-e29b-41d4-a716-446655440001

    DealStatus:
      type: string
      enum:
        - draft
        - active
        - completed
        - defaulted
      example: draft

    ScheduleItemStatus:
      type: string
      enum:
        - upcoming
        - due
        - paid
        - late
      example: upcoming

    ScheduleItem:
      type: object
      required:
        - period
        - dueDate
        - amountNgn
        - status
      properties:
        period:
          type: integer
          description: Period number in the repayment schedule (1-indexed)
          example: 1
        dueDate:
          type: string
          format: date-time
          description: ISO date when payment is due
          example: 2024-02-15T00:00:00Z
        amountNgn:
          type: number
          format: double
          description: Payment amount in Nigerian Naira
          example: 83333.33
        status:
          $ref: '#/components/schemas/ScheduleItemStatus'

    Deal:
      type: object
      required:
        - dealId
        - tenantId
        - landlordId
        - annualRentNgn
        - depositNgn
        - financedAmountNgn
        - termMonths
        - createdAt
        - status
      properties:
        dealId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        tenantId:
          type: string
          description: ID of the tenant repaying the financing
          example: tenant-001
        landlordId:
          type: string
          description: ID of the landlord who received upfront payment
          example: landlord-001
        listingId:
          type: string
          format: uuid
          nullable: true
          description: Optional ID of the associated property listing
          example: 550e8400-e29b-41d4-a716-446655440001
        annualRentNgn:
          type: integer
          description: Annual rent amount in Naira
          example: 1200000
        depositNgn:
          type: integer
          description: Deposit amount paid by tenant (must be >= 20% of annual rent)
          example: 240000
        financedAmountNgn:
          type: integer
          description: Amount financed by ShelterFlex (annual rent - deposit)
          example: 960000
        termMonths:
          type: integer
          description: Repayment term in months (3, 6, or 12)
          example: 12
        createdAt:
          type: string
          format: date-time
          example: 2024-01-15T10:00:00Z
        status:
          $ref: '#/components/schemas/DealStatus'

    DealWithSchedule:
      type: object
      required:
        - dealId
        - tenantId
        - landlordId
        - annualRentNgn
        - depositNgn
        - financedAmountNgn
        - termMonths
        - createdAt
        - status
        - schedule
      properties:
        dealId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        tenantId:
          type: string
          example: tenant-001
        landlordId:
          type: string
          example: landlord-001
        listingId:
          type: string
          format: uuid
          nullable: true
          example: 550e8400-e29b-41d4-a716-446655440001
        annualRentNgn:
          type: integer
          example: 1200000
        depositNgn:
          type: integer
          example: 240000
        financedAmountNgn:
          type: integer
          example: 960000
        termMonths:
          type: integer
          example: 12
        createdAt:
          type: string
          format: date-time
          example: 2024-01-15T10:00:00Z
        status:
          $ref: '#/components/schemas/DealStatus'
        schedule:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleItem'

    CreateDealRequest:
      type: object
      required:
        - tenantId
        - landlordId
        - annualRentNgn
        - depositNgn
        - termMonths
      properties:
        tenantId:
          type: string
          description: ID of the tenant who will repay the financing
          example: tenant-001
        landlordId:
          type: string
          description: ID of the landlord who will receive upfront payment
          example: landlord-001
        listingId:
          type: string
          format: uuid
          nullable: true
          description: Optional ID of the associated property listing
          example: 550e8400-e29b-41d4-a716-446655440001
        annualRentNgn:
          type: integer
          description: Annual rent amount in Naira
          example: 1200000
        depositNgn:
          type: integer
          description: Deposit amount paid by tenant (must be >= 20% of annual rent)
          example: 240000
        termMonths:
          type: integer
          description: Repayment term in months (must be 3, 6, or 12)
          example: 12

    UpdateDealStatusRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/DealStatus'

    UpdateScheduleItemRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/ScheduleItemStatus'

    PaginatedDeals:
      type: object
      required:
        - deals
        - total
        - page
        - pageSize
        - totalPages
      properties:
        deals:
          type: array
          items:
            $ref: '#/components/schemas/Deal'
        total:
          type: integer
          description: Total number of deals matching the filter
          example: 42
        page:
          type: integer
          description: Current page number
          example: 1
        pageSize:
          type: integer
          description: Number of deals per page
          example: 20
        totalPages:
          type: integer
          description: Total number of pages
          example: 3

    Pagination:
      type: object
      required:
        - total
        - page
        - pageSize
        - totalPages
      properties:
        total:
          type: integer
          description: Total number of items
          example: 42
        page:
          type: integer
          description: Current page number
          example: 1
        pageSize:
          type: integer
          description: Number of items per page
          example: 20
        totalPages:
          type: integer
          description: Total number of pages
          example: 3

    MarkRewardPaidRequest:
      type: object
      required:
        - amountUsdc
        - tokenAddress
        - externalRefSource
        - externalRef
      properties:
        amountUsdc:
          type: number
          description: Payment amount in USDC
          minimum: 0.01
          example: 100
        tokenAddress:
          type: string
          description: USDC token contract address
          example: USDC_CONTRACT_ADDRESS
        externalRefSource:
          type: string
          description: Source of external reference (e.g., "stripe", "manual")
          example: stripe
        externalRef:
          type: string
          description: External payment reference ID
          example: pi_abc123
        amountNgn:
          type: number
          description: Optional payment amount in Nigerian Naira
          example: 150000
        fxRateNgnPerUsdc:
          type: number
          description: Optional FX rate (NGN per USDC)
          example: 1500
        fxProvider:
          type: string
          description: Optional FX rate provider
          example: coinbase

    EpochInfo:
      type: object
      description: Information about a specific epoch in the epoch rewards contract
      required:
        - epoch_number
        - start_ts
        - duration_secs
        - end_ts
        - seal_ts
        - sealed
        - total_rewards
        - carried_forward
        - reward_index_at_seal
        - dust
        - total_claimable_at_seal
      properties:
        epoch_number:
          type: integer
          description: The epoch number
          example: 1
        start_ts:
          type: integer
          description: Unix timestamp when the epoch started
          example: 1000
        duration_secs:
          type: integer
          description: Duration of the epoch in seconds
          example: 86400
        end_ts:
          type: integer
          description: Unix timestamp when the epoch ends
          example: 87400
        seal_ts:
          type: integer
          description: Unix timestamp when the epoch was sealed
          example: 87400
        sealed:
          type: boolean
          description: Whether the epoch has been sealed
          example: true
        total_rewards:
          type: string
          description: Total rewards added to the epoch as string
          example: "10000"
        carried_forward:
          type: string
          description: Amount carried forward from previous epoch as string
          example: "0"
        reward_index_at_seal:
          type: string
          description: Reward index at the time of sealing as string
          example: "1000"
        dust:
          type: string
          description: Dust amount as string
          example: "0"
        total_claimable_at_seal:
          type: string
          description: Total claimable amount at seal as string
          example: "5000"
    EarningsResponse:
      type: object
      required:
        - totals
        - history
      properties:
        totals:
          $ref: "#/components/schemas/EarningsTotals"
        history:
          type: array
          items:
            $ref: "#/components/schemas/EarningsHistoryItem"

    EarningsTotals:
      type: object
      required:
        - totalNgn
        - pendingNgn
        - paidNgn
      properties:
        totalNgn:
          type: number
          format: double
          description: Total earnings in Nigerian Naira across all statuses
          example: 750000
        pendingNgn:
          type: number
          format: double
          description: Pending earnings in Nigerian Naira (pending + payable statuses)
          example: 450000
        paidNgn:
          type: number
          format: double
          description: Paid earnings in Nigerian Naira
          example: 300000
        totalUsdc:
          type: number
          format: double
          description: Total earnings in USDC (optional)
          example: 500
        pendingUsdc:
          type: number
          format: double
          description: Pending earnings in USDC (optional)
          example: 300
        paidUsdc:
          type: number
          format: double
          description: Paid earnings in USDC (optional)
          example: 200

    EarningsHistoryItem:
      type: object
      required:
        - rewardId
        - listingId
        - dealId
        - amountNgn
        - amountUsdc
        - status
        - createdAt
      properties:
        rewardId:
          type: string
          description: Unique identifier for the reward
          example: "rw-001"
        listingId:
          type: string
          description: Identifier of the reported listing
          example: "lst-456"
        dealId:
          type: string
          description: Identifier of the associated deal
          example: "deal-789"
        amountNgn:
          type: number
          format: double
          description: Reward amount in Nigerian Naira
          example: 300000
        amountUsdc:
          type: number
          format: double
          description: Reward amount in USDC
          example: 200
        status:
          type: string
          enum:
            - pending
            - payable
            - paid
          description: Current payout status of the reward
          example: "paid"
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the reward was created
          example: "2024-01-15T10:30:00Z"
        paidAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the reward was paid (only present when status is "paid")
          example: "2024-01-20T14:45:00Z"

    DealProgressResponse:
      type: object
      required:
        - totalPaidUsdc
        - periodsPaid
        - remainingPeriods
        - nextDueDate
        - equityAccumulatedUsdc
        - equityCapUsdc
        - equityPercentageBps
        - equityPaymentsConfirmed
      properties:
        totalPaidUsdc:
          type: string
          description: Total USDC paid across all confirmed on-chain TENANT_REPAYMENT receipts (decimal string with 6 decimal places)
          example: "129.040000"
        periodsPaid:
          type: integer
          description: Number of TENANT_REPAYMENT receipts confirmed on-chain
          example: 2
        remainingPeriods:
          type: integer
          description: Number of remaining repayment periods (termMonths minus periodsPaid, clamped to >= 0)
          example: 10
        nextDueDate:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 due date of the next scheduled payment; null if fully paid
          example: "2024-04-15T00:00:00.000Z"
        lastPaymentTxId:
          type: string
          description: txId (SHA-256 hex) of the most recent confirmed receipt
          example: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
        lastPaymentExternalRefSource:
          type: string
          description: Source part of the canonical external reference (e.g. "stripe", "manual")
          example: stripe
        lastPaymentExternalRef:
          type: string
          description: Reference part of the canonical external reference (e.g. payment intent ID)
          example: pi_3OZxyz123456
        equityAccumulatedUsdc:
          type: string
          description: |
            Rent-to-own equity confirmed on-chain — sum of `sent`
            RENT_TO_OWN_EQUITY_PAYMENT receipts' equityAmountUsdc (decimal
            string, 6 decimal places). Reflects record_equity_payment calls
            that actually landed on the rent_to_own contract.
          example: "80.650000"
        equityCapUsdc:
          type: string
          description: rent_to_own's property_value_usdc equity cap for this deal (decimal string, 6 decimal places)
          example: "600.000000"
        equityPercentageBps:
          type: integer
          description: equityAccumulatedUsdc as basis points of equityCapUsdc (0-10000), mirroring the contract's get_equity_percentage
          example: 1344
        equityPaymentsConfirmed:
          type: integer
          description: Number of RENT_TO_OWN_EQUITY_PAYMENT receipts confirmed on-chain
          example: 2

    PaymentDisputeReason:
      type: string
      enum:
        - amount_discrepancy
        - duplicate_charge
        - service_not_received
        - early_termination
        - property_issue
        - other

    PaymentDisputeStatus:
      type: string
      enum:
        - pending
        - under_review
        - resolved
        - rejected

    PaymentDisputeCreateRequest:
      type: object
      required:
        - paymentId
        - dealId
        - reason
        - description
      properties:
        paymentId:
          type: string
          format: uuid
        dealId:
          type: string
          description: The deal_escrow deal ID this dispute is challenging a pending rent release for.
          example: 550e8400-e29b-41d4-a716-446655440000
        reason:
          $ref: '#/components/schemas/PaymentDisputeReason'
        description:
          type: string
          minLength: 10
          maxLength: 1000
        evidenceKeys:
          type: array
          maxItems: 5
          items:
            type: string

    PaymentDispute:
      type: object
      required:
        - id
        - userId
        - paymentId
        - dealId
        - reason
        - description
        - evidenceKeys
        - status
        - resolution
        - resolvedBy
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        userId:
          type: string
        paymentId:
          type: string
          format: uuid
        dealId:
          type: string
          nullable: true
          description: Null for disputes filed before deal_id was captured.
        reason:
          $ref: '#/components/schemas/PaymentDisputeReason'
        description:
          type: string
        evidenceKeys:
          type: array
          items:
            type: string
        status:
          $ref: '#/components/schemas/PaymentDisputeStatus'
        resolution:
          type: string
          nullable: true
        resolvedBy:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
                - UNAUTHORIZED
                - FORBIDDEN
                - TOO_MANY_REQUESTS
                - NOT_FOUND
                - CONFLICT
                - LISTING_ALREADY_RENTED
                - SOROBAN_ERROR
                - INTERNAL_ERROR
              example: NOT_FOUND
            message:
              type: string
              example: "Resource not found"
            details:
              type: object
              description: Optional structured context for the error
              additionalProperties: true

    StakeRequest:
      type: object
      description: Request body for staking USDC tokens
      required:
        - amountUsdc
        - externalRefSource
        - externalRef
      properties:
        amountUsdc:
          type: string
          description: Amount to stake in USDC (canonical on-chain unit). Decimal string with up to 6 places.
          pattern: '^\d+(\.\d{1,6})?$'
          example: "1000.000000"
        externalRefSource:
          type: string
          description: Staking provider identifier (e.g., manual, stellar)
          pattern: '^[a-zA-Z0-9_-]+$'
          example: manual
        externalRef:
          type: string
          description: Provider-specific staking reference string
          example: stake-2024-01-15-001

    UnstakeRequest:
      type: object
      description: Request body for unstaking USDC tokens
      required:
        - amountUsdc
        - externalRefSource
        - externalRef
      properties:
        amountUsdc:
          type: string
          description: Amount to unstake in USDC (canonical on-chain unit). Decimal string with up to 6 places.
          pattern: '^\d+(\.\d{1,6})?$'
          example: "500.000000"
        externalRefSource:
          type: string
          description: Unstaking provider identifier (e.g., manual, stellar)
          pattern: '^[a-zA-Z0-9_-]+$'
          example: manual
        externalRef:
          type: string
          description: Provider-specific unstaking reference string
          example: unstake-2024-01-15-001

    ClaimStakeRewardRequest:
      type: object
      description: Request body for claiming staking rewards
      required:
        - externalRefSource
        - externalRef
      properties:
        externalRefSource:
          type: string
          description: Claim provider identifier (e.g., manual, stellar)
          pattern: '^[a-zA-Z0-9_-]+$'
          example: manual
        externalRef:
          type: string
          description: Provider-specific claim reference string
          example: claim-2024-01-15-001

    StakingResponse:
      type: object
      required:
        - success
        - outboxId
        - txId
        - status
        - message
      properties:
        success:
          type: boolean
          example: true
        outboxId:
          type: string
          format: uuid
          description: ID of the outbox item
          example: "550e8400-e29b-41d4-a716-446655440001"
        txId:
          type: string
          description: 32-byte transaction ID as hex
          example: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
        status:
          type: string
          enum: [pending, sent, failed]
          example: sent
        message:
          type: string
          example: Staking confirmed and receipt written to chain

    StakingPositionResponse:
      type: object
      required:
        - success
        - position
      properties:
        success:
          type: boolean
          example: true
        position:
          type: object
          required:
            - staked
            - claimable
          properties:
            staked:
              type: string
              description: Total amount currently staked in USDC
              pattern: '^\d+(\.\d{1,6})?$'
              example: "1000.000000"
            claimable:
              type: string
              description: Amount of rewards available for claiming in USDC
              pattern: '^\d+(\.\d{1,6})?$'
              example: "50.250000"

    MvpStakingPositionResponse:
      type: object
      required: [success, position]
      properties:
        success:
          type: boolean
          example: true
        position:
          type: object
          required: [staked, used, unused, claimable]
          properties:
            staked: { type: string, example: "1000.000000" }
            used: { type: string, description: Stake locked for an authorized protocol use, example: "250.000000" }
            unused: { type: string, description: Stake still available to unstake, example: "750.000000" }
            claimable: { type: string, example: "50.250000" }

    DelegationPositionResponse:
      type: object
      required: [success, position]
      properties:
        success:
          type: boolean
          example: true
        position:
          type: object
          required: [staked, delegated, free, currentEpoch, delegations]
          properties:
            staked:
              type: string
              description: Balance held by stake_delegation for the caller (NOT the staking_pool position)
              example: "1000.000000"
            delegated: { type: string, description: Portion currently routed to delegatees, example: "250.000000" }
            free: { type: string, description: Portion still available to delegate or unstake, example: "750.000000" }
            currentEpoch: { type: integer, description: stake_delegation's current epoch number, example: 4 }
            delegations:
              type: array
              items:
                type: object
                required: [delegatee, amountUsdc, activatedEpoch]
                properties:
                  delegatee: { type: string, example: GBRPYHIL2CI3FNQ4BXLFMNDLFJUNPU2HY3ZMFSHONUCEOASW7QC7OX2H }
                  amountUsdc: { type: string, example: "250.000000" }
                  activatedEpoch: { type: integer, example: 2 }

    DelegateeEarningsResponse:
      type: object
      required: [success, delegatee, earnings]
      properties:
        success: { type: boolean, example: true }
        delegatee: { type: string, example: GBRPYHIL2CI3FNQ4BXLFMNDLFJUNPU2HY3ZMFSHONUCEOASW7QC7OX2H }
        earnings:
          type: object
          required: [claimable, commissionClaimable]
          properties:
            claimable: { type: string, description: Net rewards after the commission split, example: "45.000000" }
            commissionClaimable: { type: string, description: Accrued commission balance, example: "5.000000" }

    DelegateRequest:
      type: object
      required: [delegatee, amountUsdc]
      properties:
        delegatee:
          type: string
          pattern: '^G[A-Z2-7]{55}$'
          description: Stellar address of the delegatee
          example: GBRPYHIL2CI3FNQ4BXLFMNDLFJUNPU2HY3ZMFSHONUCEOASW7QC7OX2H
        amountUsdc:
          type: string
          pattern: '^\d+(\.\d{1,6})?$'
          description: Amount in USDC (canonical unit)
          example: "250.000000"

    DelegationTxResponse:
      type: object
      required: [success, txHash]
      properties:
        success: { type: boolean, example: true }
        txHash: { type: string, description: Stellar transaction hash for the submitted contract call }
        message: { type: string, example: Stake delegated }
        delegation:
          type: object
          properties:
            delegatee: { type: string }
            amountUsdc: { type: string }

    GovernanceProposalStatus:
      type: string
      description: Mirrors ProposalStatus in contracts/governance/src/lib.rs.
      enum:
        - Active
        - Passed
        - Rejected
        - Executed
        - Cancelled

    GovernanceProposal:
      type: object
      description: |
        Mirrors the Proposal struct in contracts/governance/src/lib.rs. i128 fields are
        decimal strings so values beyond Number.MAX_SAFE_INTEGER keep full precision.
      required:
        - id
        - proposer
        - paramKey
        - currentValue
        - proposedValue
        - votesFor
        - votesAgainst
        - status
        - createdAt
        - votingEndsAt
        - snapshottedTotalStaked
      properties:
        id:
          type: integer
          example: 1
        proposer:
          type: string
          description: Stellar address of the proposer
          example: "GABCDEXAMPLE0000000000000000000000000000000000000000000000AB"
        paramKey:
          type: string
          description: Arbitrary Soroban symbol chosen by the proposer; opaque to the contract and this API.
          example: "min_stake"
        currentValue:
          type: string
          description: i128 as a decimal string
          example: "100"
        proposedValue:
          type: string
          description: i128 as a decimal string
          example: "200"
        votesFor:
          type: string
          example: "600000"
        votesAgainst:
          type: string
          example: "200000"
        status:
          $ref: '#/components/schemas/GovernanceProposalStatus'
        createdAt:
          type: integer
          description: Ledger timestamp (unix seconds)
          example: 1735689600
        votingEndsAt:
          type: integer
          example: 1736294400
        snapshottedTotalStaked:
          type: string
          description: Total staked snapshotted at proposal creation, used for quorum
          example: "1000000"

    GovernanceProposalListResponse:
      type: object
      required:
        - success
        - proposals
        - count
      properties:
        success:
          type: boolean
          example: true
        proposals:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceProposal'
        count:
          type: integer
          example: 1

    GovernanceProposalResponse:
      type: object
      required:
        - success
        - proposal
      properties:
        success:
          type: boolean
          example: true
        proposal:
          $ref: '#/components/schemas/GovernanceProposal'

    PrepareGovernanceProposalRequest:
      type: object
      required:
        - paramKey
        - currentValue
        - proposedValue
      properties:
        paramKey:
          type: string
          pattern: '^[A-Za-z0-9_]{1,32}$'
          description: Soroban symbol (max 32 chars of [A-Za-z0-9_])
          example: "min_stake"
        currentValue:
          oneOf:
            - type: string
            - type: integer
          example: "100"
        proposedValue:
          oneOf:
            - type: string
            - type: integer
          example: "200"

    GovernanceVoteRequest:
      type: object
      required:
        - support
      properties:
        support:
          type: boolean
          description: true = vote for, false = vote against
          example: true

    SubmitSignedTransactionRequest:
      type: object
      required:
        - signedXdr
      properties:
        signedXdr:
          type: string
          description: Base64 transaction envelope signed by the caller's connected wallet
      example:
        signedXdr: "AAAAAgAAAAA..."

    UnsignedTransactionResponse:
      type: object
      required:
        - success
        - xdr
      properties:
        success:
          type: boolean
          example: true
        xdr:
          type: string
          description: Base64 unsigned transaction envelope for the caller's wallet to sign

    GovernanceTxResponse:
      type: object
      required:
        - success
        - txHash
      properties:
        success:
          type: boolean
          example: true
        txHash:
          type: string
          example: "a3f2c1d4e5b6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"

  responses:
    Error:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: "TOO_MANY_REQUESTS"
              message: "Rate limit exceeded"

    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: "VALIDATION_ERROR"
              message: "Request validation failed"
              details:
                fieldErrors:
                  - field: "email"
                    message: "Invalid email address"

    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: "UNAUTHORIZED"
              message: "Authentication required"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        Ordinary authenticated-session bearer token (authenticateToken middleware only —
        no elevated role/permission required).
    bearerAdminAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        Same bearer token as bearerAuth, but the route additionally requires the caller's
        session to carry an admin-tier RBAC permission (requirePermission(resource, action)
        in middleware/rbac.ts, e.g. payouts:trigger) or an explicit admin/super_admin role
        check. Kept as a distinct scheme name so admin-gated operations are visibly
        distinguishable from ordinary authenticated ones in this document.
    adminSecret:
      type: apiKey
      in: header
      name: x-admin-secret
      description: >-
        Shared operator secret checked against MANUAL_ADMIN_SECRET. Used by the
        job-scheduler admin routes, which are reachable without a user session.
    webhookSignature:
      type: apiKey
      in: header
      name: X-Webhook-Signature
      description: >-
        Provider-specific HMAC signature header verified server-side instead of a bearer
        token (e.g. x-paystack-signature for Paystack, verif-hash for Flutterwave). The
        header name varies by payment rail; see the payments webhook handler.

tags:
  - name: Health
    description: Health check operations
  - name: Soroban
    description: Soroban blockchain configuration
  - name: Auth
    description: Email/OTP authentication and sessions
  - name: Payments
    description: Payment confirmation and on-chain USDC receipt recording
  - name: Risk
    description: User risk state (frozen status)
  - name: Whistleblower
    description: Whistleblower listing operations
  - name: Deals
    description: Deal management and repayment schedule operations
  - name: Admin
    description: Administrative operations including reward payouts
  - name: Staking
    description: Staking operations (stake, unstake, claim rewards)
  - name: Support
    description: Public support/contact message intake
  - name: Governance
    description: Stake-weighted parameter governance proposals and voting (contracts/governance)