Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Ninjas Commodity 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: Commodity Price
description: The Commodity Price API provides access to real-time and historical commodity prices for dozens of commonly-traded commodities. It also provides access to commodity contract information, full-catalog snapshots, and forward curves.
paths:
/v1/commodityprice:
get:
summary: Get current commodity price (single or batch)
operationId: getCurrentCommodityPrice
description: Returns the current price for a single commodity (when `name` is provided) or a list of commodities (when `names` is provided). Optional `currency` and `unit` parameters convert the response from the native USD/USX quote into any supported currency and unit.
parameters:
- name: name
in: query
required: false
description: Name of a single commodity. Mutually exclusive with `names`.
schema:
type: string
enum:
- gold
- soybean_oil
- wheat
- platinum
- micro_silver
- lean_hogs
- corn
- oat
- aluminum
- soybean_meal
- silver
- soybean
- lumber
- live_cattle
- sugar
- natural_gas
- crude_oil
- orange_juice
- coffee
- cotton
- copper
- micro_gold
- feeder_cattle
- rough_rice
- palladium
- cocoa
- brent_crude_oil
- gasoline_rbob
- heating_oil
- class_3_milk
- name: names
in: query
required: false
description: Comma-separated list of commodity values for a batch request (max 30). Mutually exclusive with `name`. Available to Business, Professional, and Enterprise subscribers; other tiers should use the `name` parameter for single-commodity lookups.
schema:
type: string
example: gold,silver,platinum
- name: currency
in: query
required: false
description: ISO 4217 currency code to convert the price into (e.g., EUR, GBP, INR). When provided, USX prices are first normalized to USD before conversion. Defaults to the native USD/USX quote.
schema:
type: string
example: EUR
- name: unit
in: query
required: false
description: Target mass/volume/energy unit to convert the price into (e.g., kg, g, lb, metric_ton, liter). Bushel and board_feet are commodity-specific and cannot be cross-converted.
schema:
type: string
example: kg
responses:
'200':
description: Successful response. A full CommodityPriceResponse object when called with `name`; when called with `names`, an array whose elements are reduced CommodityBatchPriceItem projections (or a BatchItemError for any individual commodity that failed).
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CommodityPriceResponse'
- type: array
items:
oneOf:
- $ref: '#/components/schemas/CommodityBatchPriceItem'
- $ref: '#/components/schemas/BatchItemError'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Commodity Price
/v1/commodityspot:
get:
summary: Get the current spot price of a commodity (single or batch)
operationId: getCommoditySpotPrice
description: 'Premium only. Returns the spot price (the price for immediate delivery) for commodities that have a spot market: gold, silver, platinum, and palladium (composite: a live spot price, with bid/ask) and WTI, Brent, natural gas, gasoline, and heating oil (assessed: the daily spot price at the benchmark''s physical delivery hub). Other commodities have no public spot market and return an error pointing to /commodityprice.'
parameters:
- name: name
in: query
required: false
description: The commodity. crude_oil, brent_crude_oil, gasoline_rbob, and heating_oil also accept wti, brent, gasoline, and diesel.
schema:
type: string
enum:
- gold
- silver
- platinum
- palladium
- crude_oil
- brent_crude_oil
- natural_gas
- gasoline_rbob
- heating_oil
- name: names
in: query
required: false
description: Comma-separated list of commodities for a batch request. Available to Business, Professional, and Enterprise subscribers only.
schema:
type: string
example: gold,silver,natural_gas
- name: currency
in: query
required: false
description: ISO 4217 currency code to convert prices into (e.g., EUR, GBP). Defaults to USD.
schema:
type: string
example: EUR
- name: unit
in: query
required: false
description: Target unit, in the same dimension as the commodity's native unit (mass for metals, volume for oil, gasoline and heating oil, energy for natural gas).
schema:
type: string
example: g
responses:
'200':
description: Successful response. Object when called with name; array when called with names.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CommoditySpotResponse'
- type: array
items:
oneOf:
- $ref: '#/components/schemas/CommoditySpotResponse'
- $ref: '#/components/schemas/BatchItemError'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
tags:
- Commodity Price
/v1/commoditypricehistorical:
get:
summary: Get historical commodity prices
description: Returns a historical price series for a commodity over an optional Unix start/end range and interval. Requires a `name`. For the latest price use /commodityprice.
operationId: getHistoricalCommodityPrice
parameters:
- name: name
in: query
required: true
description: Name of commodity.
schema:
type: string
- name: period
in: query
required: false
description: Time interval between data points.
schema:
type: string
enum:
- 1m
- 5m
- 15m
- 30m
- 1h
- 4h
- 1d
default: 1h
- name: start
in: query
required: false
description: Start timestamp in Unix format.
schema:
type: integer
- name: end
in: query
required: false
description: End timestamp in Unix format.
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/HistoricalPriceResponse'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Commodity Price
/v1/commoditysnapshot:
get:
summary: Get current prices for all supported commodities in a single call
operationId: getCommoditySnapshot
description: Returns an enriched price object for all 30 supported commodities on every plan, including the free tier. Free responses carry the last completed daily settlement; premium plans return the live price. Optional filters narrow the result set.
parameters:
- name: category
in: query
required: false
description: Filter to a single product category.
schema:
type: string
enum:
- precious_metals
- base_metals
- energy
- grains
- softs
- livestock
- name: exchange
in: query
required: false
description: Filter to commodities listed on a single exchange.
schema:
type: string
enum:
- CME
- NYMEX
- COMEX
- ICE
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CommoditySnapshotItem'
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Commodity Price
/v1/commoditycontract:
get:
summary: Get price information for a specific commodity contract
operationId: getCommodityContract
description: Returns price information for a specific commodity contract or all contracts matching a commodity root. Either symbol or symbol_root must be provided, but not both.
parameters:
- name: symbol
in: query
required: false
description: Specific contract symbol to look up (e.g., GCK26).
schema:
type: string
- name: symbol_root
in: query
required: false
description: Commodity root to filter contracts (e.g., GC returns all contracts starting with GC like GCK26, GCM26, etc.).
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/CommodityContractResponse'
'400':
description: Bad Request - Either symbol or symbol_root must be provided, but not both.
'401':
description: Unauthorized
'403':
description: Forbidden - This endpoint is reserved for users on Business, Professional, or annual subscriptions only.
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Commodity Price
/v1/commoditycontractlist:
get:
summary: Get a list of all available commodity contracts
operationId: getCommodityContractList
description: Returns a list of all available commodity contracts with their symbols and commodity names. This endpoint is useful for discovering which contracts are available for querying.
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/CommodityContractListResponse'
'401':
description: Unauthorized
'403':
description: Forbidden - This endpoint is reserved for users on Business, Professional, or annual subscriptions only.
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Commodity Price
/v1/commodityforwardcurve:
get:
summary: Get the forward curve (all active contracts) for a commodity
operationId: getCommodityForwardCurve
description: Returns every active futures contract for the requested commodity, sorted by contract month, along with a contango/backwardation classification and 1-month and ~12-month percent slopes. Reserved for Business, Professional, and annual-subscription tiers.
parameters:
- name: name
in: query
required: true
description: Commodity value. Same set as the `/commodityprice` `name` parameter.
schema:
type: string
example: crude_oil
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/CommodityForwardCurveResponse'
'400':
description: Bad Request - Unknown commodity name.
'401':
description: Unauthorized
'403':
description: Forbidden - Reserved for Business, Professional, or annual subscriptions.
'500':
description: Internal Server Error
security:
- ApiKeyAuth: []
tags:
- Commodity Price
components:
schemas:
BatchItemError:
type: object
description: Error entry returned for a single commodity in a batch request that failed.
properties:
name:
type: string
error:
type: string
CommoditySpotResponse:
type: object
properties:
name:
type: string
description: The commodity's display name.
value:
type: string
description: The commodity's name parameter value.
price:
type: number
description: 'The spot price: the price for immediate delivery.'
bid:
type: number
description: Spot bid price (composite spot only).
ask:
type: number
description: Spot ask price (composite spot only).
spot_type:
type: string
enum:
- composite
- assessed
description: 'How the price is produced: composite = a live spot price with bid/ask (gold, silver, platinum, palladium; refreshed every minute on Developer plans, about every 10 seconds on Business plans and above); assessed = the daily spot price at the benchmark''s physical delivery hub (oil and energy).'
date:
type: string
description: 'Assessed spot only: the trading day of the price (YYYY-MM-DD). Daily spot prices are published with a delay, so it trails by several days.'
benchmark:
type: string
description: 'Assessed spot only: the physical spot benchmark (e.g., WTI Cushing, Oklahoma).'
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: 'Composite spot only: the session''s high price.'
low_24h:
type: number
description: 'Composite spot only: the session''s low price.'
market_status:
type: string
enum:
- open
- closed
description: 'Composite spot only: whether the market 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.
CommodityForwardCurveResponse:
type: object
properties:
name:
type: string
description: Display name of the commodity.
value:
type: string
description: The API ?name= parameter value.
symbol_root:
type: string
description: Contract symbol root (e.g., CL for crude oil).
as_of:
type: integer
description: Unix timestamp of the most recent contract update across the curve.
structure:
type: string
enum:
- contango
- backwardation
- mixed
- flat
description: Curve-shape classification. Contango = strictly upward; backwardation = strictly downward; mixed = both; flat = no change.
contango_slope_1m_pct:
type:
- number
- 'null'
description: Percent difference between the front month price and the next month price. Positive = contango at the front.
contango_slope_12m_pct:
type:
- number
- 'null'
description: Percent difference between the front month price and the ~12-month-out contract price.
curve:
type: array
items:
$ref: '#/components/schemas/ForwardCurveContract'
ForwardCurveContract:
type: object
properties:
contract_symbol:
type: string
description: Full contract symbol (e.g., CLM26).
contract_month:
type: string
description: Contract delivery month in YYYY-MM format. The precise expiry day depends on the per-commodity rule; use the listing exchange's calendar for exact expiry.
month_offset:
type: integer
description: Number of calendar months between today and the contract month (0 = current month).
last_price:
type: number
last_updated:
type: integer
description: Unix timestamp of the contract's last update.
HistoricalPriceResponse:
type: array
items:
type: object
properties:
open:
type: number
description: The opening price of the commodity in USD.
low:
type: number
description: The lowest price of the commodity in USD.
high:
type: number
description: The highest price of the commodity in USD.
close:
type: number
description: The closing price of the commodity in USD.
volume:
type: integer
description: The volume of the commodity.
time:
type: integer
description: The Unix timestamp of the price update.
CommodityBatchPriceItem:
type: object
description: Reduced projection returned for each element of a `names` (batch) request. Each element is identified by `name` and `value`. The previous_close, change_24h_percent, high_24h, low_24h, high_52w, and low_52w fields returned by the single-commodity `name` form are NOT included.
properties:
name:
type: string
description: The display name of the commodity (e.g. Gold Futures).
value:
type: string
description: The commodity's `?name=` slug (e.g. gold, crude_oil).
exchange:
type: string
description: The symbol of the exchange where the commodity is traded.
unit:
type: string
description: The quote unit (e.g., troy_ounce, barrel, bushel).
currency_unit:
type: string
enum:
- USD
- USX
description: 'Price convention: USD = US dollars per unit; USX = US cents per unit.'
price:
type: number
description: The current price of the commodity in its native unit and currency convention.
change_24h:
type: number
description: Change vs previous close in the quote unit.
updated:
type: integer
description: Unix timestamp of the price update.
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).
CommodityPriceResponse:
type: object
properties:
exchange:
type: string
description: The symbol of the exchange where the commodity is traded.
name:
type: string
description: The display name of the commodity (e.g. Gold Futures).
value:
type: string
description: The commodity's `?name=` slug (e.g. gold, crude_oil).
price:
type: number
description: The current price of the commodity. See currency_unit for the price convention.
currency_unit:
type: string
enum:
- USD
- USX
description: 'Price convention: USD = US dollars per unit; USX = US cents per unit. Grains, softs, and livestock are typically USX; metals and energy are typically USD.'
unit:
type: string
description: The quote unit (e.g., troy_ounce, barrel, bushel, lb, MMBtu, gallon, metric_ton, short_ton, hundredweight, board_feet).
previous_close:
type: number
description: Previous session's closing price in the same quote convention as price.
change_24h:
type: number
description: Change vs previous close in the quote unit.
change_24h_percent:
type: number
description: Percent change vs previous close.
high_24h:
type: number
description: Day's high price.
low_24h:
type: number
description: Day's low price.
high_52w:
type: number
description: 52-week high.
low_52w:
type: number
description: 52-week low.
updated:
type: integer
description: Unix timestamp of the price update.
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).
CommoditySnapshotItem:
type: object
description: Snapshot returns a trimmed schema for batch efficiency. For previous_close, change_24h_percent, high_24h, low_24h, high_52w, low_52w, use /v1/commodityprice on a specific commodity.
properties:
exchange:
type: string
description: Listing exchange.
name:
type: string
description: Display name of the commodity.
value:
type: string
description: The API ?name= parameter value for this commodity.
category:
type: string
enum:
- precious_metals
- base_metals
- energy
- grains
- softs
- livestock
description: Product category for filtering.
currency_unit:
type: string
enum:
- USD
- USX
description: USD = US dollars per unit; USX = US cents per unit.
unit:
type: string
description: The quote unit.
price:
type: number
description: Current price in the commodity's native unit and currency convention.
change_24h:
type: number
description: Absolute price change vs the previous close.
volume:
type: integer
description: Trading volume for the session.
updated:
type: integer
description: Unix timestamp when the snapshot was fetched.
CommodityContractResponse:
type: array
items:
type: object
properties:
symbol:
type: string
description: The full contract symbol.
last_price:
type: number
description: The last price of the commodity contract.
last_updated:
type: integer
description: The Unix timestamp of when the price was last updated.
CommodityContractListResponse:
type: array
items:
type: object
properties:
symbol:
type: string
description: The full contract symbol.
commodity:
type: string
description: The name of the commodity.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
externalDocs:
description: API Ninjas documentation
url: https://api-ninjas.com/api