api-ninjas-com Gold Price API

openapi: 3.2.0
info:
  title: Ninjas Gold Price API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Gold Price
  description: The Gold Price API provides access to real-time and historical gold futures prices in the Chicago Mercantile Exchange (CME).
paths:
  /v1/goldprice:
    get:
      summary: Get current gold futures price
      description: Returns the current gold futures price in USD. Free responses carry the last completed daily settlement; premium plans return the live price.
      operationId: getCurrentGoldPrice
      parameters:
      - name: currency
        in: query
        required: false
        description: ISO 4217 currency code to convert the price into (e.g., EUR, GBP, INR). Defaults to USD.
        schema:
          type: string
          example: EUR
      - name: unit
        in: query
        required: false
        description: Target unit to convert the price into. Defaults to troy_ounce.
        schema:
          type: string
          enum:
          - troy_ounce
          - g
          - kg
          - oz
          - lb
          - metric_ton
          - short_ton
          - hundredweight
          default: troy_ounce
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoldPriceResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - Gold Price
  /v1/goldspot:
    get:
      summary: Get the current gold spot price
      operationId: getGoldSpotPrice
      description: Premium only. Returns the gold spot price (XAU/USD) with bid and ask.
      parameters:
      - name: currency
        in: query
        required: false
        description: ISO 4217 currency code to convert the price into (e.g., EUR, GBP, INR). Defaults to USD.
        schema:
          type: string
          example: EUR
      - name: unit
        in: query
        required: false
        description: Target unit to convert the price into. Defaults to troy_ounce.
        schema:
          type: string
          enum:
          - troy_ounce
          - g
          - kg
          - oz
          - lb
          - metric_ton
          - short_ton
          - hundredweight
          default: troy_ounce
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoldSpotResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - Gold Price
  /v1/goldpricehistorical:
    get:
      summary: Get historical gold futures price data
      description: Returns historical gold futures price data in OHLCV (Open, High, Low, Close, Volume) format. The data is returned in descending order (most recent first), and all prices are in USD. Premium subscribers only.
      operationId: getHistoricalGoldPrice
      security:
      - ApiKeyAuth: []
      parameters:
      - name: period
        in: query
        description: 'Time interval between data points. Valid values are: 1m, 5m, 15m, 30m, 1h, 4h, 1d. Default is 1h.'
        required: false
        schema:
          type: string
          enum:
          - 1m
          - 5m
          - 15m
          - 30m
          - 1h
          - 4h
          - 1d
          default: 1h
      - name: start
        in: query
        description: Start timestamp in Unix format. If not provided, defaults to 24 hours ago.
        required: false
        schema:
          type: integer
      - name: end
        in: query
        description: End timestamp in Unix format. If not provided, defaults to current time.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoricalGoldPriceResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - Gold Price
components:
  schemas:
    HistoricalGoldPriceResponse:
      type: array
      items:
        type: object
        properties:
          open:
            type: number
            description: The opening price for this time period in USD.
          low:
            type: number
            description: The lowest price during this time period in USD.
          high:
            type: number
            description: The highest price during this time period in USD.
          close:
            type: number
            description: The closing price for this time period in USD.
          volume:
            type: integer
            description: The trading volume during this time period.
          time:
            type: integer
            description: The timestamp for this data point in Unix format (in seconds).
    GoldPriceResponse:
      type: object
      properties:
        price:
          type: number
          description: The current gold futures price. In USD per troy ounce by default; converted when the currency and/or unit parameters are used.
        timestamp:
          type: integer
          description: The timestamp of the gold futures price in Unix format (in seconds).
        unit:
          type: string
          description: The quote unit (troy_ounce by default; changes when the unit parameter is used).
        currency_unit:
          type: string
          description: The price currency (USD by default; changes when the currency parameter is used).
        updated:
          type: integer
          description: The timestamp at which the gold futures price was last updated, in Unix format (in seconds).
        futures_contract:
          type: string
          description: The futures contract `price` is quoted for (e.g., GCZ26 = December 2026 gold).
        futures_contract_month:
          type: string
          description: Delivery month of futures_contract (YYYY-MM).
    GoldSpotResponse:
      type: object
      properties:
        price:
          type: number
          description: The gold spot price (XAU/USD), in USD per troy ounce by default.
        bid:
          type: number
          description: Spot bid price.
        ask:
          type: number
          description: Spot ask price.
        spot_type:
          type: string
          enum:
          - composite
          description: composite = a live spot price; refreshed every minute on Developer plans and about every 10 seconds on Business plans and above.
        previous_close:
          type: number
          description: The previous session's closing spot price.
        change_24h:
          type: number
          description: Change versus the previous close.
        change_24h_percent:
          type: number
          description: Percent change versus the previous close.
        high_24h:
          type: number
          description: The session's high price.
        low_24h:
          type: number
          description: The session's low price.
        market_status:
          type: string
          enum:
          - open
          - closed
          description: Whether gold is trading (Sunday 6 PM to Friday 5 PM ET, with a daily 5-6 PM ET break).
        updated:
          type: integer
          description: Unix timestamp (seconds) of the spot price.
        unit:
          type: string
          description: The quote unit.
        currency_unit:
          type: string
          description: Price currency, USD by default.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api