openapi: 3.2.0
info:
  title: FX Macrodata Monetary Policy API
  description: Official-source macroeconomic indicators, release calendars, central-bank policy rates, FX reference rates, COT positioning and commodities across 22 currencies. USD data is available without an API key; other currencies and datasets need an `X-API-Key` header.
  version: 1.0.0
servers:
- url: https://api.fxmacrodata.com
  description: FXMacroData API
security:
- {}
- APIKeyHeader: []
- HTTPBearer: []
tags:
- name: monetary_policy
paths:
  /v1/financial_prices/{currency}:
    get:
      tags:
      - monetary_policy
      summary: Official financial prices and yield curves
      description: Official government and central-bank observations. Filter by source, issuer, instrument or measure. Separate nominal, real, par, zero, security quotes and auction observations by their dimensions. Source attribution and licence conditions accompany the data. Empty coverage means no observations are available yet.
      operationId: get_financial_prices_v1_financial_prices__currency__get
      parameters:
      - name: currency
        in: path
        required: true
        schema:
          type: string
          title: Currency
        description: Required path parameter.
      - name: source
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Source
        description: Optional query parameter.
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Start Date
        description: Optional query parameter.
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: End Date
        description: Optional query parameter.
      - name: measure
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 60
          - type: 'null'
          title: Measure
        description: Optional query parameter.
      - name: instrument_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 240
          - type: 'null'
          title: Instrument Id
        description: Optional query parameter.
      - name: issuer
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 240
          - type: 'null'
          title: Issuer
        description: Optional query parameter.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 100
          title: Limit
        description: Optional query parameter.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
        description: Optional query parameter.
      - name: api_key
        in: query
        required: false
        schema:
          type: string
          description: Your Individual or Business API key
          title: Api Key
        description: 'Deprecated: legacy query-string API key. Still accepted so existing integrations keep working, but new integrations must send the key in the X-API-Key header (or Authorization: Bearer). A key is required for non-USD, paid-only, or full-history requests. Responses to requests authenticated this way carry a Deprecation header.'
        deprecated: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialPriceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FinancialPagination:
      properties:
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        returned_count:
          type: integer
          title: Returned Count
        total_count:
          type: integer
          title: Total Count
        has_more:
          type: boolean
          title: Has More
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Offset
      type: object
      required:
      - limit
      - offset
      - returned_count
      - total_count
      - has_more
      title: FinancialPagination
    FinancialSource:
      properties:
        id:
          type: string
          title: Id
        currency:
          type: string
          title: Currency
        publisher:
          type: string
          title: Publisher
        url:
          type: string
          title: Url
        license_url:
          anyOf:
          - type: string
          - type: 'null'
          title: License Url
        attribution:
          type: string
          title: Attribution
        frequency:
          anyOf:
          - type: string
          - type: 'null'
          title: Frequency
        publication_frequency:
          anyOf:
          - type: string
          - type: 'null'
          title: Publication Frequency
        history_start:
          anyOf:
          - type: string
          - type: 'null'
          title: History Start
        measures:
          items:
            type: string
          type: array
          title: Measures
        dataset_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Dataset Name
        license:
          anyOf:
          - type: string
          - type: 'null'
          title: License
        reuse_conditions:
          anyOf:
          - type: string
          - type: 'null'
          title: Reuse Conditions
      type: object
      required:
      - id
      - currency
      - publisher
      - url
      - attribution
      - measures
      title: FinancialSource
    FinancialPriceResponse:
      properties:
        currency:
          type: string
          title: Currency
        start_date:
          type: string
          title: Start Date
        end_date:
          type: string
          title: End Date
        sources:
          items:
            $ref: '#/components/schemas/FinancialSource'
          type: array
          title: Sources
        coverage:
          items:
            $ref: '#/components/schemas/FinancialCoverage'
          type: array
          title: Coverage
        pagination:
          $ref: '#/components/schemas/FinancialPagination'
        data:
          items:
            $ref: '#/components/schemas/FinancialObservation'
          type: array
          title: Data
      type: object
      required:
      - currency
      - start_date
      - end_date
      - sources
      - coverage
      - pagination
      - data
      title: FinancialPriceResponse
    FinancialCoverage:
      properties:
        source_id:
          type: string
          title: Source Id
        available:
          type: boolean
          title: Available
          description: Whether observations are available for this source; a listed source without observations is not yet available.
        first_observation:
          anyOf:
          - type: string
          - type: 'null'
          title: First Observation
        last_observation:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Observation
        last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated
        source_accessed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Accessed At
      type: object
      required:
      - source_id
      - available
      title: FinancialCoverage
    FinancialObservation:
      properties:
        observation_id:
          type: string
          title: Observation Id
          description: Stable identity of the source, observation date, instrument and quote dimensions.
        source_id:
          type: string
          title: Source Id
        date:
          type: string
          title: Date
          description: Source observation date; not an inferred publication date.
        val:
          type: number
          title: Val
          description: Official numerical value in unit, retaining source precision.
        currency:
          type: string
          title: Currency
        issuer:
          type: string
          title: Issuer
          description: Issuer, official benchmark administrator, or explicitly identified market/curve basket.
        instrument_id:
          type: string
          title: Instrument Id
        instrument_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Instrument Name
        source_series_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Series Id
        measure:
          type: string
          title: Measure
        unit:
          type: string
          title: Unit
        source_url:
          type: string
          title: Source Url
        basis:
          anyOf:
          - type: string
          - type: 'null'
          title: Basis
        curve_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Curve Type
        tenor:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenor
        maturity_years:
          anyOf:
          - type: number
          - type: 'null'
          title: Maturity Years
        maturity_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Maturity Date
        price_side:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Side
        price_basis:
          anyOf:
          - type: string
          - type: 'null'
          title: Price Basis
        price_denominator:
          anyOf:
          - type: number
          - type: 'null'
          title: Price Denominator
        coupon_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Coupon Rate
        quote_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Quote Type
        yield_convention:
          anyOf:
          - type: string
          - type: 'null'
          title: Yield Convention
        reference_rate:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Rate
        inflation_index:
          anyOf:
          - type: string
          - type: 'null'
          title: Inflation Index
        compounding:
          anyOf:
          - type: string
          - type: 'null'
          title: Compounding
        averaging_period_months:
          anyOf:
          - type: number
          - type: 'null'
          title: Averaging Period Months
        percentile:
          anyOf:
          - type: number
          - type: 'null'
          title: Percentile
        publication_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Publication Date
        source_publication_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Publication Date
        source_value_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Value Date
        rate_period_start:
          anyOf:
          - type: string
          - type: 'null'
          title: Rate Period Start
        rate_period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Rate Period End
        observation_period_start:
          anyOf:
          - type: string
          - type: 'null'
          title: Observation Period Start
        observation_period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Observation Period End
        observation_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Observation Status
        announcement_datetime:
          anyOf:
          - type: integer
          - type: 'null'
          title: Announcement Datetime
          description: Publication epoch seconds when available. A scheduled hour is explicitly assumed.
        publication_time_confirmed:
          type: boolean
          title: Publication Time Confirmed
        release_time_assumed:
          type: boolean
          title: Release Time Assumed
        point_in_time_safe:
          type: boolean
          title: Point In Time Safe
          description: True only when the source supplied exact publication-time evidence.
      additionalProperties: true
      type: object
      required:
      - observation_id
      - source_id
      - date
      - val
      - currency
      - issuer
      - instrument_id
      - measure
      - unit
      - source_url
      - publication_time_confirmed
      - release_time_assumed
      - point_in_time_safe
      title: FinancialObservation
      description: One official instrument/measure observation, retaining source dimensions.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'FXMacroData API key. Preferred transport for server-side clients: the key stays out of URLs and access logs.'
    HTTPBearer:
      type: http
      scheme: bearer
      description: 'FXMacroData API key or OAuth access token supplied as ``Authorization: Bearer <key>``.'
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
      x-deprecated: true
      description: 'Deprecated. FXMacroData API key as a query parameter. Still accepted so existing integrations keep working, but new integrations must use the X-API-Key header (APIKeyHeader) or Authorization: Bearer. The only exception is browser EventSource clients of the live-delivery streams, which cannot set request headers.'