openapi: 3.0.3
info:
  title: 1Forge Forex Data Convert API
  description: '1Forge provides real-time bid and ask quote data for 700+ forex and cryptocurrency

    currency pairs, delivered with FIX-grade speed over a simple JSON REST API. The

    REST surface covers five operations: list available symbols, fetch quotes for one

    or more pairs, convert a quantity between two currencies, check whether the market

    is currently open, and inspect remaining quota for the calling API key.


    1Forge connects directly to brokers and liquidity providers and serves traffic from

    four global edge locations (Oregon, Virginia, Taiwan, Belgium). Streaming over

    WebSocket is documented separately in `asyncapi/1forge-forex-stream-asyncapi.yml`.'
  version: '2024.01'
  contact:
    name: 1Forge Support
    email: contact@1forge.com
    url: https://1forge.com/forex-data-api
  license:
    name: 1Forge Forex API Terms of Use
    url: https://1forge.com/terms
  termsOfService: https://1forge.com/terms
  x-generated-from: documentation
  x-last-validated: '2026-05-28'
servers:
- url: https://api.1forge.com
  description: 1Forge production REST endpoint (auto-routed to nearest edge).
security:
- ApiKeyAuth: []
tags:
- name: Convert
  description: Convert a quantity from one currency into another at the current rate.
paths:
  /convert:
    get:
      operationId: convertCurrency
      summary: 1Forge Convert Currency Amount
      description: 'Converts a numeric quantity from one currency to another at the current rate.

        Returns the converted value, a human-readable string, and the conversion

        timestamp.'
      tags:
      - Convert
      parameters:
      - name: from
        in: query
        required: true
        description: ISO 4217 source currency code (e.g. `USD`).
        schema:
          type: string
          minLength: 3
          maxLength: 3
        example: USD
      - name: to
        in: query
        required: true
        description: ISO 4217 destination currency code (e.g. `EUR`).
        schema:
          type: string
          minLength: 3
          maxLength: 3
        example: EUR
      - name: quantity
        in: query
        required: true
        description: Numeric amount of the source currency to convert.
        schema:
          type: number
          format: double
        example: 100
      - name: api_key
        in: query
        required: true
        description: Your 1Forge API key.
        schema:
          type: string
        example: YOUR_API_KEY
      responses:
        '200':
          description: Conversion result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionResult'
              examples:
                ConvertCurrency200Example:
                  summary: Default convertCurrency 200 response
                  x-microcks-default: true
                  value:
                    value: 89.3164183
                    text: 100 USD is worth 89.3164183 EUR
                    timestamp: 1497186516
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Error:
      title: Error
      description: Generic error returned when authentication fails or the request is invalid.
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: boolean
          description: Always true for error responses.
          example: true
        message:
          type: string
          description: Human-readable error description.
          example: API Key Not Valid. Please go to 1forge.com to get an API key.
    ConversionResult:
      title: ConversionResult
      description: Result of a currency conversion at the current market rate.
      type: object
      required:
      - value
      - text
      - timestamp
      properties:
        value:
          type: number
          format: double
          description: Converted amount in the destination currency.
          example: 89.3164183
        text:
          type: string
          description: Human-readable conversion string.
          example: 100 USD is worth 89.3164183 EUR
        timestamp:
          type: integer
          format: int64
          description: Unix epoch timestamp (seconds) of the conversion rate.
          example: 1497186516
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: '1Forge requires an API key passed as the `api_key` query parameter on every

        request. Obtain a key at https://1forge.com.'