openapi: 3.1.0
info:
  title: Quub Exchange - Treasury & Reconciliation API
  version: "2.0.0"
  license:
    name: Proprietary
    url: https://quub.exchange/license
  description: |
    The Treasury Service manages escrow accounts, payments, distributions,
    ledger entries, and reconciliation between blockchain and banking systems.

    Includes continuous proof-of-reserves streaming for real-time audit visibility.

servers:
  - url: https://api.sandbox.quub.exchange/v1
    description: Sandbox environment
    x-environment: sandbox
  - url: https://api.quub.exchange/v1
    description: Production REST API
    x-environment: production
  - url: wss://stream.quub.exchange/v1
    description: WebSocket Streaming API for live reconciliation updates
    x-protocol: wss
    x-environment: production

tags:
  - name: treasury
    description: Treasury and settlement operations
  - name: reconciliation
    description: Reconciliation and proof-of-reserve streams

paths:
  # --------------------------------------------------------------------------
  # ESCROW ACCOUNTS
  # --------------------------------------------------------------------------
  /orgs/{orgId}/escrows:
    get:
      tags: [treasury]
      summary: List escrow accounts
      operationId: listEscrows
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/pagination.yaml#/components/parameters/cursor"
        - $ref: "./common/pagination.yaml#/components/parameters/limit"
        - $ref: "./common/components.yaml#/components/parameters/projectIdQuery"
      responses:
        "200":
          description: List of escrow accounts
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/EscrowAccount"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }
    post:
      tags: [treasury]
      summary: Open escrow account
      operationId: createEscrow
      security:
        - oauth2: [write:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/components.yaml#/components/parameters/idempotencyKey"
        - $ref: "./common/components.yaml#/components/parameters/signature"
        - $ref: "./common/components.yaml#/components/parameters/timestamp"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [currency, projectId]
              properties:
                currency:
                  type: string
                  pattern: "^[A-Z]{3}$"
                  example: "USD"
                projectId:
                  $ref: "./common/primitives.yaml#/components/schemas/ProjectId"
                bankRef:
                  type: string
                  example: "CITI-ESCROW-12345"
      responses:
        "201":
          description: Escrow account created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EscrowAccount"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "409":
          { $ref: "./common/responses.yaml#/components/responses/Conflict" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  /orgs/{orgId}/escrows/{escrowId}:
    get:
      tags: [treasury]
      summary: Get escrow account
      operationId: getEscrow
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - name: escrowId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Escrow account details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EscrowAccount"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  # --------------------------------------------------------------------------
  # PAYMENTS
  # --------------------------------------------------------------------------
  /orgs/{orgId}/payments:
    get:
      tags: [treasury]
      summary: List payments
      operationId: listPayments
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/pagination.yaml#/components/parameters/cursor"
        - $ref: "./common/pagination.yaml#/components/parameters/limit"
        - name: direction
          in: query
          schema:
            $ref: "./common/primitives.yaml#/components/schemas/PayDirection"
        - name: status
          in: query
          schema:
            $ref: "./common/primitives.yaml#/components/schemas/PayStatus"
      responses:
        "200":
          description: List of payments
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "./common/domain-models.yaml#/components/schemas/Payment"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }
    post:
      tags: [treasury]
      summary: Create payment
      operationId: createPayment
      security:
        - oauth2: [write:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/components.yaml#/components/parameters/idempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [direction, method, amount, currency]
              properties:
                direction:
                  $ref: "./common/primitives.yaml#/components/schemas/PayDirection"
                method:
                  $ref: "./common/primitives.yaml#/components/schemas/PayMethod"
                amount: { type: number, format: double }
                currency: { type: string, example: "USD" }
                from: { type: string }
                to: { type: string }
                valueDate: { type: string, format: date }
                refs: { type: object }
      responses:
        "201":
          description: Payment created
          content:
            application/json:
              schema:
                $ref: "./common/domain-models.yaml#/components/schemas/Payment"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "409":
          { $ref: "./common/responses.yaml#/components/responses/Conflict" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  # --------------------------------------------------------------------------
  # DISTRIBUTIONS
  # --------------------------------------------------------------------------
  /orgs/{orgId}/distributions:
    get:
      tags: [treasury]
      summary: List distributions
      operationId: listDistributions
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/pagination.yaml#/components/parameters/cursor"
        - $ref: "./common/pagination.yaml#/components/parameters/limit"
      responses:
        "200":
          description: List of distributions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Distribution"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }
    post:
      tags: [treasury]
      summary: Create distribution batch
      operationId: createDistribution
      security:
        - oauth2: [write:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/components.yaml#/components/parameters/idempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tokenClassId, period, net]
              properties:
                projectId:
                  $ref: "./common/primitives.yaml#/components/schemas/ProjectId"
                tokenClassId:
                  $ref: "./common/primitives.yaml#/components/schemas/TokenClassId"
                period: { type: string }
                gross: { type: number }
                fees: { type: number }
                taxWithheld: { type: number }
                net: { type: number }
      responses:
        "201":
          description: Distribution created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Distribution"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "409":
          { $ref: "./common/responses.yaml#/components/responses/Conflict" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  # --------------------------------------------------------------------------
  # LEDGER
  # --------------------------------------------------------------------------
  /orgs/{orgId}/ledger:
    get:
      tags: [treasury]
      summary: Query ledger entries
      operationId: queryLedger
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/pagination.yaml#/components/parameters/cursor"
        - $ref: "./common/pagination.yaml#/components/parameters/limit"
        - name: accountId
          in: query
          schema:
            $ref: "./common/primitives.yaml#/components/schemas/AccountId"
      responses:
        "200":
          description: Ledger entries
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/LedgerEntry"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  # --------------------------------------------------------------------------
  # RECONCILIATION
  # --------------------------------------------------------------------------
  /orgs/{orgId}/reconciliation:
    get:
      tags: [reconciliation]
      summary: List reconciliation reports
      operationId: listReconciliations
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - $ref: "./common/pagination.yaml#/components/parameters/cursor"
        - $ref: "./common/components.yaml#/components/parameters/fromDate"
        - $ref: "./common/components.yaml#/components/parameters/toDate"
        - $ref: ./common/pagination.yaml#/components/parameters/limit
      responses:
        "200":
          description: List of daily reconciliation reports
          content:
            application/json:
              schema:
                allOf:
                  - $ref: ./common/pagination.yaml#/components/schemas/PageResponse
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ReconciliationReport"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }
    post:
      tags: [reconciliation]
      summary: Trigger daily reconciliation
      operationId: createReconciliation
      security:
        - oauth2: [write:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                date: { type: string, format: date }
      responses:
        "201":
          description: Reconciliation initiated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationReport"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "409":
          { $ref: "./common/responses.yaml#/components/responses/Conflict" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  /orgs/{orgId}/reconciliation/{reportId}:
    get:
      tags: [reconciliation]
      summary: Get reconciliation report
      operationId: getReconciliation
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - name: reportId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Detailed reconciliation report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationReport"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  /orgs/{orgId}/reconciliation/{reportId}/attest:
    post:
      tags: [reconciliation]
      summary: Upload attestation or proof file
      operationId: attestReconciliation
      security:
        - oauth2: [write:treasury]
        - apiKey: []
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
        - name: reportId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                type:
                  type: string
                  enum: [bank_statement, onchain_proof, audit_certificate]
      responses:
        "200":
          description: Attestation received
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationReport"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "409":
          { $ref: "./common/responses.yaml#/components/responses/Conflict" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

  /orgs/{orgId}/reconciliation/live-status:
    get:
      tags: [reconciliation]
      summary: Live reconciliation stream (WebSocket)
      operationId: liveReconciliationStatus
      description: |
        Establishes a WebSocket connection to stream real-time reconciliation deltas.

        - Pushes balance changes, proof-hash updates, and discrepancy alerts.
        - Enables external auditors and custodians to maintain continuous proof-of-reserves.
        - Messages are HMAC-signed using the client's API key secret.
      security:
        - oauth2: [read:treasury]
        - apiKey: []
      x-protocol: wss
      parameters:
        - $ref: "./common/components.yaml#/components/parameters/orgId"
        - $ref: "./common/components.yaml#/components/parameters/orgIdHeader"
      responses:
        "200":
          description: WebSocket connection info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationStreamMessage"
        "400":
          { $ref: "./common/responses.yaml#/components/responses/BadRequest" }
        "401":
          { $ref: "./common/responses.yaml#/components/responses/Unauthorized" }
        "403":
          { $ref: "./common/responses.yaml#/components/responses/Forbidden" }
        "422":
          {
            $ref: "./common/responses.yaml#/components/responses/ValidationError",
          }
        "429":
          {
            $ref: "./common/responses.yaml#/components/responses/TooManyRequests",
          }
        "404":
          { $ref: "./common/responses.yaml#/components/responses/NotFound" }
        "500":
          {
            $ref: "./common/responses.yaml#/components/responses/InternalServerError",
          }

# --------------------------------------------------------------------------
# COMPONENTS
# --------------------------------------------------------------------------
components:
  schemas:
    ReconciliationReport:
      type: object
      description: |
        Represents reconciliation between escrow balances, ledger, and external confirmations.
      properties:
        id: { type: string, example: "recon_2025_10_21" }
        date: { type: string, format: date }
        status:
          type: string
          enum: [PENDING, MATCHED, MISMATCHED, VERIFIED]
        hashRoot:
          type: string
          description: Merkle root hash of all entries
        discrepancies:
          type: array
          items:
            type: object
            properties:
              accountRef: { type: string }
              ledgerBalance: { type: number }
              bankBalance: { type: number }
              variance: { type: number }
        proofs:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum: [bank_statement, onchain_proof, audit_certificate]
              fileUrl: { type: string, format: uri }
              uploadedAt: { type: string, format: date-time }
              verifiedBy: { type: string }
        generatedAt: { type: string, format: date-time }
        verifiedAt:
          oneOf:
            - type: string
              format: date-time
            - type: "null"

    ReconciliationStreamMessage:
      type: object
      description: Real-time event broadcast over the WebSocket stream.
      properties:
        sequence: { type: integer, example: 15823 }
        timestamp: { type: string, format: date-time }
        type:
          type: string
          enum: [BALANCE_UPDATE, HASH_UPDATE, DISCREPANCY_ALERT, HEARTBEAT]
        orgId: { type: string, format: uuid }
        data:
          oneOf:
            - type: object
              description: Balance delta
              properties:
                accountRef: { type: string }
                oldBalance: { type: number }
                newBalance: { type: number }
            - type: object
              description: Merkle hash update
              properties:
                oldRoot: { type: string }
                newRoot: { type: string }
            - type: object
              description: Discrepancy alert
              properties:
                accountRef: { type: string }
                ledgerBalance: { type: number }
                bankBalance: { type: number }
                variance: { type: number }
            - type: object
              description: Heartbeat
              properties:
                message: { type: string, example: "alive" }
        signature:
          type: string
          example: "HMAC_SHA256(...)"

    Distribution:
      type: object
      description: Token holder distribution (dividend, interest, etc.)
      required: [id, tokenClassId, type, totalAmount, currency]
      properties:
        id:
          type: string
          format: uuid
        tokenClassId:
          $ref: "./common/primitives.yaml#/components/schemas/TokenClassId"
        projectId:
          $ref: "./common/primitives.yaml#/components/schemas/ProjectId"
        type:
          type: string
          enum: [DIVIDEND, INTEREST, RETURN_OF_CAPITAL, REDEMPTION]
        totalAmount:
          type: number
          format: double
        currency:
          type: string
          example: "USD"
        perShareAmount:
          type: number
          format: double
        recordDate:
          type: string
          format: date
        paymentDate:
          type: string
          format: date
        status:
          type: string
          enum: [ANNOUNCED, PROCESSING, COMPLETED, CANCELLED]
        recipientCount:
          type: integer
        paidAmount:
          type: number
          format: double
          default: 0

    EscrowAccount:
      type: object
      description: Escrow account for project funds
      required: [id, projectId, currency, balance]
      properties:
        id:
          type: string
          format: uuid
        projectId:
          $ref: "./common/primitives.yaml#/components/schemas/ProjectId"
        orgId:
          $ref: "./common/primitives.yaml#/components/schemas/OrgId"
        currency:
          type: string
          example: "USD"
        balance:
          type: number
          format: double
        holdBalance:
          type: number
          format: double
          description: Funds on hold
        status:
          type: string
          enum: [ACTIVE, FROZEN, CLOSED]
        bankAccount:
          type: object
          properties:
            bankName: { type: string }
            accountNumber: { type: string }
            routingNumber: { type: string }
            swift: { type: string }
        createdAt:
          type: string
          format: date-time

    LedgerEntry:
      type: object
      description: General ledger entry for audit trail
      required: [id, type, amount, currency, accountRef]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum: [DEBIT, CREDIT]
        accountRef:
          type: string
          description: Reference to account/wallet/escrow
        amount:
          type: number
          format: double
        currency:
          type: string
        description:
          type: string
        relatedEntityType:
          type: string
          enum: [PAYMENT, DISTRIBUTION, TRADE, SUBSCRIPTION]
        relatedEntityId:
          type: string
        timestamp:
          type: string
          format: date-time
        orgId:
          $ref: "./common/primitives.yaml#/components/schemas/OrgId"
        accountId:
          $ref: "./common/primitives.yaml#/components/schemas/AccountId"

  securitySchemes:
    bearerAuth:
      $ref: "./common/components.yaml#/components/securitySchemes/bearerAuth"
    oauth2:
      $ref: "./common/components.yaml#/components/securitySchemes/oauth2"
    apiKey:
      $ref: "./common/components.yaml#/components/securitySchemes/apiKey"