roic-ai Forex API

openapi: 3.2.0
info:
  title: ROIC Forex API
  description: The ROIC API reference for v3 (`/v3.0.0`) and legacy v2 (`/v2`). In v3, Bearer authentication is recommended because it keeps credentials out of URLs. For browser testing, you may instead pass your key as the `apikey` query parameter. Use exactly one authentication method per request, never both. v2 takes the key only as the `apikey` query parameter.
  version: 3.0.0
servers:
- url: https://api.roic.ai
tags:
- name: Forex
  description: Currency pair reference data and foreign-exchange rate resources.
paths:
  /v3.0.0/forex-pairs:
    get:
      operationId: listForexPairs
      summary: List forex pairs
      description: Returns a page of tradable currency pairs with their currency codes and human-readable names. Use a pair `symbol` from this list with the forex price endpoints.
      tags:
      - Forex
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: apikey
        in: query
        required: false
        schema:
          description: Browser-friendly alternative to Bearer authentication. Use either this parameter or the Authorization header, never both.
          type: string
      - name: base_currency
        in: query
        required: false
        schema:
          pattern: ^[A-Za-z]{3}$
          minLength: 3
          maxLength: 3
          title: base_currency
          description: Return only pairs quoted from this base currency.
          examples:
          - EUR
          - USD
          - JPY
          type: string
      - name: quote_currency
        in: query
        required: false
        schema:
          pattern: ^[A-Za-z]{3}$
          minLength: 3
          maxLength: 3
          title: quote_currency
          description: Return only pairs quoted into this quote currency.
          examples:
          - EUR
          - USD
          - JPY
          type: string
      - name: currency
        in: query
        required: false
        schema:
          pattern: ^[A-Za-z]{3}$
          minLength: 3
          maxLength: 3
          title: currency
          description: Return every pair in which this currency appears, on either side.
          examples:
          - EUR
          - USD
          - JPY
          type: string
      - name: search
        in: query
        required: false
        schema:
          minLength: 1
          maxLength: 128
          title: search
          description: Case-insensitive substring match against the pair symbol, both currency codes, and the human-readable name.
          examples:
          - yen
          type: string
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        required: false
        schema:
          minimum: 1
          maximum: 2000
          multipleOf: 1
          default: 500
          title: limit
          description: Maximum number of resources to return. Defaults to 500.
          anyOf:
          - format: numeric
            default: 0
            type: string
          - minimum: 1
            maximum: 2000
            multipleOf: 1
            default: 500
            title: limit
            description: Maximum number of resources to return. Defaults to 500.
            type: number
      - name: page
        in: query
        required: false
        schema:
          maxLength: 4096
          description: Opaque page token from a previous response. Prefer following the returned page URLs directly.
          type: string
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.ForexPairList'
        '400':
          description: Response for status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '401':
          description: Response for status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '429':
          description: Response for status 429
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '500':
          description: Response for status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '503':
          description: Response for status 503
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
      x-fern-sdk-group-name: forexPairs
      x-fern-sdk-method-name: list
  /v3.0.0/forex-prices/latest:
    get:
      operationId: listLatestForexPrices
      summary: List latest forex prices
      description: Returns a page with one row per currency pair carrying its latest available daily OHLC quote from the last 10 days. Pairs without a price in that window appear with null price fields. Requires an Individual or higher plan.
      tags:
      - Forex
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: apikey
        in: query
        required: false
        schema:
          description: Browser-friendly alternative to Bearer authentication. Use either this parameter or the Authorization header, never both.
          type: string
      - name: base_currency
        in: query
        required: false
        schema:
          pattern: ^[A-Za-z]{3}$
          minLength: 3
          maxLength: 3
          title: base_currency
          description: Return only pairs quoted from this base currency.
          examples:
          - EUR
          - USD
          - JPY
          type: string
      - name: quote_currency
        in: query
        required: false
        schema:
          pattern: ^[A-Za-z]{3}$
          minLength: 3
          maxLength: 3
          title: quote_currency
          description: Return only pairs quoted into this quote currency.
          examples:
          - EUR
          - USD
          - JPY
          type: string
      - name: currency
        in: query
        required: false
        schema:
          pattern: ^[A-Za-z]{3}$
          minLength: 3
          maxLength: 3
          title: currency
          description: Return every pair in which this currency appears, on either side.
          examples:
          - EUR
          - USD
          - JPY
          type: string
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        required: false
        schema:
          minimum: 1
          maximum: 2000
          multipleOf: 1
          default: 500
          title: limit
          description: Maximum number of resources to return. Defaults to 500.
          anyOf:
          - format: numeric
            default: 0
            type: string
          - minimum: 1
            maximum: 2000
            multipleOf: 1
            default: 500
            title: limit
            description: Maximum number of resources to return. Defaults to 500.
            type: number
      - name: page
        in: query
        required: false
        schema:
          maxLength: 4096
          description: Opaque page token from a previous response. Prefer following the returned page URLs directly.
          type: string
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.LatestForexPriceList'
        '400':
          description: Response for status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '401':
          description: Response for status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '402':
          description: Response for status 402
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '429':
          description: Response for status 429
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '500':
          description: Response for status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '503':
          description: Response for status 503
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
      x-fern-sdk-group-name: forexPrices.latest
      x-fern-sdk-method-name: list
  /v3.0.0/forex-prices/{identifier}:
    get:
      operationId: listHistoricalForexPrices
      summary: List historical forex prices
      description: Returns a page of historical daily prices for a currency pair, addressed by bare currency-pair code or qualified pair symbol.
      tags:
      - Forex
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: identifier
        in: path
        required: true
        schema:
          minLength: 1
          maxLength: 128
          description: A currency pair as `BASEQUOTE` or `BASE/QUOTE`, or a qualified pair symbol (e.g. `FX:EURUSD`). The `symbol` of every `/forex-pairs` result is accepted here.
          examples:
          - EURUSD
          - EUR/USD
          - FX:EURUSD
          type: string
      - name: apikey
        in: query
        required: false
        schema:
          description: Browser-friendly alternative to Bearer authentication. Use either this parameter or the Authorization header, never both.
          type: string
      - name: date
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return prices from exactly this date.
          type: string
      - name: date.gte
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return prices whose date is on or after this date.
          type: string
      - name: date.gt
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return prices whose date is strictly after this date.
          type: string
      - name: date.lte
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return prices whose date is on or before this date.
          type: string
      - name: date.lt
        in: query
        required: false
        schema:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: Return prices whose date is strictly before this date.
          type: string
      - name: order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: limit
        in: query
        required: false
        schema:
          minimum: 1
          maximum: 1000
          multipleOf: 1
          default: 250
          title: limit
          description: Maximum number of resources to return. Defaults to 250.
          anyOf:
          - format: numeric
            default: 0
            type: string
          - minimum: 1
            maximum: 1000
            multipleOf: 1
            default: 250
            title: limit
            description: Maximum number of resources to return. Defaults to 250.
            type: number
      - name: page
        in: query
        required: false
        schema:
          maxLength: 4096
          description: Opaque page token from a previous response. Prefer following the returned page URLs directly.
          type: string
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.ForexPriceList'
        '400':
          description: Response for status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '401':
          description: Response for status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '402':
          description: Response for status 402
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '404':
          description: Response for status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '429':
          description: Response for status 429
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '500':
          description: Response for status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '503':
          description: Response for status 503
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
      x-fern-sdk-group-name: forexPrices
      x-fern-sdk-method-name: list
  /v3.0.0/forex-prices/latest/{identifier}:
    get:
      operationId: retrieveLatestForexPrice
      summary: Retrieve the latest forex price
      description: Returns the latest available daily price for a currency pair, addressed by bare currency-pair code or qualified pair symbol.
      tags:
      - Forex
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: identifier
        in: path
        required: true
        schema:
          minLength: 1
          maxLength: 128
          description: A currency pair as `BASEQUOTE` or `BASE/QUOTE`, or a qualified pair symbol (e.g. `FX:EURUSD`). The `symbol` of every `/forex-pairs` result is accepted here.
          examples:
          - EURUSD
          - EUR/USD
          - FX:EURUSD
          type: string
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.ForexPrice'
        '400':
          description: Response for status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '401':
          description: Response for status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '404':
          description: Response for status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '429':
          description: Response for status 429
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '500':
          description: Response for status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
        '503':
          description: Response for status 503
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v3.Error'
      x-fern-sdk-group-name: forexPrices.latest
      x-fern-sdk-method-name: retrieve
components:
  schemas:
    v3.ForexPairList:
      additionalProperties: false
      type: object
      properties:
        data:
          description: The forex pairs in this page.
          type: array
          items:
            additionalProperties: false
            type: object
            properties:
              symbol:
                description: The qualified pair symbol, e.g. `FX:EURUSD`. Accepted by the forex price endpoints.
                type: string
              name:
                description: The human-readable pair name, e.g. `EURO / U.S. DOLLAR`.
                type: string
              base_currency:
                description: ISO code of the currency being priced.
                type: string
              base_currency_name:
                anyOf:
                - type: string
                - type: 'null'
              quote_currency:
                description: ISO code of the currency the pair is priced in.
                type: string
              quote_currency_name:
                anyOf:
                - type: string
                - type: 'null'
              is_synthetic:
                description: True when the pair is derived from other quoted pairs rather than quoted directly.
                type: boolean
            required:
            - symbol
            - name
            - base_currency
            - base_currency_name
            - quote_currency
            - quote_currency_name
            - is_synthetic
            $id: '#/components/schemas/v3.ForexPair'
        next_page_url:
          description: URL for the next page, or null when this is the last page.
          anyOf:
          - type: string
          - type: 'null'
        previous_page_url:
          description: URL for the previous page, or null when this is the first page.
          anyOf:
          - type: string
          - type: 'null'
      required:
      - data
      - next_page_url
      - previous_page_url
      $id: '#/components/schemas/v3.ForexPairList'
    v3.LatestForexPriceList:
      additionalProperties: false
      type: object
      properties:
        data:
          description: The latest prices in this page, one row per pair.
          type: array
          items:
            additionalProperties: false
            type: object
            properties:
              symbol:
                description: The qualified pair symbol this quote belongs to, e.g. `FX:EURUSD`.
                type: string
              date:
                description: Quote date of the latest available price, or null when the pair has no price inside the freshness window.
                anyOf:
                - pattern: ^\d{4}-\d{2}-\d{2}$
                  minLength: 10
                  maxLength: 10
                  description: A calendar date in YYYY-MM-DD format.
                  type: string
                - type: 'null'
              open:
                anyOf:
                - type: number
                - type: 'null'
              high:
                anyOf:
                - type: number
                - type: 'null'
              low:
                anyOf:
                - type: number
                - type: 'null'
              close:
                anyOf:
                - type: number
                - type: 'null'
            required:
            - symbol
            - date
            - open
            - high
            - low
            - close
            $id: '#/components/schemas/v3.LatestForexPrice'
        next_page_url:
          description: URL for the next page, or null when this is the last page.
          anyOf:
          - type: string
          - type: 'null'
        previous_page_url:
          description: URL for the previous page, or null when this is the first page.
          anyOf:
          - type: string
          - type: 'null'
      required:
      - data
      - next_page_url
      - previous_page_url
      $id: '#/components/schemas/v3.LatestForexPriceList'
    v3.ForexPriceList:
      additionalProperties: false
      type: object
      properties:
        data:
          description: The forex prices in this page.
          type: array
          items:
            additionalProperties: false
            type: object
            properties:
              date:
                pattern: ^\d{4}-\d{2}-\d{2}$
                minLength: 10
                maxLength: 10
                description: A calendar date in YYYY-MM-DD format.
                type: string
              open:
                anyOf:
                - type: number
                - type: 'null'
              high:
                anyOf:
                - type: number
                - type: 'null'
              low:
                anyOf:
                - type: number
                - type: 'null'
              close:
                type: number
            required:
            - date
            - open
            - high
            - low
            - close
            $id: '#/components/schemas/v3.ForexPricePoint'
        symbol:
          description: The qualified pair symbol every quote in `data` belongs to, e.g. `FX:EURUSD`. Present even when `data` is empty.
          type: string
        next_page_url:
          description: URL for the next page, or null when this is the last page.
          anyOf:
          - type: string
          - type: 'null'
        previous_page_url:
          description: URL for the previous page, or null when this is the first page.
          anyOf:
          - type: string
          - type: 'null'
      required:
      - data
      - symbol
      - next_page_url
      - previous_page_url
      $id: '#/components/schemas/v3.ForexPriceList'
    v3.Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - invalid_request_error
              - authentication_error
              - payment_required_error
              - conflict_error
              - rate_limit_error
              - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            doc_url:
              type: string
            request_id:
              type: string
          required:
          - type
          - code
          - message
          - request_id
      required:
      - error
      $id: '#/components/schemas/v3.Error'
    v3.ForexPrice:
      additionalProperties: false
      type: object
      properties:
        symbol:
          description: The qualified pair symbol these quotes belong to, e.g. `FX:EURUSD`.
          type: string
        date:
          pattern: ^\d{4}-\d{2}-\d{2}$
          minLength: 10
          maxLength: 10
          description: A calendar date in YYYY-MM-DD format.
          type: string
        open:
          anyOf:
          - type: number
          - type: 'null'
        high:
          anyOf:
          - type: number
          - type: 'null'
        low:
          anyOf:
          - type: number
          - type: 'null'
        close:
          type: number
      required:
      - symbol
      - date
      - open
      - high
      - low
      - close
      $id: '#/components/schemas/v3.ForexPrice'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Recommended. Send your ROIC API key as a Bearer token.
    apiKeyAuth:
      type: apiKey
      in: query
      name: apikey
      description: Browser-friendly alternative. Do not combine this query parameter with the Authorization header.