openapi: 3.0.3
info:
  title: CurrencyAPI
  description: >-
    CurrencyAPI (currencyapi.com, an Everapi product) is a foreign exchange rate
    and currency conversion REST API. A single versioned surface at
    https://api.currencyapi.com/v3 provides the latest exchange rates, historical
    end-of-day rates back to 1999, time-series ranges with day/hour/quarter-hour/
    minute accuracy, value conversion, currency metadata, and account quota
    status. All endpoints are GET requests authenticated with an API key passed
    either as an "apikey" HTTP header (recommended) or an "apikey" query
    parameter. Only successful calls count against your quota; the status
    endpoint is never counted.
  version: '3.0'
  contact:
    name: CurrencyAPI
    url: https://currencyapi.com
  termsOfService: https://currencyapi.com/terms
servers:
  - url: https://api.currencyapi.com/v3
    description: Production
security:
  - apiKeyHeader: []
  - apiKeyQuery: []
tags:
  - name: Latest
    description: Latest foreign exchange rates.
  - name: Historical
    description: End-of-day historical exchange rates back to 1999.
  - name: Range
    description: Time-series exchange rates for a datetime range.
  - name: Convert
    description: Convert a value between currencies.
  - name: Currencies
    description: Supported currency metadata.
  - name: Status
    description: API health and account quota status.
paths:
  /latest:
    get:
      operationId: getLatestExchangeRates
      tags:
        - Latest
      summary: Latest exchange rates
      description: >-
        Returns the latest exchange rates for the given base currency against
        all available currencies or a selected list. Rate freshness depends on
        plan - daily on Free, hourly on Small, every 60 seconds on Medium and
        above.
      parameters:
        - $ref: '#/components/parameters/baseCurrency'
        - $ref: '#/components/parameters/currencies'
        - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: Latest exchange rates keyed by currency code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
              example:
                meta:
                  last_updated_at: '2023-06-23T10:15:59Z'
                data:
                  AED:
                    code: AED
                    value: 3.67306
                  EUR:
                    code: EUR
                    value: 0.91234
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /historical:
    get:
      operationId: getHistoricalExchangeRates
      tags:
        - Historical
      summary: Historical exchange rates
      description: >-
        Returns end-of-day exchange rates for a specific date. Historical data
        extends back to 1999.
      parameters:
        - name: date
          in: query
          required: true
          description: 'Date to retrieve historical rates from (format: 2021-12-31).'
          schema:
            type: string
            format: date
            example: '2022-01-01'
        - $ref: '#/components/parameters/baseCurrency'
        - $ref: '#/components/parameters/currencies'
        - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: Historical exchange rates for the requested date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
              example:
                meta:
                  last_updated_at: '2022-01-01T23:59:59Z'
                data:
                  AED:
                    code: AED
                    value: 3.67306
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /range:
    get:
      operationId: getRangeExchangeRates
      tags:
        - Range
      summary: Range (time-series) exchange rates
      description: >-
        Returns exchange rate data for a datetime range in a single call.
        Accuracy constraints - day covers up to 366 days of history; hour allows
        a maximum 7-day range up to 3 months back; quarter_hour allows a maximum
        24-hour range up to 7 days back; minute allows a maximum 6-hour range up
        to 7 days back.
      parameters:
        - name: datetime_start
          in: query
          required: true
          description: 'ISO8601 datetime for the start of the range (format: 2022-12-01T00:00:00Z).'
          schema:
            type: string
            format: date-time
            example: '2022-12-01T00:00:00Z'
        - name: datetime_end
          in: query
          required: true
          description: 'ISO8601 datetime for the end of the range (format: 2022-12-31T23:59:59Z).'
          schema:
            type: string
            format: date-time
            example: '2022-12-31T23:59:59Z'
        - name: accuracy
          in: query
          required: false
          description: Accuracy of the time-series data points.
          schema:
            type: string
            enum:
              - day
              - hour
              - quarter_hour
              - minute
            default: day
        - $ref: '#/components/parameters/baseCurrency'
        - $ref: '#/components/parameters/currencies'
        - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: Time-series exchange rate data points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RangeResponse'
              example:
                data:
                  - datetime: '2022-01-01T23:59:59Z'
                    currencies:
                      AED:
                        code: AED
                        value: 3.67306
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /convert:
    get:
      operationId: convertCurrency
      tags:
        - Convert
      summary: Convert a value between currencies
      description: >-
        Converts a monetary value from the base currency into one or more target
        currencies, using today's rates or the rates of a given historical date.
      parameters:
        - name: value
          in: query
          required: true
          description: The value you want to convert.
          schema:
            type: number
            example: 100
        - name: date
          in: query
          required: false
          description: 'Optional historical date to convert with (format: 2021-12-31). Defaults to the latest rates.'
          schema:
            type: string
            format: date
        - $ref: '#/components/parameters/baseCurrency'
        - $ref: '#/components/parameters/currencies'
        - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: Converted values keyed by currency code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
              example:
                meta:
                  last_updated_at: '2022-01-01T23:59:59Z'
                data:
                  AED:
                    code: AED
                    value: 367.306
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /currencies:
    get:
      operationId: listCurrencies
      tags:
        - Currencies
      summary: List supported currencies
      description: >-
        Returns metadata for all supported currencies - symbol, name, native
        symbol, decimal digits, rounding, code, plural name, type, and
        associated countries - optionally filtered by code or type.
      parameters:
        - $ref: '#/components/parameters/currencies'
        - $ref: '#/components/parameters/type'
      responses:
        '200':
          description: Supported currency metadata keyed by currency code.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Currency'
              example:
                data:
                  USD:
                    symbol: $
                    name: US Dollar
                    symbol_native: $
                    decimal_digits: 2
                    rounding: 0
                    code: USD
                    name_plural: US dollars
                    type: fiat
                    countries:
                      - US
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /status:
    get:
      operationId: getStatus
      tags:
        - Status
      summary: API status and quota
      description: >-
        Checks whether the API is up and returns your monthly and grace quota
        usage. Requests to this endpoint do not count against your quota or
        rate limit.
      responses:
        '200':
          description: Account quota status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                account_id: 313373133731337
                quotas:
                  month:
                    total: 300
                    used: 72
                    remaining: 229
                  grace:
                    total: 0
                    used: 0
                    remaining: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: API key passed as an HTTP header (recommended).
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key passed as a query parameter (may expose the key in access logs).
  parameters:
    baseCurrency:
      name: base_currency
      in: query
      required: false
      description: The base currency to which all results are behaving relative to. Defaults to USD.
      schema:
        type: string
        default: USD
        example: USD
    currencies:
      name: currencies
      in: query
      required: false
      description: A list of comma-separated currency codes you want to receive (e.g. EUR,USD,CAD). Defaults to all available currencies.
      schema:
        type: string
        example: EUR,USD,CAD
    type:
      name: type
      in: query
      required: false
      description: The type of currency you want to get. Defaults to all types.
      schema:
        type: string
        enum:
          - fiat
          - metal
          - crypto
  responses:
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation error - incorrect or missing parameters. Failed requests do not count against your quota.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        Monthly quota or per-minute rate limit exceeded. Inspect the
        X-RateLimit-Limit-Quota-Minute, X-RateLimit-Limit-Quota-Month,
        X-RateLimit-Remaining-Quota-Minute, and X-RateLimit-Remaining-Quota-Month
        response headers to monitor consumption.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    RatesResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            last_updated_at:
              type: string
              format: date-time
        data:
          type: object
          description: Exchange rate objects keyed by currency code.
          additionalProperties:
            $ref: '#/components/schemas/Rate'
    RangeResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              datetime:
                type: string
                format: date-time
              currencies:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Rate'
    Rate:
      type: object
      properties:
        code:
          type: string
          description: ISO currency code.
          example: EUR
        value:
          type: number
          description: Exchange rate value relative to the base currency.
          example: 0.91234
    Currency:
      type: object
      properties:
        symbol:
          type: string
        name:
          type: string
        symbol_native:
          type: string
        decimal_digits:
          type: integer
        rounding:
          type: number
        code:
          type: string
        name_plural:
          type: string
        type:
          type: string
          enum:
            - fiat
            - metal
            - crypto
        countries:
          type: array
          items:
            type: string
    StatusResponse:
      type: object
      properties:
        account_id:
          type: integer
          format: int64
        quotas:
          type: object
          properties:
            month:
              $ref: '#/components/schemas/Quota'
            grace:
              $ref: '#/components/schemas/Quota'
    Quota:
      type: object
      properties:
        total:
          type: integer
        used:
          type: integer
        remaining:
          type: integer
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string