openapi: 3.1.0
info:
  title: Bitmessa API
  description: |
    # Bitmessa API Documentation
    
    Convert BTC and USDT to Naira programmatically with our comprehensive API.
    
    ## Features
    
    - Real-time exchange rates
    - Secure transactions
    - Comprehensive transaction history
    - Webhook notifications
    - Multiple authentication methods
    - Bitcoin RPC integration
    - Referral system
    - Admin management
  version: '2.0.0'
  contact:
    name: Bitmessa Support
    url: https://bitmessa.com/support
    email: support@bitmessa.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.bitmessa.com/v1
    description: Production server
  - url: https://sandbox.api.bitmessa.com/v1
    description: Sandbox server for testing
  - url: http://localhost:3000
    description: Local development server
security:
  - ApiKeyAuth: []
  - BearerAuth: []

tags:
  - name: Authentication
    description: Authentication and API key management
  - name: Rates
    description: Exchange rate endpoints
  - name: Payments
    description: Payment processing endpoints
  - name: Transactions
    description: Transaction management endpoints
  - name: Accounts
    description: Bank account management endpoints
  - name: Users
    description: User management endpoints
  - name: Referrals
    description: Referral system endpoints
  - name: Admin
    description: Administrative endpoints
  - name: Bitcoin
    description: Bitcoin RPC endpoints
  - name: Webhooks
    description: Webhook configuration endpoints
  - name: Health
    description: System health and monitoring endpoints
  - name: Analytics
    description: Analytics and reporting endpoints

paths:
  # ========================================
  # HEALTH & MONITORING ENDPOINTS
  # ========================================
  /health:
    get:
      tags:
        - Health
      summary: System health check
      description: Returns basic system health status
      operationId: getHealth
      responses:
        '200':
          description: System is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"
                  timestamp:
                    type: string
                    format: date-time
                  uptime:
                    type: number
                    description: System uptime in seconds
        '503':
          description: System is unhealthy

  /health/detailed:
    get:
      tags:
        - Health
      summary: Detailed health check
      description: Returns detailed system health information
      operationId: getDetailedHealth
      responses:
        '200':
          description: Detailed health information
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  database:
                    type: object
                    properties:
                      status:
                        type: string
                      responseTime:
                        type: number
                  bitcoin:
                    type: object
                    properties:
                      status:
                        type: string
                      connections:
                        type: number
                  redis:
                    type: object
                    properties:
                      status:
                        type: string
                      memory:
                        type: object

  /metrics:
    get:
      tags:
        - Health
      summary: Prometheus metrics
      description: Returns Prometheus-compatible metrics
      operationId: getMetrics
      responses:
        '200':
          description: Metrics data
          content:
            text/plain:
              schema:
                type: string

  # ========================================
  # AUTHENTICATION ENDPOINTS
  # ========================================
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Generate authentication token
      description: |
        Generates a new authentication token using API key and secret.
        The token is valid for 24 hours by default.
      operationId: generateToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - api_key
                - api_secret
              properties:
                api_key:
                  type: string
                  description: Your API key
                api_secret:
                  type: string
                  description: Your API secret
                expires_in:
                  type: integer
                  description: Token expiration time in seconds (default 86400 - 24 hours)
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT token for authentication
                  expires_at:
                    type: string
                    format: date-time
                    description: Token expiration timestamp
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # RATES ENDPOINTS
  # ========================================
  /get/rate:
    get:
      tags:
        - Rates
      summary: Get current exchange rates
      description: |
        Returns the current exchange rates for BTC and USDT to Naira.
        This is the main rate endpoint used by the platform.
      operationId: getCurrentRates
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      btc_rate:
                        type: number
                        description: BTC to Naira rate
                      usdt_rate:
                        type: number
                        description: USDT to Naira rate
                      timestamp:
                        type: string
                        format: date-time
                  message:
                    type: string

  /rates/current:
    get:
      tags:
        - Rates
      summary: Get current exchange rates (commercial API)
      description: |
        Returns the current exchange rates for BTC and USDT to Naira.
        Rates are updated every minute.
      operationId: getCurrentRatesCommercial
      parameters:
        - name: currency
          in: query
          description: Filter by specific currency (BTC or USDT)
          required: false
          schema:
            type: string
            enum: [BTC, USDT]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                    description: Timestamp of the rates
                  rates:
                    type: object
                    properties:
                      BTC:
                        type: object
                        properties:
                          buy:
                            type: number
                            format: float
                            description: Buy rate in Naira
                          sell:
                            type: number
                            format: float
                            description: Sell rate in Naira
                      USDT:
                        type: object
                        properties:
                          buy:
                            type: number
                            format: float
                            description: Buy rate in Naira
                          sell:
                            type: number
                            format: float
                            description: Sell rate in Naira
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # PAYMENT ENDPOINTS
  # ========================================
  /payment:
    post:
      tags:
        - Payments
      summary: Create a new payment
      description: |
        Creates a new payment request to convert BTC or USDT to Naira.
      operationId: createPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
              properties:
                amount:
                  type: number
                  description: Amount to convert
                currency:
                  type: string
                  enum: [BTC, USDT]
                  description: Source currency
                bank_account:
                  type: string
                  description: Bank account number
                bank_name:
                  type: string
                  description: Bank name
      responses:
        '201':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /payment/{id}:
    get:
      tags:
        - Payments
      summary: Get payment details
      description: |
        Returns details of a specific payment (authenticated access).
      operationId: getPayment
      parameters:
        - name: id
          in: path
          description: Payment ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /payment/search/{id}:
    get:
      tags:
        - Payments
      summary: Search payment (public)
      description: |
        Returns details of a specific payment (public access).
      operationId: searchPayment
      parameters:
        - name: id
          in: path
          description: Payment ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /payments:
    get:
      tags:
        - Payments
      summary: List user payments
      description: |
        Returns a list of payments for the authenticated user.
      operationId: listPayments
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: status
          in: query
          description: Filter by payment status
          required: false
          schema:
            type: string
            enum: [pending, completed, failed]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /payment/finalize/{id}:
    post:
      tags:
        - Payments
      summary: Finalize payment
      description: |
        Finalizes a payment with bank account details.
      operationId: finalizePayment
      parameters:
        - name: id
          in: path
          description: Payment ID
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - bank_account
                - bank_name
                - account_name
              properties:
                bank_account:
                  type: string
                  description: Bank account number
                bank_name:
                  type: string
                  description: Bank name
                account_name:
                  type: string
                  description: Account holder name
      responses:
        '200':
          description: Payment finalized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # ACCOUNT ENDPOINTS
  # ========================================
  /accounts:
    get:
      tags:
        - Accounts
      summary: List user bank accounts
      description: |
        Returns a list of bank accounts for the authenticated user.
      operationId: listAccounts
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccount'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /account/{id}:
    get:
      tags:
        - Accounts
      summary: Get account details
      description: |
        Returns details of a specific bank account.
      operationId: getAccount
      parameters:
        - name: id
          in: path
          description: Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /account/assign/{payment_id}:
    post:
      tags:
        - Accounts
      summary: Assign account to payment
      description: |
        Assigns a bank account to a specific payment.
      operationId: assignAccountToPayment
      parameters:
        - name: payment_id
          in: path
          description: Payment ID
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
              properties:
                account_id:
                  type: string
                  description: Account ID to assign
      responses:
        '200':
          description: Account assigned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /banks/get:
    get:
      tags:
        - Accounts
      summary: Get bank list
      description: |
        Returns a list of supported Nigerian banks.
      operationId: getBankList
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bank'

  /account-resolve:
    post:
      tags:
        - Accounts
      summary: Resolve bank account
      description: |
        Resolves bank account details using account number and bank code.
      operationId: resolveAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_number
                - bank_code
              properties:
                account_number:
                  type: string
                  description: Bank account number
                bank_code:
                  type: string
                  description: Bank code
      responses:
        '200':
          description: Account resolved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      account_name:
                        type: string
                      account_number:
                        type: string
                      bank_name:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # TRANSACTION ENDPOINTS
  # ========================================
  /transactions:
    get:
      tags:
        - Transactions
      summary: List user transactions
      description: |
        Returns a list of transactions for the authenticated user.
      operationId: listTransactions
      parameters:
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: status
          in: query
          description: Filter by transaction status
          required: false
          schema:
            type: string
            enum: [pending, completed, failed]
        - name: currency
          in: query
          description: Filter by currency
          required: false
          schema:
            type: string
            enum: [BTC, USDT]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /transaction/{id}:
    get:
      tags:
        - Transactions
      summary: Get transaction details
      description: |
        Returns details of a specific transaction.
      operationId: getTransaction
      parameters:
        - name: id
          in: path
          description: Transaction ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # REFERRAL SYSTEM ENDPOINTS
  # ========================================
  /referral/auth/request-otp:
    post:
      tags:
        - Referrals
      summary: Request OTP for referral system
      description: |
        Requests an OTP for referral system authentication.
      operationId: requestReferralOTP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phone_number
              properties:
                phone_number:
                  type: string
                  description: Phone number for OTP
      responses:
        '200':
          description: OTP sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /referral/auth/verify-otp:
    post:
      tags:
        - Referrals
      summary: Verify OTP for referral system
      description: |
        Verifies OTP and logs in to referral system.
      operationId: verifyReferralOTP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phone_number
                - otp
              properties:
                phone_number:
                  type: string
                  description: Phone number
                otp:
                  type: string
                  description: OTP code
      responses:
        '200':
          description: OTP verified successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  token:
                    type: string
                  user:
                    $ref: '#/components/schemas/ReferralUser'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /referral/user/profile:
    get:
      tags:
        - Referrals
      summary: Get referral user profile
      description: |
        Returns the profile of the authenticated referral user.
      operationId: getReferralUserProfile
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralUser'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /referral/referrals/stats:
    get:
      tags:
        - Referrals
      summary: Get referral statistics
      description: |
        Returns referral statistics for the authenticated user.
      operationId: getReferralStats
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_referrals:
                    type: number
                  active_referrals:
                    type: number
                  total_earnings:
                    type: number
                  pending_earnings:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # ADMIN ENDPOINTS
  # ========================================
  /admin/get/rate:
    get:
      tags:
        - Admin
      summary: Get admin settings
      description: |
        Returns current admin settings including exchange rates.
      operationId: getAdminSettings
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  btc_rate:
                    type: number
                  usdt_rate:
                    type: number
                  platform_active:
                    type: boolean
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /admin/update/rate/{rate}:
    post:
      tags:
        - Admin
      summary: Update exchange rate
      description: |
        Updates the exchange rate for BTC to Naira.
      operationId: updateExchangeRate
      parameters:
        - name: rate
          in: path
          description: New exchange rate
          required: true
          schema:
            type: number
      responses:
        '200':
          description: Rate updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /stats/today:
    get:
      tags:
        - Admin
      summary: Get today's statistics
      description: |
        Returns today's platform statistics.
      operationId: getTodayStats
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_transactions:
                    type: number
                  total_volume:
                    type: number
                  total_users:
                    type: number
                  success_rate:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # BITCOIN RPC ENDPOINTS
  # ========================================
  /getnewaddress:
    post:
      tags:
        - Bitcoin
      summary: Generate new Bitcoin address
      description: |
        Generates a new Bitcoin address for receiving payments.
      operationId: generateBitcoinAddress
      responses:
        '200':
          description: Address generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  address:
                    type: string
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /getbalance:
    get:
      tags:
        - Bitcoin
      summary: Get Bitcoin balance
      description: |
        Returns the current Bitcoin balance.
      operationId: getBitcoinBalance
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
                  confirmed:
                    type: number
                  unconfirmed:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /listtransactions:
    get:
      tags:
        - Bitcoin
      summary: List Bitcoin transactions
      description: |
        Returns a list of Bitcoin transactions.
      operationId: listBitcoinTransactions
      parameters:
        - name: count
          in: query
          description: Number of transactions to return
          required: false
          schema:
            type: integer
            default: 10
        - name: skip
          in: query
          description: Number of transactions to skip
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BitcoinTransaction'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /sendtoaddress:
    post:
      tags:
        - Bitcoin
      summary: Send Bitcoin to address
      description: |
        Sends Bitcoin to a specified address.
      operationId: sendBitcoin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address
                - amount
              properties:
                address:
                  type: string
                  description: Bitcoin address
                amount:
                  type: number
                  description: Amount to send
      responses:
        '200':
          description: Transaction sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  txid:
                    type: string
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /getblockchaininfo:
    get:
      tags:
        - Bitcoin
      summary: Get blockchain information
      description: |
        Returns information about the Bitcoin blockchain.
      operationId: getBlockchainInfo
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  chain:
                    type: string
                  blocks:
                    type: number
                  headers:
                    type: number
                  bestblockhash:
                    type: string
                  difficulty:
                    type: number
                  verificationprogress:
                    type: number
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /estimatesmartfee:
    post:
      tags:
        - Bitcoin
      summary: Estimate smart fee
      description: |
        Estimates the smart fee for a transaction.
      operationId: estimateSmartFee
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - conf_target
              properties:
                conf_target:
                  type: integer
                  description: Confirmation target
                estimate_mode:
                  type: string
                  enum: [UNSET, ECONOMICAL, CONSERVATIVE]
                  default: CONSERVATIVE
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  feerate:
                    type: number
                  blocks:
                    type: number
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  # ========================================
  # WEBHOOK ENDPOINTS
  # ========================================
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Register a webhook
      description: |
        Registers a new webhook to receive notifications for specific events.
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '201':
          description: Webhook registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
          description: Payment ID
        amount:
          type: number
          description: Payment amount
        currency:
          type: string
          enum: [BTC, USDT]
          description: Source currency
        status:
          type: string
          enum: [pending, completed, failed]
          description: Payment status
        bank_account:
          type: string
          description: Bank account number
        bank_name:
          type: string
          description: Bank name
        account_name:
          type: string
          description: Account holder name
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Transaction:
      type: object
      properties:
        id:
          type: string
          description: Transaction ID
        payment_id:
          type: string
          description: Associated payment ID
        type:
          type: string
          enum: [deposit, withdrawal]
          description: Transaction type
        amount:
          type: number
          description: Transaction amount
        currency:
          type: string
          enum: [BTC, USDT, NGN]
          description: Transaction currency
        status:
          type: string
          enum: [pending, completed, failed]
          description: Transaction status
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    BankAccount:
      type: object
      properties:
        id:
          type: string
          description: Account ID
        account_number:
          type: string
          description: Bank account number
        account_name:
          type: string
          description: Account holder name
        bank_name:
          type: string
          description: Bank name
        bank_code:
          type: string
          description: Bank code
        is_active:
          type: boolean
          description: Account status
        created_at:
          type: string
          format: date-time

    Bank:
      type: object
      properties:
        code:
          type: string
          description: Bank code
        name:
          type: string
          description: Bank name
        longcode:
          type: string
          description: Long bank code
        active:
          type: boolean
          description: Bank status
        country:
          type: string
          description: Country code
        currency:
          type: string
          description: Currency code

    ReferralUser:
      type: object
      properties:
        id:
          type: string
          description: User ID
        phone_number:
          type: string
          description: Phone number
        username:
          type: string
          description: Username
        total_referrals:
          type: number
          description: Total referrals
        total_earnings:
          type: number
          description: Total earnings
        created_at:
          type: string
          format: date-time

    BitcoinTransaction:
      type: object
      properties:
        address:
          type: string
          description: Bitcoin address
        category:
          type: string
          enum: [receive, send, immature, generate, orphan]
          description: Transaction category
        amount:
          type: number
          description: Transaction amount
        confirmations:
          type: integer
          description: Number of confirmations
        blockhash:
          type: string
          description: Block hash
        blockindex:
          type: integer
          description: Block index
        blocktime:
          type: integer
          description: Block time
        txid:
          type: string
          description: Transaction ID
        time:
          type: integer
          description: Transaction time
        timereceived:
          type: integer
          description: Time received

    WebhookRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          description: Webhook URL
        events:
          type: array
          items:
            type: string
            enum: [payment.completed, payment.failed, transaction.completed]
          description: Events to subscribe to
        secret:
          type: string
          description: Webhook secret for signature verification

    Webhook:
      type: object
      properties:
        id:
          type: string
          description: Webhook ID
        url:
          type: string
          format: uri
          description: Webhook URL
        events:
          type: array
          items:
            type: string
          description: Subscribed events
        is_active:
          type: boolean
          description: Webhook status
        created_at:
          type: string
          format: date-time

    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        limit:
          type: integer
          description: Items per page
        total:
          type: integer
          description: Total number of items
        pages:
          type: integer
          description: Total number of pages

  responses:
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "BAD_REQUEST"
                  message:
                    type: string
                    example: "Invalid request parameters"
                  details:
                    type: object

    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "UNAUTHORIZED"
                  message:
                    type: string
                    example: "Authentication required"

    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "FORBIDDEN"
                  message:
                    type: string
                    example: "Insufficient permissions"

    NotFoundError:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "NOT_FOUND"
                  message:
                    type: string
                    example: "Resource not found"

    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "RATE_LIMIT_EXCEEDED"
                  message:
                    type: string
                    example: "Rate limit exceeded"
                  retry_after:
                    type: integer
                    description: Seconds to wait before retrying
