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)
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.
  /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'
components:
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum: [ok, unhealthy]
        database:
          type: string
          enum: [ok, error]
        rpc:
          type: string
          enum: [ok, error]
        anchor:
          type: string
          enum: [ok, error, skipped]
  - url: /api
    description: legacy base path (rewrites to v1)

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"

paths:
  /auth/login:
    post:
      summary: Login via Wallet Signature
      description: Authenticate user by verifying an Ed25519 signature of a previously issued nonce.
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency]
              properties:
                amount:
                  oneOf:
                    - type: number
                    - type: string
                currency:
                  type: string
                destination:
                  type: string
      responses:
        "200":
          description: Flow created
        "401":
          description: Unauthorized
        "501":
          description: Anchor not configured
  /anchor/withdraw:
    post:
      summary: Start anchor withdraw flow
      description: >
        Protected route. Starts a USDC -> fiat flow against the configured anchor.
        Returns a URL and/or flow steps. Returns 501 when anchor is not configured.
              required:
                - address
                - signature
              properties:
                address:
                  type: string
                  description: Stellar public key
                signature:
                  type: string
                  description: Base64 encoded signature
      responses:
        '200':
          description: Successfully authenticated, returns a session cookie.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  address:
                    type: string
        '400':
          description: Missing address or signature
        '401':
          description: Invalid signature or expired nonce
        '500':
          description: Server error
          
  /split:
    get:
      summary: Get Split Configuration
      description: Fetch the current user's allocation percentages.
      security:
        - cookieAuth: []
      tags:
        - Split
      responses:
        '200':
          description: Returns configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  percentages:
                    type: object
                    properties:
                      savings:
                        type: number
                      bills:
                        type: number
                      insurance:
                        type: number
                      family:
                        type: number
        '404':
          description: Split config not found
    post:
      summary: Update Split Configuration
      security:
        - cookieAuth: []
      tags:
        - Split
      responses:
        '200':
          description: Configuration updated
          
  /split/calculate:
    get:
      summary: Calculate Split Allocation
      description: Given an amount, calculate the allocation based on the user's split settings.
      security:
        - cookieAuth: []
      tags:
        - Split
      parameters:
        - in: query
          name: amount
          schema:
            type: number
          required: true
          description: The gross amount to split
      responses:
        '200':
          description: Calculated amounts
          
  /remittance/allocate:
    post:
      summary: Allocate Remittance
      description: Record a remittance and allocate the funds accordingly.
      security:
        - cookieAuth: []
      tags:
        - Remittance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, currency]
              properties:
                amount:
                  oneOf:
                    - type: number
                    - type: string
                currency:
                  type: string
                destinationAccount:
                  type: string
      responses:
        "200":
          description: Flow created
        "401":
          description: Unauthorized
        "501":
          description: Anchor not configured
  /admin/cache/clear:
    post:
      summary: Clear in-memory caches
      description: Admin-only route protected by X-Admin-Key or admin cookie.
      responses:
        "200":
          description: Caches cleared
        "401":
          description: Unauthorized
  /admin/users:
    get:
      summary: List recent users
      description: Admin-only route protected by X-Admin-Key or admin cookie.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        "200":
          description: User list
        "401":
          description: Unauthorized
  /admin/audit:
    get:
      summary: List audit events
      description: Admin-only route protected by X-Admin-Key or admin cookie.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        "200":
          description: Audit events
        "401":
          description: Unauthorized
components: {}
              required:
                - txHash
                - amount
              properties:
                txHash:
                  type: string
                amount:
                  type: number
      responses:
        '200':
          description: Allocation success
        
  /bills:
    get:
      summary: Get Legacy Bills
      security:
        - cookieAuth: []
      tags:
        - Bills
      responses:
        '200':
          description: List of bills
    post:
      summary: Create or Pay Legacy Bill
      security:
        - cookieAuth: []
      tags:
        - Bills
      responses:
        '200':
          description: Success
          
  /v1/bills:
    post:
      summary: Create a new Bill
      security:
        - xUserHeader: []
      tags:
        - Bills (v1)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - amount
                - dueDate
              properties:
                name:
                  type: string
                amount:
                  type: number
                dueDate:
                  type: string
                  format: date-time
                recurring:
                  type: boolean
                frequencyDays:
                  type: number
      responses:
        '200':
          description: Returns XDR for the transaction
        '400':
          description: Invalid input parameters
          
  /v1/bills/{id}/cancel:
    post:
      summary: Cancel a Bill
      security:
        - xUserHeader: []
      tags:
        - Bills (v1)
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns XDR to cancel the bill
          
  /v1/bills/{id}/pay:
    post:
      summary: Pay a Bill
      security:
        - xUserHeader: []
      tags:
        - Bills (v1)
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns XDR to pay the bill
          
  /insurance:
    get:
      summary: Get Active Policies
      security:
        - xUserHeader: []
        - cookieAuth: []
      tags:
        - Insurance
      parameters:
        - in: query
          name: owner
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of active policies
          
  /v1/insurance:
    post:
      summary: Create Insurance Policy
      security:
        - xUserHeader: []
      tags:
        - Insurance (v1)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - coverageType
                - monthlyPremium
                - coverageAmount
              properties:
                name:
                  type: string
                coverageType:
                  type: string
                monthlyPremium:
                  type: number
                coverageAmount:
                  type: number
      responses:
        '200':
          description: Returns XDR
          
  /v1/insurance/{id}/deactivate:
    post:
      summary: Deactivate Insurance Policy
      security:
        - xUserHeader: []
      tags:
        - Insurance (v1)
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns XDR
          
  /v1/insurance/{id}/pay:
    post:
      summary: Pay Insurance Premium
      security:
        - xUserHeader: []
      tags:
        - Insurance (v1)
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns XDR
          
  /goals:
    get:
      summary: Get Savings Goals
      security:
        - cookieAuth: []
      tags:
        - Goals
      responses:
        '200':
          description: Array of goals
    post:
      summary: Create Savings Goal
      security:
        - cookieAuth: []
      tags:
        - Goals
      responses:
        '200':
          description: Success
          
  /family:
    get:
      summary: Get Family Members
      security:
        - cookieAuth: []
      tags:
        - Family
      responses:
        '200':
          description: Array of family members
    post:
      summary: Add Family Member
      security:
        - cookieAuth: []
      tags:
        - Family
      responses:
        '200':
          description: Success
          
  /send:
    post:
      summary: Send Transaction
      security:
        - cookieAuth: []
      tags:
        - Send
      responses:
        '200':
          description: Returns transaction Id