indexer.yaml

openapi: 3.0.3
info:
  title: TrusTrove Indexer API
  version: 1.0.0
  description: |
    Structured API documentation for the TrusTrove Go indexer/API service.

    ## SEP-10 authentication flow

    1. The frontend calls `GET /auth?address=<stellar_public_key>` to request an authentication challenge.
    2. The client signs the returned SEP-10 challenge transaction with Freighter or another Stellar wallet.
    3. The client sends the signed challenge to `POST /auth`.
    4. The indexer validates the signed challenge and returns a JWT.
    5. Protected endpoints use `Authorization: Bearer <jwt>`.

servers:
  - url: http://localhost:8080
    description: Local development
  - url: https://trusttrove-app.onrender.com
    description: Production

tags:
  - name: Health
  - name: Auth
  - name: Invoices
  - name: Stats
  - name: Pool
  - name: Events

security:
  - bearerAuth: []

paths:
  /health:
    get:
      tags: [Health]
      summary: Health check
      security: []
      responses:
        "200":
          description: API is alive
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              examples:
                ok:
                  value:
                    status: ok

  /auth:
    get:
      tags: [Auth]
      summary: Create SEP-10 challenge
      description: Returns a SEP-10 challenge transaction for the supplied Stellar account.
      security: []
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
          example: GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF
      responses:
        "200":
          description: Challenge transaction generated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthChallengeResponse"
              examples:
                challenge:
                  value:
                    transaction: AAAAAgAAA...
                    network_passphrase: Test SDF Network ; September 2015
        "400":
          $ref: "#/components/responses/BadRequest"
    post:
      tags: [Auth]
      summary: Exchange signed SEP-10 challenge for JWT
      description: Validates the signed challenge transaction and returns a bearer token.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthRequest"
            examples:
              signedChallenge:
                value:
                  transaction: AAAAAgAAA...signed...
      responses:
        "200":
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthTokenResponse"
              examples:
                token:
                  value:
                    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                    expires_in: 86400
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /events:
    get:
      tags: [Events]
      summary: List indexed Soroban events
      security: []
      parameters:
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Indexed events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Event"

  /invoices:
    get:
      tags: [Invoices]
      summary: List invoices
      security: []
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [Created, Listed, Funded, Active, Confirmed, Repaid, Defaulted]
        - name: issuer
          in: query
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
      responses:
        "200":
          description: Invoice list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedInvoices"
    post:
      tags: [Invoices]
      summary: Create invoice
      description: Creates an off-chain/indexed invoice record. Requires JWT from the SEP-10 auth flow.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateInvoiceRequest"
            examples:
              invoice:
                value:
                  buyer: GBUYERAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
                  face_value: "1000.00"
                  due_date: 1735689600
                  asset: USDC
      responses:
        "201":
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /invoices/{id}:
    get:
      tags: [Invoices]
      summary: Get invoice by ID
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: a3f8c1d27e904b6a8d5f0139c2e7ab64f0d8c3b19a6e52f7b4c0d91e8a2735bc
      responses:
        "200":
          description: Invoice found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        "404":
          $ref: "#/components/responses/NotFound"

  /stats:
    get:
      tags: [Stats]
      summary: Protocol statistics
      security: []
      responses:
        "200":
          description: Protocol aggregate stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProtocolStats"

  /pool/stats:
    get:
      tags: [Pool]
      summary: Liquidity pool statistics
      security: []
      responses:
        "200":
          description: Pool aggregate stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PoolStats"

  /pool/position/{address}:
    get:
      tags: [Pool]
      summary: LP position by address
      security: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          example: GLPAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
      responses:
        "200":
          description: LP position
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LPPosition"
        "404":
          $ref: "#/components/responses/NotFound"

  /pool/snapshots:
    get:
      tags: [Pool]
      summary: Historical pool snapshots
      description: Returns historical liquidity pool snapshots used for charts and trend analysis.
      security: []
      responses:
        "200":
          description: Pool snapshots
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PoolSnapshot"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      required: [error]

    HealthResponse:
      type: object
      properties:
        status:
          type: string
      required: [status]

    AuthChallengeResponse:
      type: object
      properties:
        transaction:
          type: string
        network_passphrase:
          type: string
      required: [transaction, network_passphrase]

    AuthRequest:
      type: object
      properties:
        transaction:
          type: string
      required: [transaction]

    AuthTokenResponse:
      type: object
      properties:
        token:
          type: string
        expires_in:
          type: integer
      required: [token, expires_in]

    CreateInvoiceRequest:
      type: object
      properties:
        buyer:
          type: string
        face_value:
          type: string
        due_date:
          type: integer
          format: int64
        asset:
          type: string
      required: [buyer, face_value, due_date, asset]

    Invoice:
      type: object
      properties:
        id:
          type: string
          description: Hexadecimal BytesN<32> invoice identifier.
          pattern: "^[0-9a-fA-F]{64}$"
        issuer:
          type: string
        buyer:
          type: string
        face_value:
          type: string
        funded_amount:
          type: string
        due_date:
          type: integer
          format: int64
        status:
          type: string
          enum: [Created, Listed, Funded, Active, Confirmed, Repaid, Defaulted]
        created_at:
          type: integer
          format: int64
      required: [id, issuer, buyer, face_value, due_date, status]

    PaginatedInvoices:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Invoice"
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        totalPages:
          type: integer
      required: [data, total, page, limit, totalPages]

    Event:
      type: object
      properties:
        id:
          type: string
        contract_id:
          type: string
        type:
          type: string
        ledger:
          type: integer
          format: int64
        transaction_hash:
          type: string
        data:
          type: object
          additionalProperties: true
      required: [id, contract_id, type]

    ProtocolStats:
      type: object
      properties:
        total_usdc_financed:
          type: string
        active_invoice_count:
          type: integer
        total_invoices:
          type: integer
        total_repaid:
          type: integer
        total_defaulted:
          type: integer
        average_yield_bps:
          type: integer
        pool_utilization_bps:
          type: integer

    PoolStats:
      type: object
      properties:
        total_deposits:
          type: string
        total_funded:
          type: string
        available_liquidity:
          type: string
        utilization_rate_bps:
          type: integer
        total_yield_distributed:
          type: string
        active_invoice_count:
          type: integer

    LPPosition:
      type: object
      properties:
        shares:
          type: string
        usdc_value:
          type: string
        yield_earned:
          type: string
        deposit_count:
          type: integer

    PoolSnapshot:
      type: object
      properties:
        total_deposits:
          type: string
        total_funded:
          type: string
        available_liquidity:
          type: string
        utilization_rate_bps:
          type: integer
        total_yield_distributed:
          type: string
        active_invoice_count:
          type: integer
        total_shares:
          type: string
        updated_at:
          type: string
          format: date-time