openapi.yaml

openapi: 3.0.3
info:
  title: Creditra API
  version: 0.1.0
  description: |
    Backend API for Creditra – on-chain credit scoring and risk evaluation.

    Browser clients are restricted by a CORS allowlist. Production deployments
    must set `CORS_ORIGINS` to a comma-separated list of exact origins; local
    development falls back to loopback origins when the variable is unset.

    ## Authentication
    Protected endpoints require a valid API key passed via the `X-API-Key` header.
    API keys are configured via the `API_KEYS` environment variable (comma-separated).

    ## Keeping the spec in sync
    - Every new route **must** have a corresponding entry here before merging.
    - Run `npm run validate:spec` in CI to catch YAML/structural errors early.
    - Use path-level `operationId` values as the source of truth for client generation.

servers:
  - url: http://localhost:3000
    description: Local development

tags:
  - name: Health
    description: Service liveness check
  - name: Credit
    description: Credit line management
  - name: Risk
    description: On-chain risk evaluation
  - name: Webhooks
    description: Draw confirmation webhook management

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key for authenticated endpoints. Required for admin operations.
        Keys are configured via the `API_KEYS` environment variable.

  schemas:
    HealthResponse:
      type: object
      required: [status, service]
      properties:
        status:
          type: string
          example: ok
        service:
          type: string
          example: creditra-backend

    # ── Credit Line Schemas ──────────────────────────────────────────────────

    CreateCreditLineRequest:
      type: object
      required: [walletAddress, requestedLimit]
      properties:
        walletAddress:
          type: string
          minLength: 1
          maxLength: 256
          description: Stellar wallet address
          example: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
        requestedLimit:
          type: string
          pattern: "^\\d+(\\.\\d+)?$"
          description: Requested credit limit as a decimal string
          example: "1000.00"
      additionalProperties: false

    UpdateCreditLineRequest:
      type: object
      properties:
        creditLimit:
          type: string
          pattern: "^\\d+(\\.\\d+)?$"
          description: Updated credit limit
          example: "1500.00"
        interestRateBps:
          type: number
          description: Interest rate in basis points
          example: 640
        status:
          type: string
          enum: [active, suspended, closed]
          description: Credit line status
      additionalProperties: false

    CreditLine:
      type: object
      properties:
        id:
          type: string
          description: Unique credit line identifier
          example: "cl_abc123"
        walletAddress:
          type: string
          description: Associated Stellar wallet address
          example: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
        creditLimit:
          type: string
          description: Approved credit limit
          example: "720.00000000"
        currentBalance:
          type: string
          description: Current outstanding balance
          example: "100.00000000"
        availableCredit:
          type: string
          description: Available credit (creditLimit - currentBalance)
          example: "620.00000000"
        interestRateBps:
          type: number
          description: Interest rate in basis points
          example: 640
        status:
          type: string
          enum: [active, suspended, closed]
          description: Current credit line status
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 last update timestamp

    CreditLinesResponse:
      type: object
      required: [creditLines, pagination]
      properties:
        creditLines:
          type: array
          items:
            $ref: "#/components/schemas/CreditLine"
        pagination:
          type: object
          properties:
            total:
              type: integer
            offset:
              type: integer
            limit:
              type: integer
          required: [total, offset, limit]

    WalletCreditLinesResponse:
      type: object
      required: [creditLines]
      properties:
        creditLines:
          type: array
          items:
            $ref: "#/components/schemas/CreditLine"

    CreditLineActionResponse:
      type: object
      required: [line, message]
      properties:
        line:
          $ref: "#/components/schemas/CreditLine"
        message:
          type: string
          example: "Credit line suspended."

    # ── Transaction Schemas ──────────────────────────────────────────────────

    Transaction:
      type: object
      required: [id, creditLineId, type, amount, currency, timestamp, metadata]
      properties:
        id:
          type: string
          format: uuid
          description: Unique transaction identifier
        creditLineId:
          type: string
          description: ID of the credit line this transaction belongs to
        type:
          type: string
          enum: [borrow, repay, interest_accrual, fee, status_change]
          description: Transaction type
        amount:
          type: string
          nullable: true
          description: Transaction amount as a decimal string; null for status changes
          example: "500.00000000"
        currency:
          type: string
          nullable: true
          description: Currency code (e.g. USDC); null for status changes
          example: USDC
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the transaction occurred
        metadata:
          type: object
          additionalProperties: true
          description: Additional context; status changes include an 'action' field
          example:
            action: created

    TransactionHistoryResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [transactions, total, page, limit, totalPages]
          properties:
            transactions:
              type: array
              items:
                $ref: "#/components/schemas/Transaction"
            total:
              type: integer
              description: Total number of transactions matching the applied filters
            page:
              type: integer
              description: Current page number (1-indexed)
            limit:
              type: integer
              description: Maximum number of transactions per page
            totalPages:
              type: integer
              description: Total number of pages available

    # ── Risk Evaluation Schemas ───────────────────────────────────────────────

    RiskEvaluateRequest:
      type: object
      required: [walletAddress]
      properties:
        walletAddress:
          type: string
          description: Stellar wallet address to evaluate
          example: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
        forceRefresh:
          type: boolean
          description: Optional hint to bypass cache and recalculate risk
          default: false
      additionalProperties: false

    RiskEvaluateResponse:
      type: object
      required: [walletAddress, riskScore, creditLimit, interestRateBps, message]
      properties:
        walletAddress:
          type: string
          example: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
        riskScore:
          type: number
          description: Risk score (0-100)
          example: 72
        creditLimit:
          type: string
          description: Recommended credit limit
          example: "720.00000000"
        interestRateBps:
          type: number
          description: Recommended interest rate in basis points
          example: 640
        message:
          type: string
          example: "New risk evaluation completed"

    RiskEvaluateApiResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: "#/components/schemas/RiskEvaluateResponse"
        error:
          type: string
          nullable: true

    RiskEvaluation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique evaluation identifier
        walletAddress:
          type: string
          description: Evaluated wallet address
        riskScore:
          type: number
          description: Risk score (0-100)
        creditLimit:
          type: string
          description: Recommended credit limit
        interestRateBps:
          type: number
          description: Recommended interest rate in basis points
        factors:
          type: object
          additionalProperties: true
          description: Risk evaluation factors and weights
        evaluatedAt:
          type: string
          format: date-time
          description: ISO 8601 evaluation timestamp

    RiskEvaluationHistoryResponse:
      type: object
      required: [evaluations]
      properties:
        evaluations:
          type: array
          items:
            $ref: "#/components/schemas/RiskEvaluation"

    # ── Webhook Schemas ───────────────────────────────────────────────────────

    WebhookConfigResponse:
      type: object
      properties:
        urls:
          type: array
          items:
            type: string
          example: ["https://example.com/webhook"]
        maxRetries:
          type: integer
          example: 3
        initialBackoffMs:
          type: integer
          example: 1000
        backoffMultiplier:
          type: number
          example: 2.0
        timeoutMs:
          type: integer
          example: 10000
        configured:
          type: boolean
          example: true

    WebhookTestResponse:
      type: object
      properties:
        total:
          type: integer
        reachable:
          type: integer
        unreachable:
          type: integer
        results:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              reachable:
                type: boolean
              error:
                type: string
                nullable: true

    WebhookHealthResponse:
      type: object
      properties:
        status:
          type: string
          enum: [active, disabled]
        urls:
          type: integer
          description: Number of configured webhook URLs
        maxRetries:
          type: integer
        timeoutMs:
          type: integer

    AdminRecalibrateResponse:
      type: object
      properties:
        message:
          type: string
          example: "Risk model recalibration triggered"

    # ── Error Schemas ─────────────────────────────────────────────────────────

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
        id:
          type: string
          description: Present on 404 responses that reference a specific resource

    RateLimitErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          example: "Too many requests"

paths:
  /health:
    get:
      tags: [Health]
      operationId: getHealth
      summary: Liveness check
      security: []
      responses:
        "200":
          description: Service is running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              example:
                status: ok
                service: creditra-backend

  # ── Credit Lines Routes ─────────────────────────────────────────────────────

  /api/credit/lines:
    get:
      tags: [Credit]
      operationId: listCreditLines
      summary: List all credit lines
      security: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Pagination offset
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
          description: Number of credit lines per page
      responses:
        "200":
          description: Array of credit lines (may be empty)
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per window
              schema:
                type: integer
                example: 100
            X-RateLimit-Remaining:
              description: Requests remaining in current window
              schema:
                type: integer
                example: 95
            X-RateLimit-Reset:
              description: Unix timestamp when the rate limit window resets
              schema:
                type: integer
                example: 1700000060
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditLinesResponse"
              example:
                creditLines: []
                pagination:
                  total: 0
                  offset: 0
                  limit: 100
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
                example: 47
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitErrorResponse"

    post:
      tags: [Credit]
      operationId: createCreditLine
      summary: Create a new credit line
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCreditLineRequest"
            example:
              walletAddress: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
              requestedLimit: "1000.00"
      responses:
        "201":
          description: Credit line created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditLine"
        "400":
          description: Validation error or missing required fields
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/credit/lines/{id}:
    get:
      tags: [Credit]
      operationId: getCreditLineById
      summary: Get a credit line by ID
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Credit line identifier
      responses:
        "200":
          description: Credit line found
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditLine"
        "404":
          description: Credit line not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Credit line not found
                id: "abc123"
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitErrorResponse"

    put:
      tags: [Credit]
      operationId: updateCreditLine
      summary: Update a credit line
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Credit line identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCreditLineRequest"
            example:
              creditLimit: "1500.00"
              interestRateBps: 640
              status: active
      responses:
        "200":
          description: Credit line updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditLine"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Credit line not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      tags: [Credit]
      operationId: deleteCreditLine
      summary: Delete a credit line
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Credit line identifier
      responses:
        "204":
          description: Credit line deleted successfully
        "404":
          description: Credit line not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/credit/lines/{id}/transactions:
    get:
      tags: [Credit]
      operationId: getCreditLineTransactions
      summary: List transaction history for a credit line
      description: |
        Returns a paginated list of transactions for the given credit line.
        Supports optional filtering by transaction type and date range.
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Credit line identifier
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [borrow, repay, interest_accrual, fee, status_change]
          description: Filter by transaction type
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Include only transactions at or after this ISO 8601 timestamp (inclusive)
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Include only transactions at or before this ISO 8601 timestamp (inclusive)
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (1-indexed)
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of transactions per page
      responses:
        "200":
          description: Paginated list of transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionHistoryResponse"
              example:
                data:
                  transactions:
                    - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      creditLineId: "line-abc"
                      type: status_change
                      amount: null
                      currency: null
                      timestamp: "2024-01-15T10:00:00.000Z"
                      metadata:
                        action: created
                  total: 1
                  page: 1
                  limit: 20
                  totalPages: 1
        "400":
          description: Invalid query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: "Invalid type filter. Must be one of: borrow, repay, interest_accrual, fee, status_change."
        "404":
          description: Credit line not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/credit/lines/{id}/suspend:
    post:
      tags: [Credit]
      operationId: suspendCreditLine
      summary: Suspend a credit line
      description: |
        Suspends the specified credit line, preventing further draws.
        Requires API key authentication.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Credit line identifier
      responses:
        "200":
          description: Credit line suspended successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditLineActionResponse"
        "401":
          description: API key missing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Unauthorized
        "403":
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Forbidden
        "404":
          description: Credit line not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/credit/lines/{id}/close:
    post:
      tags: [Credit]
      operationId: closeCreditLine
      summary: Close a credit line
      description: |
        Closes the specified credit line permanently.
        Requires API key authentication.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Credit line identifier
      responses:
        "200":
          description: Credit line closed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditLineActionResponse"
        "401":
          description: API key missing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Unauthorized
        "403":
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Forbidden
        "404":
          description: Credit line not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/credit/wallet/{walletAddress}/lines:
    get:
      tags: [Credit]
      operationId: getCreditLinesByWallet
      summary: Get credit lines for a specific wallet
      security: []
      parameters:
        - name: walletAddress
          in: path
          required: true
          schema:
            type: string
          description: Stellar wallet address
      responses:
        "200":
          description: Credit lines for the wallet
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletCreditLinesResponse"
              example:
                creditLines:
                  - id: "cl_abc123"
                    walletAddress: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
                    creditLimit: "720.00000000"
                    currentBalance: "100.00000000"
                    availableCredit: "620.00000000"
                    interestRateBps: 640
                    status: active
                    createdAt: "2024-01-15T10:00:00.000Z"
                    updatedAt: "2024-01-15T10:00:00.000Z"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  # ── Risk Evaluation Routes ──────────────────────────────────────────────────

  /api/risk/evaluate:
    post:
      tags: [Risk]
      operationId: evaluateRisk
      summary: Evaluate on-chain risk for a wallet
      description: |
        Performs a fresh risk evaluation for the given Stellar wallet address.
        Rate limited: default 10 requests per minute per IP address.
        Configure via RATE_LIMIT_MAX_EVALUATE and RATE_LIMIT_WINDOW_MS env vars.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RiskEvaluateRequest"
            example:
              walletAddress: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
              forceRefresh: false
      responses:
        "200":
          description: Risk evaluation result
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per window
              schema:
                type: integer
                example: 10
            X-RateLimit-Remaining:
              description: Requests remaining in current window
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when the rate limit window resets
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RiskEvaluateApiResponse"
              example:
                data:
                  walletAddress: "GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOUJ3LNLRK"
                  riskScore: 72
                  creditLimit: "720.00000000"
                  interestRateBps: 640
                  message: New risk evaluation completed
                error: null
        "400":
          description: Missing required field
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Validation failed
        "413":
          description: Request body exceeds the 100 kb limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                data: null
                error: Request body too large. Maximum size is 100kb.
        "415":
          description: Content-Type is not application/json
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                data: null
                error: Content-Type must be application/json

  /api/webhooks/config:
    get:
      tags: [Webhooks]
      operationId: getWebhookConfig
      summary: Get webhook configuration
      description: Returns the current webhook configuration (excluding sensitive data)
      security: []
      responses:
        "200":
          description: Webhook configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookConfigResponse"
              example:
                urls: ["https://example.com/webhook"]
                maxRetries: 3
                initialBackoffMs: 1000
                backoffMultiplier: 2.0
                timeoutMs: 10000
                configured: true

  /api/webhooks/test:
    post:
      tags: [Webhooks]
      operationId: testWebhooks
      summary: Test webhook connectivity
      description: Sends a test payload to all configured webhook endpoints
      security: []
      responses:
        "200":
          description: Test results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookTestResponse"
              example:
                total: 2
                reachable: 1
                unreachable: 1
                results:
                  - url: "https://example.com/webhook"
                    reachable: true
                  - url: "https://test.com/hook"
                    reachable: false
                    error: "Connection refused"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/webhooks/health:
    get:
      tags: [Webhooks]
      operationId: getWebhookHealth
      summary: Webhook service health check
      description: Returns the health status of the webhook service
      security: []
      responses:
        "200":
          description: Webhook service health
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookHealthResponse"
              example:
                status: active
                urls: 2
                maxRetries: 3
                timeoutMs: 10000

  /api/risk/evaluations/{id}:
    get:
      tags: [Risk]
      operationId: getRiskEvaluationById
      summary: Fetch a stored risk evaluation by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Risk evaluation identifier
      responses:
        "200":
          description: Risk evaluation found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RiskEvaluation"
        "404":
          description: Risk evaluation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Risk evaluation not found
                id: "abc123"

  /api/risk/wallet/{walletAddress}/latest:
    get:
      tags: [Risk]
      operationId: getLatestRiskEvaluation
      summary: Get the latest risk evaluation for a wallet
      parameters:
        - name: walletAddress
          in: path
          required: true
          schema:
            type: string
            pattern: '^G[A-Z2-7]{55}$'
          description: Stellar public key
      responses:
        "200":
          description: Risk evaluation found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RiskEvaluateResponse"
        "400":
          description: Invalid wallet address
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: No risk evaluation found for wallet
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/risk/wallet/{walletAddress}/history:
    get:
      tags: [Risk]
      operationId: getRiskEvaluationHistory
      summary: Get risk evaluation history for a wallet
      parameters:
        - name: walletAddress
          in: path
          required: true
          schema:
            type: string
            pattern: '^G[A-Z2-7]{55}$'
          description: Stellar public key
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Pagination offset
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Pagination limit
      responses:
        "200":
          description: Array of risk evaluations
          content:
            application/json:
              schema:
                type: object
                properties:
                  evaluations:
                    type: array
                    items:
                      $ref: "#/components/schemas/RiskEvaluation"
        "400":
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"


components:
  schemas:
    HealthResponse:
      type: object
      required: [status, service]
      properties:
        status:
          type: string
          example: ok
        service:
          type: string
          example: creditra-backend

    CreditLine:
      type: object
      description: Placeholder – expand as the credit engine is built out
      properties:
        id:
          type: string
        owner:
          type: string
        limit:
          type: string

    CreditLinesResponse:
      type: object
      required: [creditLines, pagination]
      properties:
        creditLines:
          type: array
          items:
            $ref: "#/components/schemas/CreditLine"
        pagination:
          type: object
          properties:
            total:
              type: integer
            offset:
              type: integer
            limit:
              type: integer
          required: [total, offset, limit]

    RiskEvaluateRequest:
      type: object
      required: [walletAddress]
      properties:
        walletAddress:
          type: string
          description: Stellar public key (G...)
          pattern: '^G[A-Z2-7]{55}$'
          example: "GBAHQCUPC7G2B4D2F2I2K2M2O2Q2S2U2W2Y2A2C2E2G2I2K2M2O2Q2S2"
        forceRefresh:
          type: boolean
          description: Optional hint to bypass cache and recalculate risk
          default: false

    RiskEvaluateResponse:
      type: object
      required: [walletAddress, riskScore, creditLimit, interestRateBps, message]
      properties:
        walletAddress:
          type: string
        riskScore:
          type: number
        creditLimit:
          type: string
        interestRateBps:
          type: number
        message:
          type: string

    RiskEvaluateApiResponse:
      type: object
      required: [data, error]
      properties:
        data:
          $ref: "#/components/schemas/RiskEvaluateResponse"
        error:
          type: string
          nullable: true

    Transaction:
      type: object
      required: [id, creditLineId, type, amount, currency, timestamp, metadata]
      properties:
        id:
          type: string
          format: uuid
          description: Unique transaction identifier
        creditLineId:
          type: string
          description: ID of the credit line this transaction belongs to
        type:
          type: string
          enum: [borrow, repay, interest_accrual, fee, status_change]
          description: Transaction type
        amount:
          type: string
          nullable: true
          description: Transaction amount as a decimal string; null for status changes
          example: "500.00000000"
        currency:
          type: string
          nullable: true
          description: Currency code (e.g. USDC); null for status changes
          example: USDC
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the transaction occurred
        metadata:
          type: object
          additionalProperties: true
          description: Additional context; status changes include an 'action' field
          example:
            action: created

    TransactionHistoryResponse:
      type: object
      required: [data, error]
      properties:
        data:
          type: object
          required: [transactions, total, page, limit, totalPages]
          properties:
            transactions:
              type: array
              items:
                $ref: "#/components/schemas/Transaction"
            total:
              type: integer
              description: Total number of transactions matching the applied filters
            page:
              type: integer
              description: Current page number (1-indexed)
            limit:
              type: integer
              description: Maximum number of transactions per page
            totalPages:
              type: integer
              description: Total number of pages available
        error:
          type: string
          nullable: true

    ErrorResponse:
      type: object
      required: [data, error]
      description: Standardized error response format used across all endpoints
      properties:
        data:
          type: object
          nullable: true
          description: Always null for error responses
        error:
          type: string
        id:
          type: string
          description: Present on 404 responses that reference a specific resource