api-ninjas-com Metals Price API

openapi: 3.2.0
info:
  title: Ninjas Metals 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: Metals Price
  description: The Metals Price API returns live spot prices for gold (XAU), silver (XAG), platinum (XPT), palladium (XPD), copper, and aluminum, with the matching futures price and contract in the same response. Prices convert to any major currency and weight unit (troy ounce, gram, kilogram, pound). The free tier returns the last daily close for every metal; premium plans return live prices with bid and ask.
paths:
  /v1/metalsprice:
    get:
      summary: Get the current spot and futures price of a metal
      operationId: getCurrentMetalsPrice
      description: Returns the current spot price of a metal with its futures price and contract. Free tier returns the last daily close for every metal; Developer plans get a spot price refreshed every minute; Business, Professional, and Enterprise plans get the live spot price (about every 10 seconds) and the metals batch parameter.
      parameters:
      - name: metal
        in: query
        required: false
        description: The metal to return. Defaults to gold. xau, xag, xpt, xpd, and aluminium are also accepted as aliases.
        schema:
          type: string
          enum:
          - gold
          - silver
          - platinum
          - palladium
          - copper
          - aluminum
          default: gold
      - name: metals
        in: query
        required: false
        description: Comma-separated list of metals for a batch request. Available to Business, Professional, and Enterprise subscribers, or any annual plan.
        schema:
          type: string
          example: gold,silver,platinum
      - name: currency
        in: query
        required: false
        description: ISO 4217 currency code to convert prices into (e.g., EUR, GBP, INR). Defaults to USD.
        schema:
          type: string
          example: EUR
      - name: unit
        in: query
        required: false
        description: Target weight unit. Defaults to the metal's native unit (troy_ounce for precious metals, lb for copper, metric_ton for aluminum).
        schema:
          type: string
          enum:
          - troy_ounce
          - g
          - kg
          - oz
          - lb
          - metric_ton
          - short_ton
          - hundredweight
      responses:
        '200':
          description: Successful response. Object when called with metal; array when called with metals.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/MetalsPriceResponse'
                - type: array
                  items:
                    oneOf:
                    - $ref: '#/components/schemas/MetalsPriceResponse'
                    - $ref: '#/components/schemas/MetalsPriceOpenapi_BatchItemError'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - Metals Price
components:
  schemas:
    MetalsPriceOpenapi_BatchItemError:
      type: object
      description: Error entry returned for a single type in a batch request that failed or is not permitted.
      properties:
        metal:
          type: string
          description: The metal as requested.
        error:
          type: string
          description: Why this metal could not be returned.
    MetalsPriceResponse:
      type: object
      properties:
        metal:
          type: string
          description: The requested metal.
        name:
          type: string
          description: Display name of the metal.
        price:
          type: number
          description: 'The spot price: live on premium plans, the last daily close on the free plan.'
        bid:
          type: number
          description: Spot bid price (gold, silver, platinum, palladium; premium plans only).
        ask:
          type: number
          description: Spot ask price (gold, silver, platinum, palladium; premium plans only).
        spot_type:
          type: string
          enum:
          - composite
          - futures_based
          description: composite for gold, silver, platinum and palladium; futures_based for copper and aluminum, priced from the most actively traded futures contract.
        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.
        futures_price:
          type: number
          description: Price of the futures contract in futures_contract.
        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).
        futures_exchange:
          type: string
          description: Exchange the futures contract trades on (COMEX or NYMEX).
        unit:
          type: string
          description: Weight unit prices are quoted in.
        currency_unit:
          type: string
          description: Price currency, USD by default.
        market_status:
          type: string
          enum:
          - open
          - closed
          description: Whether metals are 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.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api