openapi.yaml

openapi: 3.0.3
info:
  title: RemitWise Frontend API (v1)
  version: 1.0.0
  description: |
    This OpenAPI document describes the current v1 API surface for RemitWise.

    Versioning: This repo uses URL-prefix versioning (e.g. /api/v1/...). The existing
    API is considered v1. To avoid breaking existing clients, the Next.js app
    rewrites `/api/*` to `/api/v1/*`.

    Deprecation policy: When a new major version is released (for example v2),
    older major versions will be supported for a minimum of 6 months before
    removal. Security patches and critical bug fixes will be backported during
    the deprecation window. Migration guides should be provided for clients.
servers:
  - url: /api/v1
    description: v1 base path (local/dev)
  - url: /api
    description: legacy base path (rewrites to v1)
paths:
  /anchor/deposit:
    post:
      summary: Start anchor deposit flow
      description: |
        Protected route. Starts a fiat -> USDC flow against the configured anchor.
        Returns a URL and/or flow steps. Returns 501 when anchor is not configured.
      responses:
        '200':
          description: Success
  /health:
    get:
      summary: Health check
      description: Returns system status and connectivity for RPC, DB, and optional anchor.
      responses:
        '200':
          description: All critical dependencies are healthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '503':
          description: One or more critical dependencies are unhealthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
  /remittance/quote:
    get:
      summary: Get Remittance Quote
      tags:
        - Remittance
      parameters:
        - in: query
          name: amount
          schema:
            type: number
          required: true
          description: Amount to send (> 0)
          example: 100.5
        - in: query
          name: currency
          schema:
            type: string
          required: true
          description: 3-letter ISO code
          example: USD
        - in: query
          name: toCurrency
          schema:
            type: string
          required: true
          description: 3-letter ISO code
          example: PHP
      responses:
        '200':
          description: Quote successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemittanceQuoteResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /remittance/build:
    post:
      summary: Build Remittance Transaction
      tags:
        - Remittance
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildRemittanceRequest'
      responses:
        '200':
          description: Transaction built
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildRemittanceResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/remittance/history:
    get:
      summary: Get Remittance History
      tags:
        - Remittance
      security:
        - cookieAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
            maximum: 200
          example: 20
        - in: query
          name: cursor
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
            enum:
              - completed
              - failed
              - pending
          example: completed
      responses:
        '200':
          description: History records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemittanceHistoryResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/remittance/status/{txHash}:
    get:
      summary: Get Remittance Status
      tags:
        - Remittance
      security:
        - cookieAuth: []
      parameters:
        - in: path
          name: txHash
          required: true
          schema:
            type: string
          example: d41d8cd98f00b204e9800998ecf8427e
      responses:
        '200':
          description: Transaction status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemittanceStatusResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /split/calculate:
    get:
      summary: Calculate Split Allocation
      tags:
        - Split
      security:
        - cookieAuth: []
      parameters:
        - in: query
          name: amount
          schema:
            type: number
          required: true
          description: Amount to split (> 0)
          example: 1000
      responses:
        '200':
          description: Calculated allocations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitCalculateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /split/initialize:
    post:
      summary: Initialize Split Configuration
      tags:
        - Split
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SplitPercentages'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitUpdateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /split/update:
    post:
      summary: Update Split Configuration
      tags:
        - Split
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SplitPercentages'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SplitUpdateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/bills:
    post:
      summary: Create a new Bill
      tags:
        - Bills
      security:
        - xUserHeader: []
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillRequest'
      responses:
        '200':
          description: XDR for transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XdrResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/bills/{id}/pay:
    post:
      summary: Pay a Bill
      tags:
        - Bills
      security:
        - xUserHeader: []
        - cookieAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          example: bill_123456
      responses:
        '200':
          description: XDR to pay bill
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XdrResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/bills/{id}/cancel:
    post:
      summary: Cancel a Bill
      tags:
        - Bills
      security:
        - xUserHeader: []
        - cookieAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          example: bill_123456
        - in: header
          name: x-owner-only
          schema:
            type: string
          required: false
        - in: header
          name: x-owner
          schema:
            type: string
          required: false
      responses:
        '200':
          description: XDR to cancel bill
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XdrResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/bills/due-soon:
    get:
      summary: Get bills due soon
      tags:
        - Bills
      security:
        - cookieAuth: []
        - xUserHeader: []
      responses:
        '200':
          description: List of bills due within 7 days
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillDueSoon'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/insurance:
    post:
      summary: Create Insurance Policy
      tags:
        - Insurance
      security:
        - xUserHeader: []
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInsuranceRequest'
      responses:
        '200':
          description: Returns XDR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XdrResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/insurance/{id}/pay:
    post:
      summary: Pay Insurance Premium
      tags:
        - Insurance
      security:
        - xUserHeader: []
        - cookieAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          example: ins_7890
      responses:
        '200':
          description: Returns XDR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XdrResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/insurance/{id}/deactivate:
    post:
      summary: Deactivate Insurance Policy
      tags:
        - Insurance
      security:
        - xUserHeader: []
        - cookieAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          example: ins_7890
        - in: header
          name: x-owner-only
          schema:
            type: string
          required: false
        - in: header
          name: x-owner
          schema:
            type: string
          required: false
      responses:
        '200':
          description: Returns XDR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XdrResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/admin/audit:
    get:
      summary: List audit events
      tags:
        - Admin
      security:
        - cookieAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 50
            maximum: 200
      responses:
        '200':
          description: Audit events
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/admin/users:
    get:
      summary: List recent users
      tags:
        - Admin
      security:
        - cookieAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/admin/webhooks/dlq:
    get:
      summary: List Webhook DLQ
      tags:
        - Admin
      security:
        - cookieAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
        - in: query
          name: source
          schema:
            type: string
          example: stripe
      responses:
        '200':
          description: DLQ events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDlqResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: remitwise-session
      description: Iron Session cookie for authenticated users
    xUserHeader:
      type: apiKey
      in: header
      name: x-user
      description: Stellar public key of the caller
  parameters:
    AcceptLanguageHeader:
      in: header
      name: Accept-Language
      required: false
      schema:
        type: string
        example: es
      description: 'Optional header to request localized responses. Supported languages: ''en'' (English), ''es'' (Spanish).'
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: |
            A translated error message based on the Accept-Language header.
            If the translation is missing or language is not supported, defaults to English.
            Example translations:
             - en: "Unauthorized: missing or invalid x-user header"
             - es: "No autorizado: falta o es inválido el encabezado x-user"
          example: 'Unauthorized: missing or invalid x-user header'
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - unhealthy
          example: ok
        database:
          type: string
          enum:
            - ok
            - error
          example: ok
        rpc:
          type: string
          enum:
            - ok
            - error
          example: ok
        anchor:
          type: string
          enum:
            - ok
            - error
            - skipped
          example: ok
    RemittanceQuoteResponse:
      type: object
      properties:
        sendAmount:
          type: number
          example: 100
        receiveAmount:
          type: number
          example: 5600.5
        fee:
          type: number
          example: 1.5
        rate:
          type: number
          example: 56
        expiry:
          type: string
          format: date-time
          example: '2023-10-12T07:20:50.52Z'
        source:
          type: string
          enum:
            - anchor
            - stellar
          example: anchor
    BuildRemittanceRequest:
      type: object
      required:
        - amount
        - recipientAddress
      properties:
        amount:
          type: number
          example: 250
        currency:
          type: string
          default: USDC
          example: USDC
        recipientAddress:
          type: string
          example: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
        memo:
          type: string
          maxLength: 28
          example: Monthly support
    BuildRemittanceResponse:
      type: object
      properties:
        xdr:
          type: string
          example: AAAAAgAAAAA...
        networkPassphrase:
          type: string
          example: Test SDF Network ; September 2015
        simulate:
          type: object
          properties:
            fee:
              type: string
              example: '100'
            success:
              type: boolean
              example: true
    RemittanceHistoryResponse:
      type: object
      properties:
        userAddress:
          type: string
          example: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
      additionalProperties: true
    RemittanceStatusResponse:
      type: object
      properties:
        hash:
          type: string
          example: d41d8cd98f00b204e9800998ecf8427e
        status:
          type: object
          additionalProperties: true
    SplitCalculateResponse:
      type: object
      properties:
        amounts:
          type: object
          additionalProperties: true
          example:
            savings: 300
            bills: 200
            insurance: 50
    SplitPercentages:
      type: object
      required:
        - spending
        - savings
        - bills
        - insurance
      properties:
        spending:
          type: number
          example: 50
        savings:
          type: number
          example: 25
        bills:
          type: number
          example: 20
        insurance:
          type: number
          example: 5
    SplitUpdateResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        xdr:
          type: string
          example: AAAAAgAAAAA...
        simulate:
          type: object
          additionalProperties: true
        message:
          type: string
          example: Successfully updated split percentages
    CreateBillRequest:
      type: object
      required:
        - name
        - amount
        - dueDate
      properties:
        name:
          type: string
          example: Electric Bill
        amount:
          type: number
          example: 120.5
        dueDate:
          type: string
          format: date-time
          example: '2023-10-15T00:00:00Z'
        recurring:
          type: boolean
          default: false
          example: true
        frequencyDays:
          type: number
          example: 30
    XdrResponse:
      type: object
      properties:
        xdr:
          type: string
          example: AAAAAgAAAAA...
    BillDueSoon:
      type: object
      required:
        - billId
        - name
        - amount
        - dueDate
      properties:
        billId:
          type: string
          example: bill_123456
        name:
          type: string
          example: Electric Bill
        amount:
          type: number
          example: 120.5
        dueDate:
          type: string
          format: date-time
          example: '2023-10-15T00:00:00Z'
    CreateInsuranceRequest:
      type: object
      required:
        - name
        - coverageType
        - monthlyPremium
        - coverageAmount
      properties:
        name:
          type: string
          example: Health Insurance
        coverageType:
          type: string
          example: Medical
        monthlyPremium:
          type: number
          example: 250
        coverageAmount:
          type: number
          example: 100000
    WebhookDlqResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            events:
              type: array
              items:
                type: object
            pagination:
              type: object
              properties:
                limit:
                  type: integer
                  example: 50
                offset:
                  type: integer
                  example: 0
                total:
                  type: integer
                  example: 5
                hasMore:
                  type: boolean
                  example: false
            stats:
              type: object
              example:
                pending: 0
                processing: 0
                processed: 100
                failed: 5
                dlq: 5
                total: 110