Frankfurter API — Rates

naftiko: 1.0.0-alpha2
info:
  label: Frankfurter API — Rates
  description: 'Frankfurter API — Rates. 2 operation(s). Lead operation: Frankfurter Get Exchange Rates. Self-contained Naftiko capability covering one Frankfurter business surface.'
  tags:
    - Frankfurter
    - Currency Exchange
    - Rates
  created: '2026-05-29'
  modified: '2026-05-29'
binds: []
capability:
  consumes:
    - type: http
      namespace: v2-rates
      baseUri: https://api.frankfurter.dev/v2
      description: Frankfurter API — Rates business capability. Self-contained, no shared references. Public, no authentication required.
      resources:
        - name: rates
          path: /rates
          operations:
            - name: getRates
              method: GET
              description: Frankfurter Get Exchange Rates
              inputParameters:
                - name: date
                  in: query
                  type: string
                  required: false
                  description: Specific date (YYYY-MM-DD). Cannot be combined with from/to.
                - name: from
                  in: query
                  type: string
                  required: false
                  description: Start of date range (YYYY-MM-DD)
                - name: to
                  in: query
                  type: string
                  required: false
                  description: End of date range (YYYY-MM-DD). Defaults to today.
                - name: base
                  in: query
                  type: string
                  required: false
                  description: 'Base currency (default: EUR)'
                - name: quotes
                  in: query
                  type: string
                  required: false
                  description: Comma-separated list of quote currencies to include
                - name: providers
                  in: query
                  type: string
                  required: false
                  description: Comma-separated list of data providers to include
                - name: group
                  in: query
                  type: string
                  required: false
                  description: Downsample rates by time period. Only applies to date ranges.
                - name: expand
                  in: query
                  type: string
                  required: false
                  description: "Comma-separated list of optional fields to include per record. Currently supports `providers`, which adds an array of `{ key, rate }` objects per record showing each provider's
                    individual rate. Outliers excluded from the blend (and providers whose rate was overridden by a currency peg) are flagged with `excluded: true`. The field is omitted on synthesized peg
                    rows where no provider published the quote. In CSV output, the `providers` column is encoded as `KEY:RATE` pairs joined by `|`, with a trailing `*` on excluded entries (e.g. `ECB:0.92|FED:1.50*`)."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: rate-base-quote
          path: /rate/{base}/{quote}
          operations:
            - name: getRate
              method: GET
              description: Frankfurter Get a Single Exchange Rate Pair
              inputParameters:
                - name: base
                  in: path
                  type: string
                  required: true
                  description: ''
                - name: quote
                  in: path
                  type: string
                  required: true
                  description: ''
                - name: date
                  in: query
                  type: string
                  required: false
                  description: Specific date (YYYY-MM-DD). Cannot be combined with from/to.
                - name: providers
                  in: query
                  type: string
                  required: false
                  description: Comma-separated list of data providers to include
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
  exposes:
    - type: rest
      namespace: v2-rates-rest
      port: 8080
      description: REST adapter for Frankfurter API — Rates. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/rates
          name: v1-rates
          description: REST surface for Frankfurter Get Exchange Rates.
          operations:
            - method: GET
              name: getRates
              description: Frankfurter Get Exchange Rates
              call: v2-rates.getRates
              with:
                date: rest.date
                from: rest.from
                to: rest.to
                base: rest.base
                quotes: rest.quotes
                providers: rest.providers
                group: rest.group
                expand: rest.expand
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/rate/{base}/{quote}
          name: v1-rate-base-quote
          description: REST surface for Frankfurter Get a Single Exchange Rate Pair.
          operations:
            - method: GET
              name: getRate
              description: Frankfurter Get a Single Exchange Rate Pair
              call: v2-rates.getRate
              with:
                base: rest.base
                quote: rest.quote
                date: rest.date
                providers: rest.providers
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      namespace: v2-rates-mcp
      port: 9090
      transport: http
      description: MCP adapter for Frankfurter API — Rates. One verb-noun tool per consumed operation, routed inline through this capability's consumes block.
      tools:
        - name: get-exchange-rates
          description: Frankfurter Get Exchange Rates
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: v2-rates.getRates
          with:
            date: tools.date
            from: tools.from
            to: tools.to
            base: tools.base
            quotes: tools.quotes
            providers: tools.providers
            group: tools.group
            expand: tools.expand
          outputParameters:
            - type: object
              mapping: $.
        - name: get-single-exchange-rate-pair
          description: Frankfurter Get a Single Exchange Rate Pair
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: v2-rates.getRate
          with:
            base: tools.base
            quote: tools.quote
            date: tools.date
            providers: tools.providers
          outputParameters:
            - type: object
              mapping: $.