LogoCommodityPriceAPI

Real-Time Commodity Prices  API for Developers

Access live market rates for 240+ assets including Gold, Silver, WTI Crude, and Brent Oil. Integrate high-frequency JSON data with 60-second updates into any application in minutes.

Unlimited free trial for integrations. No credit card required.

Loading...
240+
Commodities
150+
Quote Currencies
99.97%
Uptime SLA
<80ms
Avg Response

Trusted by teams at

Valona IntelligenceRebel OilTía
Core Features

Everything you need to build with commodity data — 240+ symbols, 150+ quote currencies, one JSON API

title

240+ Commodities in One API

Query live and historical prices for 240+ commodities — precious metals, energy, agriculture, and industrial materials — through a single JSON API instead of juggling multiple data vendors.

title

Integrate in Under 5 Minutes

One API key, one REST call, one JSON response. Copy-paste examples take you from signup to your first live price in under 5 minutes — no SDK required.

title

7-Day Free Trial, Cancel Anytime

Simple monthly or annual plans with no long-term contracts. Start with a 7-day free trial, then upgrade, downgrade, or cancel whenever you like.

title

Exchange-Grade Data Sources

Prices aggregated from trusted global exchanges and financial institutions and refreshed second-by-second, so your application never runs on stale data.

title

Prices in 150+ Currencies

Get any commodity price denominated in the currency you need with a single quote parameter. 150+ world currencies supported out of the box.

01

02

03

Live Rates and Historical Data, 1 Call Away.

Fetch the latest spot rates the moment markets move, or pull the closing rate for any past date — each is a single GET request to one endpoint.

Every response is clean JSON with a unit and timestamp per symbol, ready to drop straight into dashboards, alerts, or pricing engines.

New — Official MCP Server

Connect Claude, Cursor & any AI agent to live commodity prices

The official CommodityPriceAPI MCP server exposes gold, silver, oil, and 240+ commodities as AI tools. One npx command — no code required. Ask your AI assistant for live rates, historical data, and fluctuations directly.

npx -y @commoditypriceapi/mcpSet up the MCP server
DOCUMENTATION

Commodity Price API Documentation

Simple and easy to use API for commodity prices. Get real-time and historical data for oil, gold, silver, corn, wheat, natural gas and more.

CommodityPriceAPI

CommodityPriceAPI provides a simple REST API for live and historical rates for 240+ commodities in a simple JSON format. Rates are available historically for all days going back up to 1st January, 1990.

This documentation provides complete details of the features and options available in this API.

Base API URL

https://api.commoditypriceapi.com/v3

Versioning

The API version is part of the URL path. The current version is v3, which this documentation describes. Earlier version '/v2' remain available at their own path and are not affected by changes to newer versions.

Authentication

The CommodityPriceAPI uses API keys to authenticate requests. Each request must contain your API key via an apiKey query parameter or x-api-key request header.

In order to use the API, you need to sign up. No credit card required. Once you've created your account, get your API key from your dashboard, where you can also extend your trial, manage your subscription, and monitor usage.

We strongly discourage the use of API keys in client-side JavaScript, as it will expose your API key to the public.

Get Your API Key

You can get your API key from the Dashboard page.

Do not share your API key in publicly accessible areas such as GitHub, client-side code, and so forth.

Send Your API Key

The API Key may be sent in two ways:

  1. Request Parameter — include an apiKey parameter in your request's query string.
  2. Request Header — include an x-api-key request header with each request.

Track Usage

You can track your API usage in the Dashboard and via the Usage endpoint.

Errors and Codes

The CommodityPriceAPI returns error status using both conventional HTTP codes and error messages within the JSON response body. The error body will have the following attributes:

Error Body

timestampString

ISO 8601 date-time string (e.g. 2026-09-07T10:27:50.362Z) identifying when the error response was generated.

pathString

The request path relative to the base URL, e.g. /rates/latest.

codeInteger

The HTTP status code of the error, repeated in the body (e.g. 400, 404).

errorString

A short, standardized error code indicating the type of error. Common values include VALIDATION_ERROR, UNAUTHORIZED, PAYMENT_REQUIRED, LIMIT_REACHED, SYMBOL_NOT_FOUND, etc. Useful for programmatic error handling.

messageString

A human-readable description providing details about the error. It explains what went wrong and may offer guidance on how to resolve the issue.

unresolvedObject

Optional. Present on 404 SYMBOL_NOT_FOUND responses from the latest, historical, time-series and fluctuation endpoints. Keyed by each requested symbol; every entry has a message and, when close matches exist, a suggestions array of valid symbols. The same object appears on 206 Partial Content responses (see below).

Partial Content (206)

The /rates/latest, /rates/historical, /rates/time-series and /rates/fluctuation endpoints accept a list of symbols. When at least one of them resolves but others do not, the API returns 206 Partial Content instead of 200. The body is the normal success body plus an unresolved object keyed by each requested symbol that is missing from rates.

Each entry carries one of three messages:

  • Did you mean …? — with a suggestions array of up to 6 supported symbols. Matching is case-insensitive and ignores punctuation, so zw, ZW SPOT and zwspot all suggest ZW-SPOT. Common aliases (e.g. XPT for platinum) and commodity names (e.g. soybean) are also recognised.
  • We don't support this symbol, please visit our symbols page to see supported symbols. — no close match was found.
  • This symbol is supported but no rate was available for this request. — the symbol is valid but has no data for this request.

If none of the requested symbols is supported, the API returns 404 SYMBOL_NOT_FOUND and the same unresolved object is appended to the error body. When every symbol resolves, the response is a plain 200 with no unresolved key.

206 is a success status: response.ok is true and the request is billed like a 200. Check unresolved (or the status code) to detect symbols that were dropped.

206 Partial Content

404 SYMBOL_NOT_FOUND

HTTP Status Codes

The table below lists the HTTP status codes the API returns. Success responses (200 and 206) carry the endpoint's response object; error responses carry the error body described above. The table covers the codes common to all endpoints; endpoint-specific errors are listed under each endpoint.

CodeErrorMessage
200—Request succeeded. All requested symbols were returned.
206—Request succeeded, but some requested symbols could not be returned. They are listed in the unresolved object of the response.
400VALIDATION_ERRORsymbols parameter is required in the query parameters.
401UNAUTHORIZEDAPI key is missing from the request. Please include your API key in the request headers.
402PAYMENT_REQUIREDPlease extend your trial or subscribe to a plan to continue using the API
402PAYMENT_REQUIREDUser does not have an active subscription.
402PAYMENT_REQUIREDMaximum symbols per request exceeded
403LIMIT_REACHEDAPI key usage limit reached, Please upgrade your plan.
403LIMIT_REACHEDYou have reached the maximum request count for the month. Please upgrade your plan to continue using the API.
404API_KEY_NOT_FOUNDAPI key is missing from the request. Please include your API key in the request headers.
404USER_NOT_FOUNDThe user with the specified API key was not found (Invalid API key).
404SYMBOL_NOT_FOUNDThe symbol is not supported, please visit the documentation for a list of supported symbols
429TOO_MANY_REQUESTSToo many requests, please try again in a minute
500SERVER_ERRORInternal Server Error

Requests to an unknown path return 404 with a body of the form { status, message, path }.

Supported Symbols

Browse the full list of commodity symbols supported by the API, including their category, default currency, and measuring unit.

View Supported Symbols

Quoted Currencies

Premium and Plus subscribers can request rates in any of the supported quote currencies. Browse the full list to find the currency code you need.

View Quoted Currencies

Usage Endpoint

GET/v3/usage

Returns the current usage and quota information for your account.

Endpoint

Request Object

  • apiKeystringrequired
    Your unique API key. Note: may also be passed via x-api-key header.

Response Object

  • planstring
    Your current plan name in lowercase (e.g. lite, premium, plus).
  • quotainteger
    Your current allotted quota.
  • usedinteger
    Your usage since start of month, subscription, or trial.

Response JSON

Symbols Endpoint

GET/v3/symbols

Returns the complete information of all supported commodities, including symbol, name, category, default quote currency (code, name, symbol), measuring unit, status and update interval. Deprecated symbols are included with status: "inactive" and a deprecationDate.

Endpoint

Request Object

  • apiKeystringrequired
    Your unique API key. Note: may also be passed via x-api-key header.

Response Object

  • successboolean
    true if the request was successful, false if there was an error.
  • symbolsobject []
    Array of available commodity symbols with their metadata.
  • symbols.symbolstring
    The symbol code to use in the symbols query parameter of the rate endpoints.
  • symbols.namestring
    Human-readable commodity name.
  • symbols.descriptionstring
    Short description of the commodity. May be empty for some symbols.
  • symbols.categorystring
    Commodity category, e.g. Metals, Energy, Agriculture, Industrial.
  • symbols.currencyobject
    Default quote currency: code, name and symbol.
  • symbols.unitobject
    Measuring unit: symbol and name.
  • symbols.statusstring
    active or inactive (deprecated; latest rates unavailable).
  • symbols.updateIntervalstring
    How often the rate updates. One of PER_SECOND, PER_MINUTE, PER_10_MINUTES, PER_HOUR, PER_DAY, PER_WEEK, PER_MONTH.
  • symbols.exchangestring
    Optional. Data source for the symbol, e.g. World Bank. Present only for some symbols.
  • symbols.deprecationDatestring
    Optional. Present only for inactive symbols. Format: YYYY-MM-DD.

Response JSON

Latest Rates

GET/v3/rates/latest

Returns the latest rates for the specified symbols. Depending on your subscription plan, the latest rates may be delayed by up to 10 minutes.

Lite users receive rates in the default quote currency of a commodity. Premium and Plus users can customize the quote currency via a query parameter.

Symbols that are unsupported, or that have no current rate, are reported in unresolved with a 206 Partial Content status. See Partial Content.

Latest rates for deprecated symbols are not available; however, you can access historical rates up to a symbol's deprecation date. View deprecated symbols.

Endpoint

Request Object

  • apiKeystringrequired
    Your unique API key. Note: may also be passed via x-api-key header.
  • symbolsstring []required
    Comma-separated list of commodity symbols. Case-insensitive; surrounding whitespace and duplicates are ignored.
  • quotestringoptional
    Target currency for the exchange rate; if omitted (or set to default), the default quote currency of each commodity is used. Ignored on the Lite plan. View supported quote currencies.

Response Object

  • successboolean
    Boolean indicator of API request success. true for successful requests.
  • timestampnumber
    Unix timestamp indicating when the response was generated.
  • ratesobject
    Object containing the current rates for each requested commodity, keyed by symbol.
  • metadataobject
    Object containing metadata for the symbols, such as their unit and quote currency.
  • unresolvedobject
    Only present on 206 and 404 SYMBOL_NOT_FOUND responses. Keyed by each requested symbol missing from rates, with a message and optional suggestions array. See Partial Content.
  • warningstring
    Only present when currency conversion for the requested quote is temporarily unavailable; rates are then returned in their default currencies.

Response JSON

HTTP Status Codes

CodeErrorMessage
200—All requested symbols were returned.
206—Some requested symbols could not be returned and are listed in unresolved.
400VALIDATION_ERRORsymbols parameter is required in the query parameters.
402PAYMENT_REQUIREDMaximum symbols per request exceeded
404SYMBOL_NOT_FOUNDThe symbol is not supported, please visit the documentation for a list of supported symbols
404QUOTE_NOT_FOUNDThe quote currency is invalid, please visit the documentation for a list of valid quote currencies

Historical Rates

GET/v3/rates/historical

Historical rates are available for most commodities since 1990-01-01. Query the API for historical rates by passing a date (format YYYY-MM-DD) as a URL parameter.

If the rate of a commodity for a specific date is unavailable, the API returns the most recent available rate from the same month along with its corresponding date.

For monthly commodities, only their closing rates are available in the historical data. See the available symbols.

Symbols that are unsupported, or that have no rate on the requested date and no fallback rate earlier in that month, are reported in unresolved with a 206 Partial Content status. If all symbols are supported but none has data for the date, the API returns 404 RATE_NOT_FOUND. See Partial Content.

Endpoint

Request Object

  • apiKeystringrequired
    Your unique API key. Note: may also be passed via x-api-key header.
  • symbolsstring []required
    Comma-separated list of commodity symbols. Case-insensitive; duplicates are ignored.
  • datestringrequired
    Date for which the rates are requested. Format: YYYY-MM-DD.

Response Object

  • successboolean
    Boolean indicator of API request success.
  • datestring
    Date for which the user requested the commodity price. Format: YYYY-MM-DD.
  • ratesobject
    Object containing the requested rates, keyed by symbol.
  • rates.datestring
    Date for which commodity prices were fetched. May differ from the requested date when the API falls back to the most recent available rate. Format: YYYY-MM-DD.
  • rates.opennumber
    The opening price of the commodity on the given date.
  • rates.highnumber
    The highest price of the commodity recorded on the given date.
  • rates.lownumber
    The lowest price of the commodity recorded on the given date.
  • rates.closenumber
    The closing price of the commodity on the given date.
  • unresolvedobject
    Only present on 206 and 404 SYMBOL_NOT_FOUND responses. Keyed by each requested symbol missing from rates, with a message and optional suggestions array.

Response JSON

HTTP Status Codes

CodeErrorMessage
200—All requested symbols were returned.
206—Some requested symbols could not be returned and are listed in unresolved.
400VALIDATION_ERRORsymbols parameter is required in the query parameters.
400VALIDATION_ERRORDate is required in query params.
400VALIDATION_ERRORInvalid Date Format (YYYY-MM-DD).
400VALIDATION_ERRORInvalid Date: The provided date does not exist.
402PAYMENT_REQUIREDMaximum symbols per request exceeded
404SYMBOL_NOT_FOUNDThe symbol is not supported, please visit the documentation for a list of supported symbols
404RATE_NOT_FOUNDno rates found for the specified date

Time Series

GET/v3/rates/time-series

Query the API for daily historical rates between two dates of your choice. The difference between start and end date should not exceed 1 year (365 days). Only dates for which data exists are returned; a symbol is omitted from a date it has no rate for.

For monthly commodities, only their closing rates are available in the time-series data.

Symbols that are unsupported, or that have no data on any date in the range, are reported in unresolved with a 206 Partial Content status. A symbol counts as resolved if it appears on at least one date; missing days for a resolved symbol are not reported. If all symbols are supported but none has data in the range, the API returns 404 DATA_NOT_FOUND. See Partial Content.

Endpoint

Request Object

  • apiKeystringrequired
    Your unique API key. Note: may also be passed via x-api-key header.
  • symbolsstring []required
    Comma-separated list of commodity symbols. Case-insensitive; duplicates are ignored.
  • startDatestringrequired
    Start date for the time series. Format: YYYY-MM-DD.
  • endDatestringrequired
    End date for the time series. Format: YYYY-MM-DD. Must not be before startDate.
The maximum difference between the start and end date is 1 year (365 days).

Response Object

  • successboolean
    Boolean indicator of API request success.
  • startDatestring
    Start date for the time series. Format: YYYY-MM-DD.
  • endDatestring
    End date for the time series. Format: YYYY-MM-DD.
  • ratesobject
    Object containing the requested rates, keyed by date (YYYY-MM-DD), then by symbol.
  • rates.opennumber
    The opening price of the commodity on the given date.
  • rates.highnumber
    The highest price of the commodity recorded on the given date.
  • rates.lownumber
    The lowest price of the commodity recorded on the given date.
  • rates.closenumber
    The closing price of the commodity on the given date.
  • unresolvedobject
    Only present on 206 and 404 SYMBOL_NOT_FOUND responses. Keyed by each requested symbol that appears on no date in rates, with a message and optional suggestions array.

Response JSON

HTTP Status Codes

CodeErrorMessage
200—All requested symbols were returned.
206—Some requested symbols could not be returned and are listed in unresolved.
400VALIDATION_ERRORsymbols parameter is required in the query parameters.
400VALIDATION_ERRORThe 'startDate' parameter is required in the query and must be a string.
400VALIDATION_ERRORThe 'endDate' parameter is required in the query and must be a string.
400VALIDATION_ERRORInvalid date format specified for start or end date
400VALIDATION_ERRORInvalid Date: The provided start date or end date does not exist.
400VALIDATION_ERRORstart date cannot be after end date
400VALIDATION_ERRORDate range exceeds the allowed limit.
402PAYMENT_REQUIREDMaximum symbols per request exceeded
404SYMBOL_NOT_FOUNDThe symbol is not supported, please visit the documentation for a list of supported symbols
404DATA_NOT_FOUNDNo data found for the specified date range

Fluctuation

GET/v3/rates/fluctuation

Returns information about how rates of different commodities fluctuate over a date range. Provide a startDate and endDate as query parameters and select which symbols you want to query. Unlike the time-series endpoint, there is no limit on the date range.

For monthly commodities, the fluctuation is computed between the first day of the start month and the first day of the end month. All numeric values are rounded to 2 decimal places.

Symbols that are unsupported, or that have no rate in the requested range, are reported in unresolved with a 206 Partial Content status. If all symbols are supported but none has data in the range, the API returns 404 DATA_NOT_FOUND. See Partial Content.

Endpoint

Request Object

  • apiKeystringrequired
    Your unique API key. Note: may also be passed via x-api-key header.
  • symbolsstring []required
    Comma-separated list of commodity symbols. Case-insensitive; duplicates are ignored.
  • startDatestringrequired
    Start date for the fluctuation. Format: YYYY-MM-DD.
  • endDatestringrequired
    End date for the fluctuation. Format: YYYY-MM-DD.

Response Object

  • successboolean
    Boolean indicator of API request success.
  • startDatestring
    Start date for the fluctuation. Format: YYYY-MM-DD.
  • endDatestring
    End date for the fluctuation. Format: YYYY-MM-DD.
  • ratesobject
    Object containing the requested rates per symbol.
  • rates.startRatenumber
    Starting rate for the fluctuation.
  • rates.endRatenumber
    Ending rate for the fluctuation.
  • rates.changenumber
    The change between the starting and ending rates. Negative values represent a decrease.
  • rates.changePercentnumber
    The change percent between the starting and ending rates. Negative values represent a decrease.
  • unresolvedobject
    Only present on 206 and 404 SYMBOL_NOT_FOUND responses. Keyed by each requested symbol missing from rates, with a message and optional suggestions array.

Response JSON

HTTP Status Codes

CodeErrorMessage
200—All requested symbols were returned.
206—Some requested symbols could not be returned and are listed in unresolved.
400VALIDATION_ERRORsymbols parameter is required in the query parameters.
400VALIDATION_ERRORThe 'startDate' parameter is required in the query and must be a string.
400VALIDATION_ERRORThe 'endDate' parameter is required in the query and must be a string.
400VALIDATION_ERRORInvalid Date Format (YYYY-MM-DD).
400VALIDATION_ERRORStart date cannot be after end date
400VALIDATION_ERRORInvalid Date: The provided start date or end date does not exist.
402PAYMENT_REQUIREDMaximum symbols per request exceeded
404SYMBOL_NOT_FOUNDThe symbol is not supported, please visit the documentation for a list of supported symbols
404DATA_NOT_FOUNDNo data found for the given date range
Loading...

Frequently Asked Questions

Get your API key today

CommodityPriceAPI is the easiest way to get real-time and historical prices for a diverse range of commodities. Our API is easy to use and can be integrated into your application in minutes.

Get API key