openapi: 3.0.3
info:
  title: Seal Backend API
  version: 1.0.0
  description: API reference for Seal Backend. This spec is a minimal, editable starting point — expand request/response schemas as needed.
servers:
  - url: /
security:
  - bearerAuth: []
tags:
  - name: Auth
    description: Authentication endpoints (register, login, logout, tokens)
  - name: Users
    description: User profile and admin user management
  - name: Wallet
    description: Wallet and balance operations
  - name: Transactions
    description: Transaction listing and lookup
  - name: Transfer
    description: Internal, external and cross-border transfers
  - name: Payments
    description: Payments initialization, verification and webhooks
  - name: KYC
    description: KYC submissions and admin actions
  - name: FX
    description: Foreign exchange rates and conversions
  - name: Webhooks
    description: Third-party webhook handlers
paths:
  /health:
    get:
      tags: [Auth]
      summary: Health check
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

  /api/auth/register:
    post:
      tags: [Auth]
      summary: Register a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Register"
      responses:
        "201":
          description: Created

  /api/auth/login:
    post:
      tags: [Auth]
      summary: Login and receive token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Login"
      responses:
        "200":
          description: Authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string

  /api/auth/logout:
    post:
      tags: [Auth]
      summary: Logout (requires auth)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Logged out

  /api/auth/refresh-token:
    post:
      tags: [Auth]
      summary: Refresh token (requires auth)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Token refreshed

  /api/users/me:
    get:
      tags: [Users]
      summary: Get current user
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current user

  /api/users:
    get:
      tags: [Users]
      summary: List users (admin)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
    post:
      summary: Create user (not implemented - example)

  /api/users/update:
    put:
      tags: [Users]
      summary: Update current user
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdate"
      responses:
        "200":
          description: Updated

  /api/users/{id}:
    get:
      tags: [Users]
      summary: Get user by id (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User
    delete:
      summary: Delete user (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted

  /api/wallet:
    get:
      tags: [Wallet]
      summary: Get wallet for current user
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Wallet object

  /api/wallet/balance:
    get:
      tags: [Wallet]
      summary: Get wallet balance
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Balance

  /api/wallet/freeze:
    post:
      tags: [Wallet]
      summary: Freeze funds
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
      responses:
        "200":
          description: Funds frozen

  /api/wallet/unfreeze:
    post:
      tags: [Wallet]
      summary: Unfreeze funds
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
      responses:
        "200":
          description: Funds unfrozen

  /api/transactions:
    get:
      tags: [Transactions]
      summary: List transactions
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Transactions list

  /api/transactions/reference/{ref}:
    get:
      tags: [Transactions]
      summary: Get transaction by reference
      security:
        - bearerAuth: []
      parameters:
        - name: ref
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction

  /api/transactions/{id}:
    get:
      tags: [Transactions]
      summary: Get transaction by id
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Transaction

  /api/transfer/internal:
    post:
      tags: [Transfer]
      summary: Internal transfer
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Transfer"
      responses:
        "200":
          description: Transfer initiated

  /api/transfer/cross-border:
    post:
      tags: [Transfer]
      summary: Cross-border transfer
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Transfer"
      responses:
        "200":
          description: Transfer initiated

  /api/transfer/external:
    post:
      tags: [Transfer]
      summary: External transfer
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Transfer"
      responses:
        "200":
          description: Transfer initiated

  /api/payments/initialize:
    post:
      tags: [Payments]
      summary: Initialize payment
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Payment initialized

  /api/payments/verify/{reference}:
    get:
      tags: [Payments]
      summary: Verify payment by reference
      security:
        - bearerAuth: []
      parameters:
        - name: reference
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Payment verified

  /api/payments/webhook:
    post:
      tags: [Payments, Webhooks]
      summary: Payment gateway webhook (public)
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Webhook handled

  /api/kyc/submit:
    post:
      tags: [KYC]
      summary: Submit KYC
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: KYC submitted

  /api/kyc/status:
    get:
      tags: [KYC]
      summary: Get KYC status
      security:
        - bearerAuth: []
      responses:
        "200":
          description: KYC status

  /api/kyc/admin/all:
    get:
      tags: [KYC]
      summary: Get all KYC records (admin)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Array of KYC records

  /api/kyc/verify/{userId}:
    patch:
      tags: [KYC]
      summary: Verify KYC for a user (admin)
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: KYC verified

  /api/fx/rates:
    get:
      tags: [FX]
      summary: Get FX rates
      responses:
        "200":
          description: FX rates

  /api/fx/convert:
    post:
      tags: [FX]
      summary: Convert currency
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Conversion result

  /api/fx/swap:
    post:
      tags: [FX]
      summary: Swap currency
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Swap completed

  /api/webhooks/paystack:
    post:
      tags: [Webhooks]
      summary: Paystack webhook
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Handled

  /api/webhooks/hub2:
    post:
      tags: [Webhooks]
      summary: Hub2 webhook
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Handled

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Register:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        password:
          type: string
    Login:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
    UserUpdate:
      type: object
      properties:
        name:
          type: string
    Transfer:
      type: object
      properties:
        toAccount:
          type: string
        amount:
          type: number
        currency:
          type: string