openapi: 3.0.0
info:
  title: ForexAPI - Live currency rates for your company
  version: 2.0.0
  description: |
    ForexAPI provides streamlined, dependable JSON API offering 700+ currency pairs, updated instantly.
    <br>
    Seamlessly integrate with any application & programming language.
    <br>
    <br>
    <a href="https://forexapi.eu/en/signup">Get a free apikey</a> to start using the API.
    <br>

  termsOfService: https://forexapi.eu/en/terms-of-service
  contact:
      name: ForexAPI
      url: https://forexapi.eu/en
      email: support@forexapi.eu
servers:
  - url: https://api.forexapi.eu/v2

paths:
  /live:
    get:
      summary: Get live currency quotes
      parameters:
        - name: base
          in: query
          required: true
          schema:
            type: string
            default: 'USD'
          description: Base currency
        - name: counter
          in: query
          required: true
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            default:
              - 'GBP'
              - 'PLN'
              - 'CHF'
              - 'HUF'
              - 'JPY'
          description: Comma-separated list of counter currencies
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - csv
              - xml
            default: json
          description: Response format (json, csv, xml)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveQuotes'
              example:
                base: USD
                quotes:
                  PLN:
                    base: USD
                    counter: PLN
                    bid: '3.7870'
                    ask: '3.7890'
                    mid: '3.7880'
                    timestamp: 1589568000
                  GBP:
                    base: USD
                    counter: GBP
                    bid: '0.8130'
                    ask: '0.8150'
                    mid: '0.8140'
                    timestamp: 1589568000
                cost: 2
            text/csv:
              schema:
                type: string
              example: |
                base,counter,bid,ask,mid,timestamp
                USD,HUF,346.0900,347.0300,346.5600,"2024-01-16 00:49:06"
                USD,PLN,4.0003,4.0046,4.0024,"2024-01-16 00:49:06"
            application/xml:
              schema:
                  type: object
                  xml:
                    name: response
                    wrapped: true
              example: |
                <?xml version="1.0"?>
                <response>
                  <base>USD</base>
                  <cost>2</cost>
                  <quotes>
                    <quote counter="GBP">
                      <counter>GBP</counter>
                      <bid>0.7863</bid>
                      <ask>0.7863</ask>
                      <mid>0.7863</mid>
                      <timestamp>2024-01-24T23:51:22Z</timestamp>
                    </quote>
                    <quote counter="EUR">
                      <counter>EUR</counter>
                      <bid>0.9186</bid>
                      <ask>0.9190</ask>
                      <mid>0.9188</mid>
                      <timestamp>2024-01-24T23:51:22Z</timestamp>
                    </quote>
                  </quotes>
                </response>
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedRequestError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'

  /convert:
    get:
      summary: Convert between currencies
      parameters:
        - name: amount
          in: query
          required: true
          schema:
            type: number
            format: decimal
            default: '1.0'
          description: Amount to convert; if you want to get the exchange rate, set it to 1.
        - name: from
          in: query
          required: true
          schema:
            type: string
            default: USD
          description: Base currency
        - name: to
          in: query
          required: true
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
            default:
              - 'EUR'
              - 'GBP'
              - 'JPY'
              - 'PLN'
              - 'HUF'
          description: Comma-separated list of counter currencies
        - name: precision
          in: query
          schema:
            type: integer
            default: 4
          description: "Number of decimal places in the result (0-8) - default: 4"
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - csv
              - xml
            default: json
          description: Response format (json, csv, xml)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyConversion'
              example:
                from: USD
                amount: 100
                results:
                  PLN: '378.70'
                  GBP: '81.30'
                timestamp: 1589568000
                cost: 2
            text/csv:
              schema:
                type: string
              example: |
                timestamp,from,amount,GBP,PLN,EUR,CHF
                "2024-01-24 23:57:21",USD,123,96.78,495.59,113.09,106.30
            application/xml:
              schema:
                type: object
                xml:
                  name: response
                  wrapped: true
              example: |
                <?xml version="1.0"?>
                <response>
                  <from>USD</from>
                  <amount>123</amount>
                  <results>
                    <result currency="GBP">96.78</result>
                    <result currency="PLN">495.60</result>
                    <result currency="EUR">113.10</result>
                    <result currency="CHF">106.30</result>
                  </results>
                  <timestamp>2024-01-24T23:51:22Z</timestamp>
                  <cost>4</cost>
                </response>
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedRequestError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'

  /market-status:
    get:
      summary: Check the market status
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - csv
              - xml
            default: json
          description: Response format (json, csv, xml)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketStatus'
              example:
                is_market_open: true
            text/csv:
              schema:
                type: string
              example: |
                is_market_open
                1
            application/xml:
              schema:
                type: object
                xml:
                  name: response
                  wrapped: true
              example: |
                <response>
                  <is_market_open>1</is_market_open>
                </response>
        '401':
          $ref: '#/components/responses/UnauthorizedRequestError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'

  /currencies:
    get:
      summary: Get a list of supported currencies
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - csv
              - xml
            default: json
          description: Response format (json, csv, xml)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyList'
              example:
                currencies:
                  USD:
                    code: USD
                    name: US Dollar
                    num: 840
                  PLN:
                    code: PLN
                    name: Polish Zloty
                    num: 985
                  GBP:
                    code: GBP
                    name: British Pound
                    num: 826
                  EUR:
                    code: EUR
                    name: Euro
                    num: 978
                  CHF:
                    code: CHF
                    name: Swiss Franc
                    num: 756
                  JPY:
                    code: JPY
                    name: Japanese Yen
                    num: 392
                  CZK:
                    code: CZK
                    name: Czech Koruna
                    num: 203
            text/csv:
              schema:
                type: string
              example: |
                code,name,num
                EUR,Euro,978
                USD,"US Dollar",840
                AUD,"Australian Dollar",36
                INR,"Indian Rupee",356
            application/xml:
              schema:
                type: object
                xml:
                  name: response
                  wrapped: true
              example: |
                <?xml version="1.0"?>
                <response>
                  <count>28</count>
                  <currencies>
                    <currency code="EUR">
                      <code>EUR</code>
                      <name>Euro</name>
                      <num>978</num>
                    </currency>
                    <currency code="USD">
                      <code>USD</code>
                      <name>US Dollar</name>
                      <num>840</num>
                    </currency>
                  </currencies>
                </response>
        '401':
          $ref: '#/components/responses/UnauthorizedRequestError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /usage:
    get:
      summary: Check API usage
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - csv
              - xml
            default: json
          description: Response format (json, csv, xml)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUsage'
              example:
                plan: free
                used: 0
                limit: 1000
                remaining: 1000
            text/csv:
              schema:
                type: string
              example: |
                plan,used,limit,remaining
                basic_yearly,100,120000,119900
            application/xml:
              schema:
                type: object
                xml:
                  name: response
                  wrapped: true
              example: |
                <?xml version="1.0"?>
                <response>
                  <plan>basic_yearly</plan>
                  <used>100</used>
                  <limit>120000</limit>
                  <remaining>119900</remaining>
                </response>
security:
  - ApiKeyAuth: []
  - ApiKeyAuthQuery: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-apikey
      description: API key
    ApiKeyAuthQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key
  responses:
    UnauthorizedRequestError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
          example:
            error: 'API key is required to access this resource.'
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DetailedError'
          example:
            error: 'Invalid base currency'
            path: 'base'
    TooManyRequestsError:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
          example:
            error: 'You have exceeded your API usage limit'
  schemas:
    LiveQuotes:
      type: object
      required:
          - base
          - quotes
          - cost
      properties:
        base:
          type: string
          description: Base currency
        quotes:
          type: object
          description: Quotes for each counter currency
          additionalProperties:
            $ref: '#/components/schemas/Quote'
        cost:
          type: integer
          description: Cost of the request in API credits
    Quote:
      type: object
      required:
          - base
          - counter
          - bid
          - ask
          - mid
          - timestamp
      properties:
        bid:
          type: number
          format: decimal
        ask:
          type: number
          format: decimal
        mid:
          type: number
          format: decimal
        timestamp:
          type: integer
    CurrencyConversion:
      type: object
      required:
        - from
        - amount
        - results
        - timestamp
        - cost
      properties:
        from:
          type: string
        amount:
          type: number
          format: decimal
        results:
          type: object
          additionalProperties:
            type: number
            format: decimal
        timestamp:
          type: integer
        cost:
          type: integer
    MarketStatus:
      type: object
      required:
        - is_market_open
      properties:
        is_market_open:
          type: boolean
    CurrencyList:
      type: object
      required:
        - currencies
      properties:
        currencies:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Currency'
    Currency:
      type: object
      required:
        - code
        - name
        - num
      properties:
        code:
          type: string
        name:
          type: string
        num:
          type: integer
    ApiUsage:
      type: object
      required:
        - plan
        - used
        - limit
        - remaining
      properties:
        plan:
          type: string
        used:
          type: integer
        limit:
          type: integer
        remaining:
          type: integer
    DetailedError:
      type: object
      properties:
        error:
          type: string
        path:
          type: string
      required:
        - error
    GeneralError:
      type: object
      properties:
        error:
          type: string
      required:
        - error