openapi: 3.0.3
info:
  title: Treasury Fiscal Data Exchange Rates API
  description: The U.S. Treasury Fiscal Data API provides free, open access to federal financial data including national debt, interest rates, exchange rates, and detailed fiscal operations data. No authentication or API key is required. The API uses RESTful principles, accepts GET requests, and returns JSON responses with standardized pagination, filtering, sorting, and field selection across 80+ endpoints covering all major Treasury financial reports.
  version: '1.0'
  contact:
    name: Bureau of the Fiscal Service
    url: https://fiscaldata.treasury.gov/
    email: FiscalDataHelp@fiscal.treasury.gov
  license:
    name: Public Domain (U.S. Government Work)
    url: https://fiscaldata.treasury.gov/about-us/
  x-generated-from: documentation
servers:
- url: https://api.fiscaldata.treasury.gov/services/api/fiscal_service
  description: Treasury Fiscal Data API
tags:
- name: Exchange Rates
  description: Treasury reporting rates of exchange for foreign currencies.
paths:
  /v1/accounting/od/rates_of_exchange:
    get:
      operationId: getRatesOfExchange
      summary: Treasury Fiscal Data Get Treasury Reporting Rates of Exchange
      description: Retrieve official Treasury foreign currency exchange rates used for reporting purposes. Published quarterly and includes historical data back to 1956. Each record includes country, currency name, exchange rate, and effective date.
      tags:
      - Exchange Rates
      parameters:
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Successful response with exchange rate data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeRateResponse'
              examples:
                GetRatesOfExchange200Example:
                  summary: Default getRatesOfExchange 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - country: Afghanistan
                      currency: Afghani
                      exchange_rate: '64.77'
                      record_date: '2026-03-31'
                    meta:
                      count: 1
                      total-count: 18804
                      total-pages: 18804
                    links:
                      self: '&page%5Bnumber%5D=1&page%5Bsize%5D=1'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ExchangeRateRecord:
      title: ExchangeRateRecord
      type: object
      description: A single exchange rate record from the Treasury Reporting Rates dataset.
      properties:
        country:
          type: string
          description: Country name.
          example: Afghanistan
        currency:
          type: string
          description: Currency name.
          example: Afghani
        exchange_rate:
          type: string
          description: Exchange rate (units of foreign currency per USD).
          example: '64.77'
        effective_date:
          type: string
          format: date
          description: Date the exchange rate became effective.
          example: '2026-03-31'
        record_date:
          type: string
          format: date
          description: Record date in YYYY-MM-DD format.
          example: '2026-03-31'
    FiscalLinks:
      title: FiscalLinks
      type: object
      description: Pagination links for navigating result pages.
      properties:
        self:
          type: string
          description: URL parameters for the current page.
          example: '&page%5Bnumber%5D=1&page%5Bsize%5D=100'
        first:
          type: string
          description: URL parameters for the first page.
          example: '&page%5Bnumber%5D=1&page%5Bsize%5D=100'
        prev:
          type: string
          nullable: true
          description: URL parameters for the previous page (null if on first page).
          example: null
        next:
          type: string
          nullable: true
          description: URL parameters for the next page (null if on last page).
          example: '&page%5Bnumber%5D=2&page%5Bsize%5D=100'
        last:
          type: string
          description: URL parameters for the last page.
          example: '&page%5Bnumber%5D=83&page%5Bsize%5D=100'
    ExchangeRateResponse:
      title: ExchangeRateResponse
      type: object
      description: Response from the Exchange Rates endpoint.
      properties:
        data:
          type: array
          description: Array of exchange rate records.
          items:
            $ref: '#/components/schemas/ExchangeRateRecord'
        meta:
          $ref: '#/components/schemas/FiscalMeta'
        links:
          $ref: '#/components/schemas/FiscalLinks'
    FiscalMeta:
      title: FiscalMeta
      type: object
      description: Metadata included in all Treasury Fiscal Data API responses.
      properties:
        count:
          type: integer
          description: Number of records in this response page.
          example: 100
        labels:
          type: object
          description: Human-readable labels for each field in the data.
          additionalProperties:
            type: string
          example:
            record_date: Record Date
            tot_pub_debt_out_amt: Total Public Debt Outstanding
        dataTypes:
          type: object
          description: Data type for each field (DATE, STRING, CURRENCY, NUMBER, PERCENTAGE).
          additionalProperties:
            type: string
          example:
            record_date: DATE
            tot_pub_debt_out_amt: CURRENCY
        dataFormats:
          type: object
          description: Display format for each field.
          additionalProperties:
            type: string
          example:
            record_date: YYYY-MM-DD
        total-count:
          type: integer
          description: Total number of records matching the query.
          example: 8298
        total-pages:
          type: integer
          description: Total number of pages available.
          example: 83
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Error response from the Treasury Fiscal Data API.
      properties:
        error:
          type: string
          description: Error code.
          example: Bad Request
        message:
          type: string
          description: Detailed error message.
          example: Invalid filter parameter syntax.
        status:
          type: integer
          description: HTTP status code.
          example: 400
  parameters:
    fields:
      name: fields
      in: query
      required: false
      description: Comma-separated list of field names to include in the response. Use to limit output to specific columns (e.g., fields=record_date,tot_pub_debt_out_amt).
      schema:
        type: string
        example: record_date,tot_pub_debt_out_amt,debt_held_public_amt
    filter:
      name: filter
      in: query
      required: false
      description: 'Filter criteria using format field:operator:value. Multiple filters separated by commas. Operators: eq (equals), lt (less than), lte (less than or equal), gt (greater than), gte (greater than or equal), in (in list). Example: filter=record_date:gte:2025-01-01,record_date:lte:2025-12-31'
      schema:
        type: string
        example: record_date:gte:2025-01-01,record_date:lte:2025-12-31
    format:
      name: format
      in: query
      required: false
      description: 'Response format. Options: json (default), csv, xml.'
      schema:
        type: string
        enum:
        - json
        - csv
        - xml
        default: json
        example: json
    pageSize:
      name: page[size]
      in: query
      required: false
      description: Number of records per page (max 10000).
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 100
        example: 100
    sort:
      name: sort
      in: query
      required: false
      description: 'Comma-separated list of field names to sort by. Prefix with minus (-) for descending order. Example: sort=-record_date,security_desc'
      schema:
        type: string
        example: -record_date
    pageNumber:
      name: page[number]
      in: query
      required: false
      description: Page number for pagination (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1