openapi: 3.1.0
info:
  title: MeterMaid — Currency Conversion API
  version: 1.0.0
  description: >
    Currency conversion and rate tables from the European Central Bank's
    euro foreign exchange reference rates (public feed, refreshed on ECB
    business days ~16:00 CET by a Cloudflare Cron Trigger). ECB rates are
    indicative reference rates, not transaction rates; every response
    carries that disclaimer.
servers:
  - url: https://metermaid.square-firefly-0154.workers.dev
security:
  - ApiKey: []
paths:
  /v1/fx/currencies:
    get:
      summary: List supported currencies
      operationId: listCurrencies
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  base: { type: string, example: EUR }
                  date: { type: string, format: date, description: ECB rate date }
                  count: { type: integer }
                  currencies: { type: array, items: { type: string } }
                  disclaimer: { type: string }
  /v1/fx/rates:
    get:
      summary: Full rate table, optionally rebased
      operationId: getRates
      parameters:
        - { name: base, in: query, required: false, schema: { type: string, default: EUR, example: USD } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  base: { type: string }
                  date: { type: string, format: date }
                  rates: { type: object, additionalProperties: { type: number }, description: units per 1 unit of base }
                  disclaimer: { type: string }
        '400':
          description: Unsupported base currency
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /v1/fx/convert:
    get:
      summary: Convert an amount between currencies
      operationId: convert
      parameters:
        - { name: from, in: query, required: true, schema: { type: string, example: EUR } }
        - { name: to, in: query, required: true, schema: { type: string, example: USD } }
        - { name: amount, in: query, required: true, schema: { type: number, example: 100 } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  from: { type: string }
                  to: { type: string }
                  amount: { type: number }
                  result: { type: number }
                  rate: { type: number, description: units of `to` per 1 unit of `from` }
                  date: { type: string, format: date }
                  disclaimer: { type: string }
        '400':
          description: Unsupported currency or invalid amount
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
  schemas:
    Error:
      type: object
      properties:
        error: { type: string, example: unsupported_currency }
        message: { type: string }