openapi: 3.1.0
info:
  title: Gold and Currency Price API
  version: 1.0.0
  description: |
    A simple API to fetch live prices for currencies, gold and coins, plus daily changes and range-based OHLC archives.
    Authentication via API Key (Bearer) or query param license_key.
  termsOfService: https://roxcode.net/terms
  contact:
    name: Roxcode
    url: https://roxcode.net
    email: support@roxcode.net
  license:
    name: Proprietary
servers:
  - url: https://ws.roxcode.net

tags:
  - name: Prices
  - name: History (Daily)
  - name: History (Range)

paths:
  /api/currency/list:
    get:
      tags: [Prices]
      summary: Get live prices
      description: Returns latest prices for currencies, gold and coins.
      security:
        - BearerAuth: []
        - ApiKeyQuery: []
      parameters:
        - $ref: '#/components/parameters/symbols'
        - $ref: '#/components/parameters/metals'
        - $ref: '#/components/parameters/license_key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PricesResponse' }

  /api/currency/list/sandbox:
    get:
      tags: [Prices]
      summary: Get live prices (Sandbox)
      description: Test endpoint without params.
      responses:
        '200':
          description: OK (Sandbox)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PricesResponse' }

  /api/currency/day:
    get:
      tags: [History (Daily)]
      summary: Daily changes for a given date
      description: Price changes within a given day (Unix timestamp or YYYY-MM-DD).
      security:
        - BearerAuth: []
        - ApiKeyQuery: []
      parameters:
        - $ref: '#/components/parameters/currency'
        - $ref: '#/components/parameters/date'
        - $ref: '#/components/parameters/license_key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/DayChangeItem' }

  /api/currency/day/sandbox:
    get:
      tags: [History (Daily)]
      summary: Daily changes (Sandbox)
      responses:
        '200':
          description: OK (Sandbox)
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/DayChangeItem' }

  /api/currency/between:
    get:
      tags: [History (Range)]
      summary: Daily OHLC within a date range
      description: Returns per-day OHLC (Open/High/Low/Close) for a date range.
      security:
        - BearerAuth: []
        - ApiKeyQuery: []
      parameters:
        - $ref: '#/components/parameters/currency'
        - $ref: '#/components/parameters/start'
        - $ref: '#/components/parameters/end'
        - $ref: '#/components/parameters/license_key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/OHLCItem' }

  /api/currency/between/sandbox:
    get:
      tags: [History (Range)]
      summary: Daily OHLC (Sandbox)
      responses:
        '200':
          description: OK (Sandbox)
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/OHLCItem' }

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: license_key

  parameters:
    symbols:
      name: symbols
      in: query
      description: Comma separated currency codes (e.g. USD,EUR,IRR)
      required: false
      schema: { type: string }
    metals:
      name: metals
      in: query
      description: Comma separated metal names (e.g. gold,silver)
      required: false
      schema: { type: string }
    currency:
      name: currency
      in: query
      description: Asset/currency code (e.g. USD or GOLD)
      required: true
      schema: { type: string }
    date:
      name: date
      in: query
      description: Unix timestamp or YYYY-MM-DD
      required: true
      schema:
        oneOf:
          - type: integer
          - type: string
            pattern: '^\d{4}-\d{2}-\d{2}$'
    start:
      name: start
      in: query
      description: Start date (Unix timestamp or YYYY-MM-DD)
      required: true
      schema:
        oneOf:
          - type: integer
          - type: string
            pattern: '^\d{4}-\d{2}-\d{2}$'
    end:
      name: end
      in: query
      description: End date (Unix timestamp or YYYY-MM-DD)
      required: true
      schema:
        oneOf:
          - type: integer
          - type: string
            pattern: '^\d{4}-\d{2}-\d{2}$'
    license_key:
      name: license_key
      in: query
      description: API key as query parameter (alternative to Bearer header)
      required: false
      schema: { type: string }

  schemas:
    PricesResponse:
      type: object
      properties:
        timestamp: { type: string, format: date-time }
        base: { type: string, example: IRR }
        gold:
          type: object
          properties:
            ounce: { type: number, example: 2450.12 }
            gram:  { type: number, example: 78.90 }
        currencies:
          type: object
          additionalProperties:
            type: number
            example: 538000

    DayChangeItem:
      type: object
      properties:
        timestamp: { type: integer, example: 1733011200 }
        date: { type: string, example: "2024-12-01" }
        value: { type: number, example: 541200 }
        change: { type: number, nullable: true, example: 1200 }

    OHLCItem:
      type: object
      properties:
        timestamp: { type: integer, example: 1733011200 }
        date: { type: string, example: "2024-12-01" }
        open: { type: number, example: 540000 }
        high: { type: number, example: 545000 }
        low:  { type: number, example: 538000 }
        close:{ type: number, example: 541200 }

    ErrorResponse:
      type: object
      properties:
        err_code: { type: integer }
        message:  { type: string }

  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    NotFound:
      description: Not Found
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
