openapi.yaml

components:
  headers:
    XRequestID:
      description: >-
        Unique identifier for the request. Include this in support requests to correlate client activity with server
        logs. If you supply a valid UUID v4 in the `X-Request-ID` request header the server echoes it back; otherwise
        the server generates one automatically.
      schema:
        example: 550e8400-e29b-41d4-a716-446655440000
        format: uuid
        type: string
    XSchemaVersion:
      description: >-
        Request-body schema variant. Accepted values are full semver strings (e.g. "1.0.0", "2.0.0"). An integer
        shorthand (e.g. "1") is also accepted and is normalised to "1.0.0" for backward compatibility. Omitting this
        header selects the latest stable schema for the endpoint. Supported versions for a given endpoint are listed in
        the X-Schema-Version-Supported response header. NOTE: this header governs the request-body schema only — it is
        independent of the URL API version (/api/v1). The URL version changes only on breaking (MAJOR) API releases.
      schema:
        example: 1.0.0
        type: string
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
      description: Resource not found
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
      description: Missing or invalid API key
    ValidationError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
      description: Validation error
  schemas:
    Error:
      properties:
        error:
          properties:
            code:
              example: VALIDATION_ERROR
              type: string
            message:
              example: Validation failed
              type: string
          type: object
        success:
          example: false
          type: boolean
      type: object
    NotFoundError:
      properties:
        error:
          properties:
            code:
              example: NOT_FOUND
              type: string
            message:
              example: Resource not found
              type: string
          type: object
        success:
          example: false
          type: boolean
      type: object
    PaginationMeta:
      properties:
        direction:
          enum:
            - next
            - prev
          example: next
          type: string
        limit:
          example: 20
          type: integer
        next_cursor:
          example: eyJ0aW1lc3RhbXAiOiIyMDI0LTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJpZCI6IjEifQ==
          nullable: true
          type: string
        prev_cursor:
          example: null
          nullable: true
          type: string
      type: object
    UnauthorizedError:
      properties:
        error:
          properties:
            code:
              example: UNAUTHORIZED
              type: string
            message:
              example: Invalid or missing API key
              type: string
          type: object
        success:
          example: false
          type: boolean
      type: object
    ValidationError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - properties:
            error:
              properties:
                code:
                  example: VALIDATION_ERROR
                  type: string
                details:
                  items:
                    properties:
                      field:
                        type: string
                      message:
                        type: string
                    type: object
                  type: array
                message:
                  example: Invalid request parameters
                  type: string
              type: object
          type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key passed in the x-api-key header. Obtain via `npm run keys:create`.
      in: header
      name: x-api-key
      type: apiKey
info:
  description: API for managing micro-donations on the Stellar blockchain network.
  title: Stellar Micro-Donation API
  version: 1.0.0
openapi: 3.1.0
paths:
  /admin/audit-logs/export:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                endDate:
                  format: date-time
                  type: string
                eventType:
                  type: string
                format:
                  default: json
                  enum:
                    - json
                    - csv
                  type: string
                startDate:
                  format: date-time
                  type: string
              type: object
        required: true
      responses:
        '202':
          description: Export job queued
        '400':
          description: Validation error
      security:
        - ApiKeyAuth: []
      summary: Queue an async audit log export job
      tags:
        - AuditLogExport
  /admin/audit-logs/export/{jobId}/download:
    get:
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
        - in: query
          name: format
          schema:
            enum:
              - json
              - csv
            type: string
      responses:
        '200':
          description: Signed download URL
        '202':
          description: Export not yet complete
        '404':
          description: Job not found
      security:
        - ApiKeyAuth: []
      summary: Get signed download URL for completed export
      tags:
        - AuditLogExport
  /admin/audit-logs/export/{jobId}/status:
    get:
      parameters:
        - in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job status
        '404':
          description: Job not found
      security:
        - ApiKeyAuth: []
      summary: Poll export job status
      tags:
        - AuditLogExport
  /donations/{id}/approve:
    post:
      description: >
        Donations above the configured MULTISIG_THRESHOLD_XLM are created with status `awaiting_approval` instead of
        being submitted immediately. Each call records one signer's approval; once the required number of distinct
        signers have approved, the donation is submitted to Stellar automatically. Requires the `donations:approve`
        permission (granted to the `signer` and `admin` roles).
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                signerKeyId:
                  description: Identifier of the approving signer (e.g. their Stellar public key)
                  type: string
              required:
                - signerKeyId
              type: object
        required: true
      responses:
        '200':
          description: Approval recorded (and donation submitted if fully approved)
        '400':
          description: Validation error (missing signerKeyId, duplicate approval)
        '403':
          description: Caller lacks the donations:approve permission
        '404':
          description: Donation not found
        '422':
          description: Donation is not currently awaiting approval, or the approval window has expired
      security:
        - ApiKeyAuth: []
      summary: Record a multi-signer approval for a high-value donation (#1498)
      tags:
        - Donations
  /liquidity-pools/deposit:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                assetA:
                  description: First asset (e.g. {type:"native"} or {type:"credit_alphanum4",code:"USDC",issuer:"G..."})
                  type: object
                assetB:
                  description: Second asset
                  type: object
                maxAmountA:
                  description: Maximum amount of assetA to deposit
                  type: string
                maxAmountB:
                  description: Maximum amount of assetB to deposit
                  type: string
                secret:
                  description: Source account secret key
                  type: string
              required:
                - secret
                - assetA
                - assetB
                - maxAmountA
                - maxAmountB
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      ledger:
                        type: integer
                      poolId:
                        type: string
                      sharesReceived:
                        type: string
                      transactionId:
                        type: string
                    type: object
                  success:
                    type: boolean
                type: object
          description: Deposit successful
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Validation error
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuth: []
      summary: Deposit assets into a Stellar liquidity pool
      tags:
        - LiquidityPools
  /liquidity-pools/withdraw:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount:
                  description: Number of pool shares to redeem
                  type: string
                poolId:
                  type: string
                secret:
                  type: string
              required:
                - secret
                - poolId
                - amount
              type: object
        required: true
      responses:
        '200':
          description: Withdrawal successful
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Validation error
        '401':
          description: Unauthorized
      security:
        - ApiKeyAuth: []
      summary: Withdraw assets from a Stellar liquidity pool
      tags:
        - LiquidityPools
  /liquidity-pools/{id}/earnings:
    get:
      parameters:
        - description: Pool ID
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Pool earnings
        '404':
          description: Pool not found
      security:
        - ApiKeyAuth: []
      summary: Get earnings for a liquidity pool
      tags:
        - LiquidityPools
  /stats/daily:
    get:
      responses:
        '200':
          description: Daily stats
      security:
        - ApiKeyAuth: []
      summary: Get daily donation statistics
      tags:
        - Statistics
  /stats/donors:
    get:
      responses:
        '200':
          description: Donor stats
      security:
        - ApiKeyAuth: []
      summary: Get donor statistics
      tags:
        - Statistics
  /stats/recipients:
    get:
      responses:
        '200':
          description: Recipient stats
      security:
        - ApiKeyAuth: []
      summary: Get recipient statistics
      tags:
        - Statistics
  /stats/summary:
    get:
      responses:
        '200':
          description: Summary analytics
      security:
        - ApiKeyAuth: []
      summary: Get summary analytics
      tags:
        - Statistics
  /stats/weekly:
    get:
      responses:
        '200':
          description: Weekly stats
      security:
        - ApiKeyAuth: []
      summary: Get weekly donation statistics
      tags:
        - Statistics
  /stream/create:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                amount:
                  type: number
                donorPublicKey:
                  type: string
                frequency:
                  enum:
                    - daily
                    - weekly
                    - monthly
                  type: string
                recipientPublicKey:
                  type: string
              required:
                - donorPublicKey
                - recipientPublicKey
                - amount
                - frequency
              type: object
        required: true
      responses:
        '201':
          description: Schedule created
        '400':
          description: Validation error
      security:
        - ApiKeyAuth: []
      summary: Create a recurring donation schedule
      tags:
        - Stream
  /stream/schedules:
    get:
      responses:
        '200':
          description: List of schedules
      security:
        - ApiKeyAuth: []
      summary: List all recurring donation schedules
      tags:
        - Stream
  /stream/schedules/{id}:
    delete:
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Schedule cancelled
        '404':
          description: Schedule not found
      security:
        - ApiKeyAuth: []
      summary: Cancel a recurring donation schedule
      tags:
        - Stream
    get:
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Schedule details
        '404':
          description: Schedule not found
      security:
        - ApiKeyAuth: []
      summary: Get a specific schedule
      tags:
        - Stream
  /transactions:
    get:
      parameters:
        - in: query
          name: limit
          schema:
            default: 20
            type: integer
        - in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: Paginated transaction list
      security:
        - ApiKeyAuth: []
      summary: Get paginated transactions
      tags:
        - Transactions
  /transactions/multisig:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                network_passphrase:
                  type: string
                required_signers:
                  minimum: 2
                  type: integer
                signer_keys:
                  items:
                    type: string
                  type: array
                transaction_xdr:
                  type: string
              required:
                - transaction_xdr
                - network_passphrase
                - required_signers
                - signer_keys
              type: object
        required: true
      responses:
        '201':
          description: Multi-sig transaction created
      security:
        - ApiKeyAuth: []
      summary: Create a pending multi-sig transaction
      tags:
        - Transactions
  /transactions/multisig/collect:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:
                  type: integer
                signed_xdr:
                  type: string
                signer:
                  type: string
              required:
                - id
                - signer
                - signed_xdr
              type: object
        required: true
      responses:
        '200':
          description: Signature collected; submitted if threshold met
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        example: INSUFFICIENT_SIGNATURES
                        type: string
                      collected:
                        type: integer
                      remaining:
                        type: integer
                      required:
                        type: integer
                    type: object
                  success:
                    example: false
                    type: boolean
                type: object
          description: Insufficient signatures
      security:
        - ApiKeyAuth: []
      summary: Collect a signature for a pending multi-sig transaction
      tags:
        - Transactions
  /transactions/sync:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                publicKey:
                  type: string
              required:
                - publicKey
              type: object
        required: true
      responses:
        '200':
          description: Sync completed
      security:
        - ApiKeyAuth: []
      summary: Sync wallet transactions from Stellar network
      tags:
        - Transactions
security:
  - ApiKeyAuth: []
servers:
  - description: Current server
    url: /
tags:
  - description: Create and manage donations on the Stellar network
    name: Donations
  - description: Recurring donation schedules
    name: Stream
  - description: Transaction history and synchronization
    name: Transactions
  - description: Donation analytics and statistics
    name: Statistics
  - description: Stellar AMM liquidity pool deposit, withdrawal, and earnings
    name: LiquidityPools
  - description: Compliance audit log export with async jobs and signed URLs
    name: AuditLogExport