openapi: 3.1.0
info:
  title: DBIS Data API
  version: 0.1.0
  description: |
    Public read API for data.d-bis.org — monetary aggregates, GRU series, settlement summaries, rates.
    Every response MUST declare lineage via `x-dbis-lineage` on operations: `on_chain`, `policy`, `modelled`.
servers:
  - url: https://data.d-bis.org
    description: Production
  - url: http://localhost:8080
    description: Local
tags:
  - name: gru
  - name: reserves
  - name: settlement
  - name: rates
paths:
  /v1/health:
    get:
      summary: Liveness
      operationId: health
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: ok }
  /v1/gru/supply:
    get:
      tags: [gru]
      summary: GRU supply time series (when defined)
      operationId: gruSupply
      x-dbis-lineage: policy
      parameters:
        - name: from
          in: query
          schema: { type: string, format: date }
        - name: to
          in: query
          schema: { type: string, format: date }
      responses:
        "200":
          description: Series points
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimeSeriesResponse"
        "501":
          description: Not yet published
  /v1/reserves/summary:
    get:
      tags: [reserves]
      summary: Reserve holdings summary
      operationId: reservesSummary
      x-dbis-lineage: on_chain
      responses:
        "200":
          description: Summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReservesSummary"
  /v1/settlement/volumes:
    get:
      tags: [settlement]
      summary: Settlement volume aggregates
      operationId: settlementVolumes
      x-dbis-lineage: on_chain
      parameters:
        - name: window
          in: query
          schema: { type: string, enum: [1h, 24h, 7d, 30d] }
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SettlementVolumes"
  /v1/rates/reference:
    get:
      tags: [rates]
      summary: Reference rates (policy or observed)
      operationId: referenceRates
      x-dbis-lineage: policy
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    LineageMeta:
      type: object
      required: [lineage, asOf]
      properties:
        lineage:
          type: string
          enum: [on_chain, policy, modelled]
        asOf: { type: string, format: date-time }
        source: { type: string }
    TimeSeriesResponse:
      allOf:
        - $ref: "#/components/schemas/LineageMeta"
        - type: object
          properties:
            unit: { type: string }
            points:
              type: array
              items:
                type: object
                required: [t, v]
                properties:
                  t: { type: string, format: date-time }
                  v: { type: number }
    ReservesSummary:
      allOf:
        - $ref: "#/components/schemas/LineageMeta"
        - type: object
          additionalProperties: true
    SettlementVolumes:
      allOf:
        - $ref: "#/components/schemas/LineageMeta"
        - type: object
          properties:
            window: { type: string }
            totalValue: { type: string, description: Decimal string }
            txCount: { type: integer }