openapi: 3.1.0
info:
  title: CurrencyBeacon conversion rates API
  description: REST API for real-time and historical currency exchange rates covering 170+ fiat currencies and cryptocurrencies. Sourced from central banks and trusted financial institutions with 30 years of historical data, server-side conversion, timeseries analysis, and 99.99% uptime.
  version: '1'
  termsOfService: https://currencybeacon.com/terms
  contact:
    name: CurrencyBeacon Support
    email: info@currencybeacon.com
    url: https://currencybeacon.com
  license:
    name: Proprietary
    url: https://currencybeacon.com/terms
servers:
- url: https://api.currencybeacon.com/v1
  description: Production API
security:
- ApiKeyQuery: []
- BearerAuth: []
tags:
- name: rates
  description: Currency exchange rate operations
paths:
  /latest:
    get:
      operationId: getLatestRates
      summary: Get latest exchange rates
      description: Returns real-time mid-market exchange rates for the specified base currency. Rates are sourced from central banks and financial institutions. Update frequency depends on plan tier.
      tags:
      - rates
      security:
      - ApiKeyQuery: []
      - BearerAuth: []
      parameters:
      - name: base
        in: query
        required: true
        description: Three-letter ISO 4217 currency code for the base currency. Defaults to USD if not specified.
        schema:
          type: string
          default: USD
          minLength: 3
          maxLength: 3
          example: USD
      - name: symbols
        in: query
        required: false
        description: Comma-separated list of currency codes to return rates for. If omitted, all supported currencies are returned.
        schema:
          type: string
          example: EUR,GBP,JPY
      responses:
        '200':
          description: Successful response with latest exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatestRatesResponse'
              example:
                meta:
                  code: 200
                  disclaimer: Usage subject to terms
                date: '2026-06-13'
                base: USD
                rates:
                  EUR: 0.9185
                  GBP: 0.7862
                  JPY: 157.42
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        5XX:
          $ref: '#/components/responses/ServerError'
  /historical:
    get:
      operationId: getHistoricalRates
      summary: Get historical exchange rates
      description: Returns exchange rates for a specific historical date. CurrencyBeacon provides up to 30 years of historical data.
      tags:
      - rates
      security:
      - ApiKeyQuery: []
      - BearerAuth: []
      parameters:
      - name: date
        in: query
        required: true
        description: The date for which to retrieve historical rates in YYYY-MM-DD format.
        schema:
          type: string
          format: date
          example: '2020-01-01'
      - name: base
        in: query
        required: false
        description: Three-letter ISO 4217 currency code for the base currency. Defaults to USD if not specified.
        schema:
          type: string
          default: USD
          minLength: 3
          maxLength: 3
          example: USD
      - name: symbols
        in: query
        required: false
        description: Comma-separated list of currency codes to return rates for. If omitted, all supported currencies are returned.
        schema:
          type: string
          example: EUR,GBP,JPY
      responses:
        '200':
          description: Successful response with historical exchange rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalRatesResponse'
              example:
                meta:
                  code: 200
                  disclaimer: Usage subject to terms
                date: '2020-01-01'
                base: USD
                rates:
                  EUR: 0.8912
                  GBP: 0.7565
                  JPY: 108.63
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        5XX:
          $ref: '#/components/responses/ServerError'
  /timeseries:
    get:
      operationId: getTimeseries
      summary: Get timeseries exchange rates
      description: Returns exchange rate time-series data between two dates for a given base currency. Available on Startup and Pro plans only.
      tags:
      - rates
      security:
      - ApiKeyQuery: []
      - BearerAuth: []
      parameters:
      - name: start_date
        in: query
        required: true
        description: Start date of the time series in YYYY-MM-DD format.
        schema:
          type: string
          format: date
          example: '2026-01-01'
      - name: end_date
        in: query
        required: true
        description: End date of the time series in YYYY-MM-DD format.
        schema:
          type: string
          format: date
          example: '2026-06-01'
      - name: base
        in: query
        required: false
        description: Three-letter ISO 4217 currency code for the base currency. Defaults to USD if not specified.
        schema:
          type: string
          default: USD
          minLength: 3
          maxLength: 3
          example: USD
      - name: symbols
        in: query
        required: false
        description: Comma-separated list of currency codes to include in the series. If omitted, all supported currencies are returned.
        schema:
          type: string
          example: EUR,GBP
      responses:
        '200':
          description: Successful response with timeseries data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeseriesResponse'
              example:
                meta:
                  code: 200
                  disclaimer: Usage subject to terms
                start_date: '2026-01-01'
                end_date: '2026-01-03'
                base: USD
                rates:
                  '2026-01-01':
                    EUR: 0.9195
                    GBP: 0.787
                  '2026-01-02':
                    EUR: 0.9201
                    GBP: 0.7875
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        5XX:
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Forbidden:
      description: Current plan does not include access to this endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            meta:
              code: 403
              message: Your plan does not include access to this endpoint
    NotFound:
      description: Endpoint or resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            meta:
              code: 404
              message: Resource not found
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            meta:
              code: 401
              message: Invalid or missing API key
    UnprocessableEntity:
      description: Invalid or missing required parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            meta:
              code: 422
              message: Missing required parameter
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            meta:
              code: 429
              message: Rate limit exceeded
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            meta:
              code: 500
              message: Internal server error
  schemas:
    HistoricalRatesResponse:
      type: object
      description: Response for historical exchange rates
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        date:
          type: string
          format: date
          description: The historical date of the rates
          example: '2020-01-01'
        base:
          type: string
          description: Base currency code
          example: USD
        rates:
          type: object
          description: Map of currency codes to exchange rates on the given date
          additionalProperties:
            type: number
            format: double
    LatestRatesResponse:
      type: object
      description: Response for latest exchange rates
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        date:
          type: string
          format: date
          description: Date of the exchange rates
          example: '2026-06-13'
        base:
          type: string
          description: Base currency code
          example: USD
        rates:
          type: object
          description: Map of currency codes to exchange rates
          additionalProperties:
            type: number
            format: double
          example:
            EUR: 0.9185
            GBP: 0.7862
    Meta:
      type: object
      description: Response metadata
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 200
        disclaimer:
          type: string
          description: Usage disclaimer text
          example: Usage subject to terms
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        meta:
          type: object
          properties:
            code:
              type: integer
              description: HTTP error code
            message:
              type: string
              description: Human-readable error message
    TimeseriesResponse:
      type: object
      description: Response for timeseries exchange rates
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        start_date:
          type: string
          format: date
          description: Start date of the time series
          example: '2026-01-01'
        end_date:
          type: string
          format: date
          description: End date of the time series
          example: '2026-06-01'
        base:
          type: string
          description: Base currency code
          example: USD
        rates:
          type: object
          description: Map of dates to rate objects
          additionalProperties:
            type: object
            additionalProperties:
              type: number
              format: double
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as a query parameter.
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the Authorization header.
externalDocs:
  description: CurrencyBeacon API Documentation
  url: https://currencybeacon.com/api-documentation