openapi: 3.1.0
info:
  title: Polygon Forex REST API
  version: '1.0'
  description: |
    Polygon Forex API exposes real-time and historical foreign exchange
    rates for 1,000+ currency pairs via `https://api.polygon.io`. This
    spec covers aggregates, real-time currency conversion, previous-close,
    and last-quote endpoints. Auth uses an API key via `apiKey` query
    parameter or `Authorization: Bearer`.
  contact:
    name: Polygon Documentation
    url: https://polygon.io/docs/forex
servers:
  - url: https://api.polygon.io
    description: Polygon REST API
security:
  - apiKeyQuery: []
  - bearerAuth: []
tags:
  - name: Aggregates
    description: FX aggregate bars.
  - name: Conversion
    description: Real-time currency conversion.
  - name: Quotes
    description: FX quote endpoints.
paths:
  /v2/aggs/ticker/{forexTicker}/range/{multiplier}/{timespan}/{from}/{to}:
    get:
      tags: [Aggregates]
      operationId: getForexAggregateBars
      summary: Get Aggregate Bars For A Forex Pair
      description: Aggregate bars (OHLC) for an FX pair (e.g., C:EURUSD).
      parameters:
        - in: path
          name: forexTicker
          required: true
          schema:
            type: string
        - in: path
          name: multiplier
          required: true
          schema:
            type: integer
        - in: path
          name: timespan
          required: true
          schema:
            type: string
            enum: [minute, hour, day, week, month, quarter, year]
        - in: path
          name: from
          required: true
          schema:
            type: string
        - in: path
          name: to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Forex aggregate bars response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatesResponse'
  /v1/conversion/{from}/{to}:
    get:
      tags: [Conversion]
      operationId: getForexConversion
      summary: Convert From One Currency To Another
      description: Get currency conversion rate and converted amount.
      parameters:
        - in: path
          name: from
          required: true
          schema:
            type: string
            minLength: 3
            maxLength: 3
        - in: path
          name: to
          required: true
          schema:
            type: string
            minLength: 3
            maxLength: 3
        - in: query
          name: amount
          schema:
            type: number
            default: 100
        - in: query
          name: precision
          schema:
            type: integer
            minimum: 0
            maximum: 4
            default: 2
      responses:
        '200':
          description: Conversion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionResponse'
  /v2/aggs/ticker/{forexTicker}/prev:
    get:
      tags: [Aggregates]
      operationId: getForexPreviousClose
      summary: Get Previous Close For A Forex Pair
      parameters:
        - in: path
          name: forexTicker
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Forex previous close response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatesResponse'
  /v1/last_quote/currencies/{from}/{to}:
    get:
      tags: [Quotes]
      operationId: getForexLastQuote
      summary: Get Last Quote For A Currency Pair
      parameters:
        - in: path
          name: from
          required: true
          schema:
            type: string
        - in: path
          name: to
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Last quote response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastQuoteResponse'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    AggregateBar:
      type: object
      properties:
        v:
          type: number
        vw:
          type: number
        o:
          type: number
        c:
          type: number
        h:
          type: number
        l:
          type: number
        t:
          type: integer
          format: int64
        n:
          type: integer
    AggregatesResponse:
      type: object
      properties:
        ticker:
          type: string
        status:
          type: string
        request_id:
          type: string
        resultsCount:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/AggregateBar'
    ConversionResponse:
      type: object
      properties:
        status:
          type: string
        request_id:
          type: string
        from:
          type: string
        to:
          type: string
        initialAmount:
          type: number
        converted:
          type: number
        last:
          type: object
          properties:
            ask:
              type: number
            bid:
              type: number
            exchange:
              type: integer
            timestamp:
              type: integer
              format: int64
    LastQuote:
      type: object
      properties:
        ask:
          type: number
        bid:
          type: number
        exchange:
          type: integer
        timestamp:
          type: integer
          format: int64
    LastQuoteResponse:
      type: object
      properties:
        status:
          type: string
        request_id:
          type: string
        symbol:
          type: string
        last:
          $ref: '#/components/schemas/LastQuote'