openapi: 3.0.3
info:
  title: FXRatesAPI
  description: >-
    FXRatesAPI is a foreign exchange rates REST API serving real-time and
    historical currency exchange rates for 185+ fiat currencies plus major
    cryptocurrencies and precious metals. All endpoints return JSON over HTTPS
    from the base host https://api.fxratesapi.com. A limited tier is usable
    without an API key; a paid API key (passed as the api_key query parameter or
    an Authorization Bearer header) raises quotas, increases update frequency,
    and unlocks base-currency switching.


    Endpoint paths, methods, and parameters below are grounded in live probes of
    the API on 2026-07-12. Response schemas are modeled from the observed JSON
    payloads rather than a provider-published machine-readable schema, and only
    parameters confirmed during probing are asserted; additional optional
    parameters may exist.
  version: '1.0'
  contact:
    name: FXRatesAPI
    url: https://fxratesapi.com
  termsOfService: https://fxratesapi.com/legal/terms-conditions
servers:
  - url: https://api.fxratesapi.com
    description: FXRatesAPI production
security:
  - {}
  - apiKeyQuery: []
  - bearerAuth: []
tags:
  - name: Latest Rates
    description: Most recent exchange rates for a base currency.
  - name: Historical Rates
    description: Exchange rates for a specific past date.
  - name: Time-Series
    description: Daily exchange rates across a date range.
  - name: Convert
    description: Convert an amount between two currencies.
  - name: Currencies
    description: List of supported currencies and their metadata.
paths:
  /latest:
    get:
      operationId: getLatestRates
      tags:
        - Latest Rates
      summary: Get the latest exchange rates
      description: >-
        Returns the most recent exchange rates for the requested base currency.
        Confirmed to respond with HTTP 200 without an API key for a limited tier.
      parameters:
        - name: base
          in: query
          required: false
          description: Base currency code (ISO 4217). Defaults to USD.
          schema:
            type: string
            default: USD
            example: EUR
        - name: currencies
          in: query
          required: false
          description: Comma-separated list of currency codes to return. Defaults to all supported currencies.
          schema:
            type: string
            example: USD,GBP
        - name: api_key
          in: query
          required: false
          description: Optional API key. May also be supplied via the Authorization Bearer header.
          schema:
            type: string
      responses:
        '200':
          description: Latest exchange rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '400':
          $ref: '#/components/responses/Error'
  /historical:
    get:
      operationId: getHistoricalRates
      tags:
        - Historical Rates
      summary: Get historical exchange rates for a date
      description: Returns the exchange rates as they were on a specific past date.
      parameters:
        - name: date
          in: query
          required: true
          description: The date to retrieve rates for, in YYYY-MM-DD format.
          schema:
            type: string
            format: date
            example: '2026-01-01'
        - name: base
          in: query
          required: false
          description: Base currency code (ISO 4217). Defaults to USD.
          schema:
            type: string
            default: USD
        - name: currencies
          in: query
          required: false
          description: Comma-separated list of currency codes to return.
          schema:
            type: string
        - name: api_key
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Historical exchange rates for the requested date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '400':
          $ref: '#/components/responses/Error'
  /timeseries:
    get:
      operationId: getTimeSeriesRates
      tags:
        - Time-Series
      summary: Get time-series exchange rates
      description: Returns daily exchange rates for each date across the requested range.
      parameters:
        - name: start_date
          in: query
          required: true
          description: Range start date in YYYY-MM-DD format.
          schema:
            type: string
            format: date
            example: '2026-01-01'
        - name: end_date
          in: query
          required: true
          description: Range end date in YYYY-MM-DD format.
          schema:
            type: string
            format: date
            example: '2026-01-05'
        - name: base
          in: query
          required: false
          description: Base currency code (ISO 4217). Defaults to USD.
          schema:
            type: string
            default: USD
        - name: currencies
          in: query
          required: false
          description: Comma-separated list of currency codes to return.
          schema:
            type: string
            example: EUR
        - name: api_key
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Date-keyed exchange rates across the range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
        '400':
          $ref: '#/components/responses/Error'
  /convert:
    get:
      operationId: convertCurrency
      tags:
        - Convert
      summary: Convert an amount between currencies
      description: >-
        Converts an amount from one currency to another using the latest rate,
        or a historical rate when a date is supplied.
      parameters:
        - name: from
          in: query
          required: true
          description: Source currency code (ISO 4217).
          schema:
            type: string
            example: USD
        - name: to
          in: query
          required: true
          description: Target currency code (ISO 4217).
          schema:
            type: string
            example: EUR
        - name: amount
          in: query
          required: true
          description: Amount of the source currency to convert.
          schema:
            type: number
            example: 100
        - name: date
          in: query
          required: false
          description: Optional date (YYYY-MM-DD) to convert at a historical rate.
          schema:
            type: string
            format: date
        - name: api_key
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Conversion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertResponse'
        '400':
          $ref: '#/components/responses/Error'
  /currencies:
    get:
      operationId: listCurrencies
      tags:
        - Currencies
      summary: List supported currencies
      description: >-
        Returns an object keyed by currency code, each value describing the
        currency's code, name, plural name, symbol, native symbol, decimal
        digits, and rounding. Confirmed live returning 185 entries.
      responses:
        '200':
          description: Map of supported currencies.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Currency'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as the api_key query parameter.
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key passed as an Authorization: Bearer <API_KEY> header.'
  responses:
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    RatesResponse:
      type: object
      description: Modeled from observed /latest and /historical JSON payloads.
      properties:
        success:
          type: boolean
          example: true
        terms:
          type: string
          example: https://fxratesapi.com/legal/terms-conditions
        privacy:
          type: string
          example: https://fxratesapi.com/legal/privacy-policy
        timestamp:
          type: integer
          description: Unix timestamp of the rate snapshot.
          example: 1783883940
        date:
          type: string
          format: date-time
          example: '2026-07-12T19:19:00.000Z'
        base:
          type: string
          example: USD
        rates:
          type: object
          description: Map of currency code to exchange rate against the base.
          additionalProperties:
            type: number
          example:
            EUR: 0.8761481387
            GBP: 0.7461771444
    TimeSeriesResponse:
      type: object
      description: Modeled from the observed /timeseries JSON payload.
      properties:
        success:
          type: boolean
          example: true
        base:
          type: string
          example: USD
        start_date:
          type: string
          format: date-time
          example: '2026-01-01T00:00:00.000Z'
        end_date:
          type: string
          format: date-time
          example: '2026-01-05T00:00:00.000Z'
        rates:
          type: object
          description: Map of date-time to a map of currency code and rate.
          additionalProperties:
            type: object
            additionalProperties:
              type: number
          example:
            '2026-01-04T23:59:00.000Z':
              EUR: 0.854400106
    ConvertResponse:
      type: object
      description: Modeled from the observed /convert JSON payload.
      properties:
        success:
          type: boolean
          example: true
        query:
          type: object
          properties:
            from:
              type: string
              example: USD
            to:
              type: string
              example: EUR
            amount:
              type: number
              example: 100
        info:
          type: object
          properties:
            rate:
              type: number
              example: 0.8511001313
        historical:
          type: boolean
          example: false
        date:
          type: string
          format: date-time
          example: '2026-01-01T23:59:00.000Z'
        timestamp:
          type: integer
          example: 1767311940
        result:
          type: number
          example: 85.11001313
    Currency:
      type: object
      description: Modeled from the observed /currencies JSON payload.
      properties:
        code:
          type: string
          example: EUR
        name:
          type: string
          example: Euro
        decimal_digits:
          type: integer
          example: 2
        name_plural:
          type: string
          example: euros
        rounding:
          type: number
          example: 0
        symbol:
          type: string
          example: "€"
        symbol_native:
          type: string
          example: "€"
    ErrorResponse:
      type: object
      description: >-
        Modeled from observed error payloads. FXRatesAPI returns success=false
        with either a nested error object ({message}) or a flat error string plus
        a description field, depending on the endpoint and failure mode.
      properties:
        success:
          type: boolean
          example: false
        error:
          oneOf:
            - type: string
              example: missing_from_currency
            - type: object
              properties:
                message:
                  type: string
                  example: Endpoint Not Found
        description:
          type: string
          example: The from currency is required for the convert endpoint.