openapi: 3.1.0
info:
  title: Exchange Rate API
  x-providerName: exchange-rateapi.com
  x-apisguru-categories:
    - financial
  x-origin:
    - url: https://exchange-rateapi.com/openapi.yaml
      format: openapi
      version: "3.1.0"
  x-logo:
    url: https://exchange-rateapi.com/logo-256.png
  description: |
    Real-time and historical currency exchange rates API.

    ## Overview
    Exchange Rate API provides accurate mid-market exchange rates for 160+ currencies. Our API is designed for:
    - Currency converters and calculators
    - Financial applications and fintech
    - E-commerce platforms
    - AI chatbots and assistants

    ## Authentication
    Most endpoints require an API key via the `Authorization: Bearer <api_key>` header.
    The `/api/v1/symbols` endpoint is public and does not require authentication.

    ## Plans & Quotas
    A free tier and paid plans are available. See [exchange-rateapi.com/pricing](https://exchange-rateapi.com/pricing) for current quotas.

    ## Getting an API Key
    1. Register at [exchange-rateapi.com/register](https://exchange-rateapi.com/register)
    2. Verify your email
    3. Find your API key in your dashboard

  version: 1.0.0
  contact:
    name: Exchange Rate API Support
    url: https://exchange-rateapi.com
    email: admin@exchange-rateapi.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://exchange-rateapi.com/api
    description: Production server

tags:
  - name: Exchange Rates
    description: Get current and historical exchange rates

paths:
  /rate:
    get:
      tags:
        - Exchange Rates
      summary: Get current exchange rate (public)
      description: |
        Returns the current mid-market exchange rate between two currencies.
        No authentication required.
      operationId: getCurrentRate
      parameters:
        - name: source
          in: query
          required: true
          description: Source currency code (ISO 4217)
          schema:
            type: string
            example: USD
            minLength: 3
            maxLength: 3
        - name: target
          in: query
          required: true
          description: Target currency code (ISO 4217)
          schema:
            type: string
            example: EUR
            minLength: 3
            maxLength: 3
      responses:
        '200':
          description: Successful response with exchange rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponse'
              example:
                rate: 0.92145
                source: wise
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Missing required parameters
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /historical-rates:
    get:
      tags:
        - Exchange Rates
      summary: Get historical exchange rates
      description: |
        Returns historical exchange rate data for a currency pair over a specified time period.
        Requires API key authentication via `Authorization: Bearer <api_key>`.
        Data points vary by period:
        - 1d: Hourly data points
        - 7d: Daily data points
        - 30d: Daily data points
        - 1y: Weekly data points
      operationId: getHistoricalRates
      security:
        - BearerAuth: []
      parameters:
        - name: source
          in: query
          required: true
          description: Source currency code (ISO 4217)
          schema:
            type: string
            example: USD
        - name: target
          in: query
          required: true
          description: Target currency code (ISO 4217)
          schema:
            type: string
            example: INR
        - name: period
          in: query
          required: false
          description: Time period for historical data
          schema:
            type: string
            enum: [1d, 7d, 30d, 1y]
            default: 7d
      responses:
        '200':
          description: Successful response with historical rates
          headers:
            Cache-Control:
              description: Cache duration
              schema:
                type: string
                example: public, max-age=3600
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalRatesResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/rates:
    get:
      tags:
        - Exchange Rates
      summary: Authenticated exchange rate API
      description: |
        Get exchange rates with higher rate limits using API key authentication.
        Supports fetching multiple currency pairs and historical data.
      operationId: getAuthenticatedRates
      security:
        - BearerAuth: []
      parameters:
        - name: source
          in: query
          required: false
          description: Source currency code (or use 'from')
          schema:
            type: string
            example: USD
        - name: target
          in: query
          required: false
          description: Target currency code. Supports comma-separated values for multiple targets (e.g. EUR,GBP,JPY)
          schema:
            type: string
            example: EUR
        - name: from
          in: query
          required: false
          description: Alternate source currency parameter
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: Alternate target currency parameter
          schema:
            type: string
        - name: time
          in: query
          required: false
          description: Historical timestamp (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: amount
          in: query
          required: false
          description: Amount to convert (default 1). Response rate is always per unit.
          schema:
            type: number
            example: 1000
        - name: group
          in: query
          required: false
          description: Group rates by time period
          schema:
            type: string
            enum: [hour, day, week, month]
      responses:
        '200':
          description: Successful response with rates
          headers:
            X-RateLimit-Remaining:
              description: Remaining requests
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Total requests allowed
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Reset timestamp
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthenticatedRateItem'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/symbols:
    get:
      tags:
        - Exchange Rates
      summary: List all supported currencies
      description: |
        Returns all supported currency codes, names, and symbols.
        No authentication required. Response is cached for 24 hours.
      operationId: getSymbols
      responses:
        '200':
          description: List of supported currencies
          content:
            application/json:
              schema:
                type: object
                properties:
                  currencies:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: USD
                        name:
                          type: string
                          example: US Dollar
                        symbol:
                          type: string
                          example: $
                  count:
                    type: integer
                    example: 52

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication. Get your API key from your Exchange Rate API dashboard.

        Example: `Authorization: Bearer era_live_xxxxx`

  schemas:
    RateResponse:
      type: object
      required:
        - rate
        - source
      properties:
        rate:
          type: number
          format: double
          description: Current exchange rate
          example: 0.92145
        source:
          type: string
          description: Data source provider
          example: wise

    HistoricalRatesResponse:
      type: object
      required:
        - source
        - target
        - data
        - period
      properties:
        source:
          type: string
          description: Source currency code
          example: USD
        target:
          type: string
          description: Target currency code
          example: INR
        data:
          type: array
          description: Historical rate data points
          items:
            type: object
            properties:
              date:
                type: string
                format: date-time
                description: Data point timestamp
              rate:
                type: number
                format: double
                description: Exchange rate at this time
              timestamp:
                type: integer
                format: int64
                description: Unix timestamp in milliseconds
        source_api:
          type: string
          description: Data source provider
          example: wise
        period:
          type: string
          description: Requested time period
          enum: [1d, 7d, 30d, 1y]

    AuthenticatedRateItem:
      type: object
      properties:
        rate:
          type: number
          format: double
          description: Exchange rate
        source:
          type: string
          description: Source currency code
        target:
          type: string
          description: Target currency code
        time:
          type: string
          format: date-time
          description: Rate timestamp

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
