openapi: 3.0.3
info:
  title: 1Forge Forex Data 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).
tags:
  - name: Quotes
    description: Real-time bid/ask quote data for forex and cryptocurrency pairs.
  - name: Convert
    description: Convert a quantity from one currency into another at the current rate.
  - name: Symbols
    description: Discover the currency pairs available to the calling API key.
  - name: Market Status
    description: Check whether the forex market is currently open.
  - name: Quota
    description: Inspect API key consumption and remaining quota.
security:
  - ApiKeyAuth: []
paths:
  /quotes:
    get:
      operationId: getQuotes
      summary: 1Forge Get Quotes for Pairs
      description: |-
        Returns the latest bid, ask, and price data for one or more currency pairs.
        Pairs are supplied as a comma-separated list. Either `EUR/USD` or `EURUSD`
        notation is accepted. Responses are an array of `Quote` objects in the order
        the pairs were requested.
      tags:
        - Quotes
      parameters:
        - name: pairs
          in: query
          required: true
          description: Comma-separated list of currency pair symbols (e.g. `EUR/USD,GBP/JPY,AUD/USD`).
          schema:
            type: string
          example: EUR/USD,GBP/JPY,AUD/USD
        - name: api_key
          in: query
          required: true
          description: Your 1Forge API key. Obtain one at https://1forge.com.
          schema:
            type: string
          example: YOUR_API_KEY
      responses:
        '200':
          description: Array of `Quote` records, one per requested currency pair.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Quote'
              examples:
                GetQuotes200Example:
                  summary: Default getQuotes 200 response
                  x-microcks-default: true
                  value:
                    - s: EUR/USD
                      p: 1.181
                      b: 1.18099
                      a: 1.18101
                      t: 1502160794
                    - s: GBP/JPY
                      p: 144.3715
                      b: 144.368
                      a: 144.375
                      t: 1502160794
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /symbols:
    get:
      operationId: getSymbols
      summary: 1Forge List Available Symbols
      description: |-
        Returns the full list of currency pair symbols available to the calling API
        key. Symbols are expressed in `BASE/QUOTE` notation (e.g. `EUR/USD`).
      tags:
        - Symbols
      parameters:
        - name: api_key
          in: query
          required: true
          description: Your 1Forge API key.
          schema:
            type: string
          example: YOUR_API_KEY
      responses:
        '200':
          description: Array of currency pair symbols.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: Currency pair in `BASE/QUOTE` notation.
                  example: EUR/USD
              examples:
                GetSymbols200Example:
                  summary: Default getSymbols 200 response
                  x-microcks-default: true
                  value:
                    - AUD/JPY
                    - AUD/USD
                    - CHF/JPY
                    - EUR/AUD
                    - EUR/CAD
                    - EUR/CHF
                    - EUR/GBP
                    - EUR/JPY
                    - EUR/USD
                    - GBP/AUD
                    - GBP/CAD
                    - GBP/CHF
                    - GBP/JPY
                    - NZD/JPY
                    - NZD/USD
                    - USD/CAD
                    - USD/CHF
                    - USD/JPY
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /market_status:
    get:
      operationId: getMarketStatus
      summary: 1Forge Check Market Open Status
      description: |-
        Returns a boolean indicating whether the forex market is currently open. The
        forex market is closed on weekends.
      tags:
        - Market Status
      parameters:
        - name: api_key
          in: query
          required: true
          description: Your 1Forge API key.
          schema:
            type: string
          example: YOUR_API_KEY
      responses:
        '200':
          description: Market open/closed status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketStatus'
              examples:
                GetMarketStatus200Example:
                  summary: Default getMarketStatus 200 response
                  x-microcks-default: true
                  value:
                    market_is_open: true
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /quota:
    get:
      operationId: getQuota
      summary: 1Forge Get API Key Quota
      description: |-
        Returns the calling API key's current usage and remaining quota for the
        billing window, along with the number of hours until quota resets.
      tags:
        - Quota
      parameters:
        - name: api_key
          in: query
          required: true
          description: Your 1Forge API key.
          schema:
            type: string
          example: YOUR_API_KEY
      responses:
        '200':
          description: Quota usage information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quota'
              examples:
                GetQuota200Example:
                  summary: Default getQuota 200 response
                  x-microcks-default: true
                  value:
                    quota_used: 259
                    quota_limit: 5000
                    quota_remaining: 4741
                    hours_until_reset: 23
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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.
  schemas:
    Quote:
      title: Quote
      description: A single bid/ask/price snapshot for a forex or cryptocurrency pair.
      type: object
      required:
        - s
        - p
        - b
        - a
        - t
      properties:
        s:
          type: string
          description: Currency pair symbol in `BASE/QUOTE` notation.
          example: EUR/USD
        p:
          type: number
          format: double
          description: Last traded price (midpoint of bid/ask).
          example: 1.181
        b:
          type: number
          format: double
          description: Current bid price.
          example: 1.18099
        a:
          type: number
          format: double
          description: Current ask price.
          example: 1.18101
        t:
          type: integer
          format: int64
          description: Unix epoch timestamp (seconds) of the quote.
          example: 1502160794
    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
    MarketStatus:
      title: MarketStatus
      description: Open/closed status of the forex market.
      type: object
      required:
        - market_is_open
      properties:
        market_is_open:
          type: boolean
          description: True when the forex market is currently open, false otherwise.
          example: true
    Quota:
      title: Quota
      description: Current API key consumption against the plan quota.
      type: object
      required:
        - quota_used
        - quota_limit
        - quota_remaining
        - hours_until_reset
      properties:
        quota_used:
          type: integer
          format: int64
          description: Number of requests consumed in the current billing window.
          example: 259
        quota_limit:
          type: integer
          format: int64
          description: Total request quota for the current billing window.
          example: 5000
        quota_remaining:
          type: integer
          format: int64
          description: Requests remaining in the current billing window.
          example: 4741
        hours_until_reset:
          type: integer
          description: Hours until the quota resets.
          example: 23
    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.