openapi.yaml

openapi: 3.0.0
info:
  title: Lens API
  description: Unified Stellar price API aggregating SDEX + AMM prices.
  version: 0.1.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:4000
    description: Local development server

paths:
  /status:
    get:
      operationId: getStatus
      summary: Get API status and indexer state
      security: []
      responses:
        '200':
          description: API status
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  watchedPairs:
                    type: array
                    items:
                      type: string
                  lastIndexedLedger:
                    type: integer
                    nullable: true
                  lastProcessedAt:
                    type: string
                    format: date-time
                    nullable: true
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /price/{assetA}/{assetB}:
    get:
      operationId: getPrice
      summary: Get aggregated price for a pair
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
          example: XLM
        - name: assetB
          in: path
          required: true
          schema:
            type: string
          example: USDC
      responses:
        '200':
          description: Aggregated price data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatedPrice'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Pair not watched
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /price/{assetA}/{assetB}/route:
    get:
      operationId: getBestRoute
      summary: Get best swap route for a pair and amount
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
        - name: assetB
          in: path
          required: true
          schema:
            type: string
        - name: amount
          in: query
          required: false
          schema:
            type: number
            default: 1000
      responses:
        '200':
          description: Best route information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteInfo'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /price/{assetA}/{assetB}/history:
    get:
      operationId: getPriceHistory
      summary: Get price history buckets
      security: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
        - name: assetB
          in: path
          required: true
          schema:
            type: string
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [1m, 5m, 1h, 24h]
            default: 1h
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            maximum: 1000
      responses:
        '200':
          description: Price history
          content:
            application/json:
              schema:
                type: object
                properties:
                  pairKey:
                    type: string
                  window:
                    type: string
                  buckets:
                    type: array
                    items:
                      $ref: '#/components/schemas/PriceBucket'
        '400':
          description: Invalid parameters
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /pools:
    get:
      operationId: getPools
      summary: Get AMM liquidity pool reserves and spot prices
      security:
        - x402: []
      responses:
        '200':
          description: List of pools
          content:
            application/json:
              schema:
                type: object
                properties:
                  pools:
                    type: array
                    items:
                      type: object
                      properties:
                        pool_id:
                          type: string
                        asset_a:
                          type: string
                        asset_b:
                          type: string
                        reserve_a:
                          type: number
                        reserve_b:
                          type: number
                        spot_price:
                          type: number
                        fee_bp:
                          type: integer
                        timestamp:
                          type: string
                          format: date-time
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /candles/{assetA}/{assetB}:
    get:
      operationId: getCandles
      summary: Get OHLCV candle data
      security:
        - x402: []
      parameters:
        - name: assetA
          in: path
          required: true
          schema:
            type: string
        - name: assetB
          in: path
          required: true
          schema:
            type: string
        - name: interval
          in: query
          required: false
          schema:
            type: string
            enum: [1m, 5m, 15m, 1h, 4h, 1d]
            default: 1h
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Candle data
          content:
            application/json:
              schema:
                type: object
                properties:
                  pairKey:
                    type: string
                  interval:
                    type: string
                  from:
                    type: string
                  to:
                    type: string
                  candles:
                    type: array
                    items:
                      type: object
                      properties:
                        time:
                          type: string
                          format: date-time
                        open:
                          type: number
                        high:
                          type: number
                        low:
                          type: number
                        close:
                          type: number
                        volume:
                          type: number
        '400':
          description: Invalid parameters
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /prices/history:
    get:
      operationId: getPriceHistory
      summary: Get historical 1-minute price snapshots
      description: >-
        Returns minute-resolution price snapshots for a pair over [from, to],
        optionally aggregated into 5m or 1h buckets. Snapshots are retained for
        ~30 days. Gated by x402 (matches the /price prefix).
      security:
        - x402: []
      parameters:
        - name: pair
          in: query
          required: true
          schema:
            type: string
          example: XLM/USDC
        - name: interval
          in: query
          required: false
          schema:
            type: string
            enum: [1m, 5m, 1h]
            default: 1m
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Historical price snapshots
          content:
            application/json:
              schema:
                type: object
                properties:
                  pair:
                    type: string
                  interval:
                    type: string
                  from:
                    type: string
                    format: date-time
                  to:
                    type: string
                    format: date-time
                  count:
                    type: integer
                  points:
                    type: array
                    items:
                      type: object
                      properties:
                        ts:
                          type: string
                          format: date-time
                        price:
                          type: number
                        volume:
                          type: number
        '400':
          description: Invalid parameters
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /pairs:
    get:
      operationId: listPairs
      summary: List all active trading pairs
      security: []
      responses:
        '200':
          description: List of pairs
          content:
            application/json:
              schema:
                type: object
                properties:
                  pairs:
                    type: array
                    items:
                      type: object
                      properties:
                        pairKey:
                          type: string
                        assetA:
                          $ref: '#/components/schemas/Asset'
                        assetB:
                          $ref: '#/components/schemas/Asset'
                        latestPrice:
                          type: number
                          nullable: true
                        lastUpdated:
                          type: string
                          format: date-time
                          nullable: true
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: addPair
      summary: Add a new trading pair (Admin only)
      security:
        - adminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                assetA:
                  type: string
                  example: XLM
                assetB:
                  type: string
                  example: USDC:GBBD47...
      responses:
        '201':
          description: Pair added
        '400':
          description: Invalid input
        '401':
          description: Unauthorized
        '409':
          description: Pair already exists
        '429':
          $ref: '#/components/responses/TooManyRequests'

components:
  securitySchemes:
    x402:
      type: apiKey
      name: X-PAYMENT
      in: header
      description: Base64 encoded JSON payment proof for x402 micropayments.
    adminAuth:
      type: apiKey
      name: X-Admin-Key
      in: header

  responses:
    PaymentRequired:
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            properties:
              x402Version:
                type: integer
              accepts:
                type: array
                items:
                  type: object
                  properties:
                    scheme:
                      type: string
                    price:
                      type: string
                    network:
                      type: string
                    payTo:
                      type: string
              error:
                type: string
              description:
                type: string
    TooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests in current window
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              error:
                type: string
              message:
                type: string
              retryAfter:
                type: string

  schemas:
    Asset:
      type: object
      properties:
        code:
          type: string
        issuer:
          type: string
          nullable: true

    AggregatedPrice:
      type: object
      properties:
        assetA:
          type: string
        assetB:
          type: string
        pairKey:
          type: string
        price:
          type: number
        sdexPrice:
          type: number
        ammPrice:
          type: number
        bestRoute:
          type: string
          enum: [SDEX, AMM, SPLIT, UNKNOWN]
        volume24h:
          type: number
        sdexVolume24h:
          type: number
        ammVolume24h:
          type: number
        vwap1m:
          type: number
        vwap5m:
          type: number
        vwap1h:
          type: number
        vwap24h:
          type: number
        priceChange24h:
          type: number
        lastUpdated:
          type: string
          format: date-time
        sources:
          type: integer
        confidence:
          type: string
          enum: [high, medium, low, unknown]
        lastTradeAgeSeconds:
          type: integer
          nullable: true

    RouteInfo:
      type: object
      properties:
        route:
          type: string
          enum: [SDEX, AMM, SPLIT, UNKNOWN]
        sdexPrice:
          type: number
        ammPrice:
          type: number
        estimatedOutput:
          type: number
        slippagePct:
          type: number
        recommendation:
          type: string

    PriceBucket:
      type: object
      properties:
        bucket:
          type: string
          format: date-time
        window:
          type: string
        vwap:
          type: number
        sdexVwap:
          type: number
          nullable: true
        ammVwap:
          type: number
          nullable: true
        volume:
          type: number
        tradeCount:
          type: integer
        open:
          type: number
          nullable: true
        close:
          type: number
          nullable: true
        high:
          type: number
          nullable: true
        low:
          type: number
          nullable: true