MetalCharts API reference

All 61 endpoints of the MetalCharts metals price API on one page: what each returns, the parameters it takes, the fields in its response, and a request you can run. It is generated from the same OpenAPI document the API serves.

Get a free key See pricing OpenAPI JSON

Basics

Base URL, authentication and formats

Live and historical prices for precious and base metals, plus the exchange data behind them: COMEX warehouse inventory and deliveries, LBMA vaults and clearing, Shanghai SGE and SHFE, India MCX premiums, Guangzhou GFEX warehouse receipts, and CFTC Commitments of Traders positioning. Commercial use is permitted on every plan including the free tier, which allows 200 requests a month. On the free tier, any public display of the data must show a visible link to https://metalcharts.org, such as "Metal prices by MetalCharts"; free-tier responses carry an X-Attribution header saying so. Paid plans need no link. Authenticate with the header Authorization: Bearer mc_live_..., or, from a spreadsheet or another tool that can't send headers, with api_key=mc_live_... on a GET request. Add format=csv to /v1/prices, /v1/history and other list endpoints for CSV. From the Pro plan, /v1/stream/prices pushes live prices as Server-Sent Events.

Base URL: https://api.metalcharts.org
Authentication: Send your key in a header: Authorization: Bearer mc_live_YOUR_KEY
Formats: JSON by default. Add format=csv to any endpoint whose response is a list to get the same rows as CSV.
Free tier: 200 requests a month, no card required. Commercial use is allowed on every plan.
Plans: Free $0, Starter $9/month, Basic $29/month, Pro $99/month, Ultimate $249/month, Enterprise $1,200/month.
Errors: 400 for an invalid parameter, 401 for a missing or invalid key, 403 when the request needs a higher plan or reaches past the plan's history, 429 when a key is over its per-minute limit. Error bodies are JSON.
Machine-readable: OpenAPI 3.0 document, and a hosted MCP server for AI assistants
Try it: Worked examples, the interactive docs and the status page

Quick start

Your first request

One call to /v1/prices returns every metal. The same request in five languages:

Gold price API in cURL

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/prices"

Every tracked metal comes back in one response; gold is under data.XAU.

Gold price API in Python

import requests

res = requests.get(
    "https://api.metalcharts.org/v1/prices",
    headers={"Authorization": "Bearer mc_live_YOUR_KEY"},
    timeout=10,
)
res.raise_for_status()

price = res.json()["data"]["XAU"]["price"]
print(f"Gold: ${price}")

Uses requests. raise_for_status turns a 401 or 429 into an exception rather than letting a bad payload through.

Gold price API in JavaScript

const res = await fetch(
  "https://api.metalcharts.org/v1/prices",
  { headers: { Authorization: "Bearer mc_live_YOUR_KEY" } },
);

if (!res.ok) throw new Error(`HTTP ${res.status}`);

const { data } = await res.json();
console.log(`Gold: ${data.XAU.price}`);

Native fetch, so it runs in Node 18 and above. Keep the key on your server; proxy browser requests through it.

Gold price API in PHP

<?php
$ch = curl_init("https://api.metalcharts.org/v1/prices");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer mc_live_YOUR_KEY"],
    CURLOPT_TIMEOUT => 10,
]);

$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code !== 200) {
    throw new RuntimeException("MetalCharts API returned $code");
}

$data = json_decode($body, true);
echo "Gold: " . $data["data"]["XAU"]["price"];

Plain cURL with no dependencies. Check the status code, because a failed call still returns a parseable body.

Gold price API in Go

req, _ := http.NewRequest(
    http.MethodGet, "https://api.metalcharts.org/v1/prices", nil,
)
req.Header.Set("Authorization", "Bearer mc_live_YOUR_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

var out struct {
    Data map[string]struct {
        Price float64 `json:"price"`
    } `json:"data"`
}
if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
    return err
}
fmt.Println("Gold:", out.Data["XAU"].Price)

Decoding into a narrow struct keeps the compiler honest about the field you actually use.

Index

All 61 endpoints

Each links to its parameters, response fields and example request below.

Spot prices and conversion

/v1/pricesLatest spot prices
/v1/stream/pricesLive price stream (Server-Sent Events)
/v1/metalsList supported metals
/v1/convertConvert between metals, currencies and units

Price history

/v1/history/{symbol}Price history for a metal
/v1/bulk/historyBulk daily history download

Exchange and regional data

/v1/shanghaiLatest Shanghai prices and premiums
/v1/shanghai/historyShanghai silver premium history
/v1/shanghai/gold/historyShanghai gold price history
/v1/india/ibjaIBJA gold rate
/v1/indiaLatest India MCX prices and premiums
/v1/india/historyIndia MCX premium history
/v1/shfe/settlementSHFE settlement prices
/v1/shfe/inventorySHFE warehouse inventory
/v1/comex/inventoryCOMEX warehouse inventory
/v1/comex/depositoriesCOMEX stocks and flows by depository
/v1/comex/volume-oiCOMEX volume and open interest
/v1/comex/delivery-noticesCOMEX delivery notices
/v1/sge/tradingSGE contract trading history
/v1/sge/benchmarkSGE gold and silver benchmark fixings
/v1/sge/inventorySGE vault inventory
/v1/gfex/settlementGFEX platinum and palladium settlement prices
/v1/gfex/premiumGFEX premium over Western prices
/v1/gfex/receiptsGFEX warehouse receipts
/v1/gfex/receipts/coverageGFEX warehouse receipts coverage
/v1/lbma/vaultLBMA vault holdings
/v1/lbma/clearingLBMA clearing statistics

Positioning, rates and reference data

/v1/currencyExchange rates
/v1/currency/historyExchange rate history
/v1/cotCommitments of Traders positioning
/v1/supplyVisible supply and inventory
/v1/ath/{symbol}All-time high for a metal
/v1/economic-calendarEconomic calendar events
/v1/fundingLatest perpetual funding rates
/v1/funding/venuesFunding rate venues
/v1/funding/{symbol}/historyFunding rate history for a perpetual
/v1/usageYour usage and limits

Markets, indices and instruments

/v1/market-statusExchange open and closed status
/v1/healthService health check
/v1/marketsLatest 24/7 market prices
/v1/markets/{symbol}/historyPrice history for a 24/7 market
/v1/indicesLatest market index values
/v1/indices/history/{symbol}History for a market index
/v1/instrumentsList tracked instruments
/v1/instruments/summaryInstrument counts by asset class
/v1/bullionRetail bullion dealer prices
/v1/bullion/{productId}Dealer quotes for a bullion product

Commodities

/v1/commoditiesLatest commodity prices
/v1/commodities/{symbol}/historyPrice history for a commodity

Cryptocurrencies

/v1/cryptoLatest cryptocurrency prices
/v1/crypto/{symbol}/historyPrice history for a cryptocurrency

ETFs

/v1/etfsLatest ETF prices
/v1/etfs/{symbol}/historyPrice history for an ETF

News and sentiment

/v1/newsLatest market news
/v1/news/feedPaginated news feed
/v1/news/searchSearch news articles
/v1/news/filtersNews filter values with counts
/v1/news/categoriesNews categories
/v1/news/sentiment/candles/{symbol}News sentiment candles for a metal
/v1/news/sentiment/{symbol}News sentiment for a metal
/v1/news/{symbol}Latest news for a symbol

Prices

Spot prices and conversion

Live prices for every metal in one request, in any supported currency, mass unit or gold karat.

Latest spot prices

GET/v1/prices

Latest spot prices for all supported assets (precious and base metals plus key benchmarks) in a single call, keyed by symbol. Prices are in US dollars per each market's own unit unless currency, unit or karat say otherwise; every quote states the currency and unit it is in, and a converted response carries the fx rate used (ECB reference rate). karat returns gold only, at nominal purity karat/24.

Parameter	In	Type	Description
symbols	query	string
currency	query	string	ISO 4217 code to quote in. Default USD. One of: USD, EUR, GBP, JPY, CHF, AUD, CAD, CNY, INR, SGD, HKD, NZD, SEK, NOK, DKK, MXN, BRL, ZAR, TRY, PLN, CZK, HUF, RON, ISK, ILS, KRW, IDR, MYR, PHP, THB, AED, SAR. Example: `EUR`
unit	query	string	Mass unit to quote per: toz, g, kg, lb, mt, tola (toz is the troy ounce; oz is accepted as an alias). Default: the market's own unit. Example: `g`
karat	query	string	Gold only: price 24, 23, 22, 21, 20, 18, 16, 15, 14, 12, 10, 9, 8-karat gold at nominal purity karat/24 (24K is the spot price). Example: `22`

Returns: Spot prices keyed by metal symbol.

Response field	Type	Description
success	boolean
data	object	Keyed by metal symbol. Without a symbols filter it covers XAU, XAG, XPT, XPD, HG, ALI, NI, ZN, PB, JBP, CO, LC, UXA; a metal with no stored price is left out.
count	number
source	string
cacheAge	number or null
isStale	boolean
timestamp	string (date-time)
_rid	string	Request id, for support.
currency	string	Currency of every quote in this response.
fx	object	Present when prices were converted from US dollars.
data.<key>	object
data.<key>.symbol	string
data.<key>.price	number
data.<key>.change24h	number or null
data.<key>.changePercent24h	number or null
data.<key>.high24h	number or null
data.<key>.low24h	number or null
data.<key>.exchange	string
data.<key>.marketType	string
data.<key>.timestamp	string (date-time)
data.<key>.open24h	number or null
data.<key>.bid	number or null	Indicative bid, a fixed spread below the mid price.
data.<key>.ask	number or null	Indicative ask, a fixed spread above the mid price.
data.<key>.stale	boolean	True when this quote's feed hasn't updated for more than five days.
data.<key>.currency	string	Currency the price fields are in.
data.<key>.unit	string	Mass unit the price is per.
data.<key>.karat	number	With `karat`: the karat priced.
data.<key>.purity	number	With `karat`: nominal purity, karat/24.
fx.rate	number	Units of `currency` per US dollar.
fx.date	string	Date of the rate.
fx.source	string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/prices"

Live price stream (Server-Sent Events)

GET/v1/stream/prices

Pushes spot prices as they change, as Server-Sent Events over HTTPS. The first event is snapshot with every requested quote ({"data": {"XAU": quote}, "timestamp"}); after that each change arrives as a price event ({"symbol": "XAU", ...quote}), and a : ping comment line keeps the connection open every 15 seconds. Quotes have the same fields as /v1/prices and honour currency, unit and karat the same way. Gold, silver, platinum and palladium update every few seconds while the market is open. The server closes a connection after an hour; reconnect when it does (EventSource clients do this on their own). Included from the Pro plan (1 connection); Ultimate allows 10 at once and Enterprise 50. Opening a connection counts as one request.

Parameter	In	Type	Description
symbols	query	string	Comma-separated metal symbols. Default: all of XAU, XAG, XPT, XPD, HG, ALI, NI, ZN, PB, JBP, CO, LC, UXA. Example: `XAU,XAG`
currency	query	string	ISO 4217 code to quote in. Default USD. One of: USD, EUR, GBP, JPY, CHF, AUD, CAD, CNY, INR, SGD, HKD, NZD, SEK, NOK, DKK, MXN, BRL, ZAR, TRY, PLN, CZK, HUF, RON, ISK, ILS, KRW, IDR, MYR, PHP, THB, AED, SAR. Example: `EUR`
unit	query	string	Mass unit to quote per: toz, g, kg, lb, mt, tola (toz is the troy ounce; oz is accepted as an alias). Default: the market's own unit. Example: `g`
karat	query	string	Gold only: price 24, 23, 22, 21, 20, 18, 16, 15, 14, 12, 10, 9, 8-karat gold at nominal purity karat/24 (24K is the spot price). Example: `22`

Returns: An event stream (text/event-stream).

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/stream/prices"

List supported metals

GET/v1/metals

Reference list of supported metals with their names, categories, and units.

Parameter	In	Type	Description
sort	query	string
order	query	string

Returns: Every tracked metal with its latest price.

Response field	Type	Description
success	boolean
data	object
data.items	array of object
data.sparklines	object	Recent price points per symbol, for inline charts.
data.items[].symbol	string
data.items[].name	string
data.items[].price	number
data.items[].category	string or null
data.items[].unit	string or null
data.items[].change24h	number or null
data.items[].change7d	number or null
data.items[].high24h	number or null
data.items[].low24h	number or null
data.items[].updatedAt	string (date-time) or null
data.sparklines.<key>	array of number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/metals"

Convert between metals, currencies and units

GET/v1/convert

Converts an amount between a metal, a currency and a mass unit: 10 g of gold in euros (from=XAU&to=EUR&amount=10&unit=g), how much silver 1,000 rupees buys (from=INR&to=XAG&unit=g), euros to yen, or grams to troy ounces. Metal prices are live spot (or the close on date), currency rates are ECB reference rates. karat prices gold at nominal purity karat/24. A date counts as history: Free reaches 30 days back, paid plans their history depth.

Parameter	In	Type	Description
fromrequired	query	string	A metal symbol (XAU), a currency (EUR) or a unit (g). Example: `XAU`
torequired	query	string	A metal symbol, a currency or a unit. Example: `EUR`
amount	query	string	Quantity of `from`. Default 1. Example: `10`
unit	query	string	For a metal: the unit its quantity is in (toz, g, kg, lb, mt, tola). Default: the metal's own unit. Example: `g`
karat	query	string	For gold to or from a currency: karat purity (karat/24). Example: `22`
date	query	string	YYYY-MM-DD: convert at that day's closing price and ECB rate instead of live. Counts as history for plan limits. Example: `2025-01-15`

Returns: The converted amount and the rate used.

Response field	Type	Description
success	boolean
result	number
rate	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/convert?from=XAU&to=EUR"

History

Price history

Daily bars back to 1966 for gold and silver, and intraday bars down to 15 minutes.

Price history for a metal

GET/v1/history/{symbol}

Historical price series for a metal. Symbols are the metal codes, not names: XAU (gold), XAG (silver), XPT (platinum), XPD (palladium), HG (copper), plus ALI, NI, ZN, PB, JBP, CO, LC and UXA.GOLD is not valid here; it belongs to /v1/markets. Use the range parameter (for example 1M, 6M, 1Y or ALL; MAX is accepted as a synonym for ALL) or a start date to set the window; start overrides range, and end (used only with start) defaults to now. interval picks the candle size. Supported intervals are 15m, 30m, 45m, 1h, 2h, 4h, 8h, 1d, 1w and 1M; intraday intervals read the interval candle tables and 1w/1M are aggregated from daily candles. Prices are in US dollars per the market's own unit unless currency, unit or karat say otherwise; each point is converted at the ECB reference rate in force on its date (FX history starts 1999-01-04, and earlier points are left out of a converted series). The response states the currency and unit it is in.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `XAU`
range	query	string
interval	query	string
start	query	string
end	query	string
currency	query	string	ISO 4217 code to quote in. Default USD. One of: USD, EUR, GBP, JPY, CHF, AUD, CAD, CNY, INR, SGD, HKD, NZD, SEK, NOK, DKK, MXN, BRL, ZAR, TRY, PLN, CZK, HUF, RON, ISK, ILS, KRW, IDR, MYR, PHP, THB, AED, SAR. Example: `EUR`
unit	query	string	Mass unit to quote per: toz, g, kg, lb, mt, tola (toz is the troy ounce; oz is accepted as an alias). Default: the market's own unit. Example: `g`
karat	query	string	Gold only: price 24, 23, 22, 21, 20, 18, 16, 15, 14, 12, 10, 9, 8-karat gold at nominal purity karat/24 (24K is the spot price). Example: `22`

Returns: OHLC series, oldest first.

Response field	Type	Description
success	boolean
data	array of object
symbol	string
range	string
startDate	string
endDate	string
count	number
source	string
exchange	string or null
_rid	string	Request id, for support.
data[].timestamp	string (date-time)
data[].price	number	Same as close. Kept for older consumers.
data[].open	number
data[].high	number
data[].low	number
data[].close	number
data[].volume	number	0 where the source publishes no volume.

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/history/XAU"

Bulk daily history download

GET/v1/bulk/historyFrom Ultimate

Every daily bar for the requested metals, back to the start of each series (October 1966 for gold and silver), as one CSV file with columns symbol, date, open, high, low, close, volume, currency, unit. currency and unit convert as on /v1/history (FX history starts 1999-01-04, so a converted file starts there). For an initial load or a nightly sync. Requires the Ultimate plan.

Parameter	In	Type	Description
symbols	query	string	Comma-separated metal codes. Default: all of XAU, XAG, XPT, XPD, HG, ALI, NI, ZN, PB, JBP, CO, LC, UXA. Example: `XAU,XAG`
currency	query	string	ISO 4217 code to quote in. Default USD. One of: USD, EUR, GBP, JPY, CHF, AUD, CAD, CNY, INR, SGD, HKD, NZD, SEK, NOK, DKK, MXN, BRL, ZAR, TRY, PLN, CZK, HUF, RON, ISK, ILS, KRW, IDR, MYR, PHP, THB, AED, SAR. Example: `EUR`
unit	query	string	Mass unit to quote per: toz, g, kg, lb, mt, tola (toz is the troy ounce; oz is accepted as an alias). Default: the market's own unit. Example: `g`

Returns: CSV file.

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/bulk/history"

Regional

Exchange and regional data

COMEX inventory and deliveries, LBMA vaults and clearing, Shanghai (SGE and SHFE), Guangzhou (GFEX) and India.

Latest Shanghai prices and premiums

GET/v1/shanghai

Latest Shanghai Gold Exchange spot prices and premium to Western pricing. price is USD per troy ounce, priceCNY is in the exchange's native unit (CNY/kg for silver, CNY/g for gold), and exchangeRate is USD/CNY. Shanghai silver prices (SGE and SHFE) include China's VAT and are returned as quoted; priceExVat, priceCNYExVat and premiumPercentExVat strip it at vatRate, and vatInclusive says whether a price carries VAT. Gold carries none, so its ex-VAT fields equal the raw ones.

Parameter	In	Type
symbols	query	string
type	query	string
series	query	string

Response field	Type	Description
success	boolean
data	object
count	number
source	string
series	string
cacheAge	number
isStale	boolean
timestamp	string (date-time)
data.XAU	object
data.XAG	object
data.XAU.symbol	string
data.XAU.exchange	string
data.XAU.marketType	string
data.XAU.price	number
data.XAU.priceCNY	number
data.XAU.timestamp	string (date-time)
data.XAU.exchangeRate	number
data.XAU.source	string
data.XAU.vatInclusive	boolean
data.XAU.vatRate	number
data.XAU.priceExVat	number
data.XAU.priceCNYExVat	number
data.XAU.premiumPercent	number
data.XAU.premiumPercentExVat	number
data.XAG.symbol	string
data.XAG.exchange	string
data.XAG.marketType	string
data.XAG.price	number
data.XAG.priceCNY	number
data.XAG.timestamp	string (date-time)
data.XAG.exchangeRate	number
data.XAG.source	string
data.XAG.vatInclusive	boolean
data.XAG.vatRate	number
data.XAG.priceExVat	number
data.XAG.priceCNYExVat	number

2 more nested fields are in the OpenAPI document.

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/shanghai"

Shanghai silver premium history

GET/v1/shanghai/historyFrom Pro

Historical Shanghai silver premium series versus Western pricing. shanghai and premiumPercent use the SGE silver price as quoted, which includes China's VAT; shanghaiExVat and premiumPercentExVat strip it at the rate in force on each date (13% since 2019-04-01, 16% from 2018-05-01, 17% before). Requires the Pro plan or higher.

Parameter	In	Type
range	query	string
series	query	string
start	query	string
end	query	string

Response field	Type	Description
success	boolean
data	array of object
vatInclusive	boolean
count	number
source	string
series	string
range	object
requestedRange	object
data[].date	string (date)
data[].premium	number or null
data[].premiumPercent	number or null
data[].premiumPercentExVat	number or null
data[].shanghai	number
data[].shanghaiExVat	number
data[].western	number or null
range.minDate	string (date)
range.maxDate	string (date)
range.totalRecords	number
requestedRange.start	string (date)
requestedRange.end	string (date)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/shanghai/history"

Shanghai gold price history

GET/v1/shanghai/gold/historyFrom Pro

Historical Shanghai gold price series. Gold carries no VAT, so shanghaiExVat and premiumPercentExVat equal the raw values. Requires the Pro plan or higher.

Parameter	In	Type
range	query	string
series	query	string
start	query	string
end	query	string

Response field	Type	Description
success	boolean
data	array of object
vatInclusive	boolean
count	number
source	string
series	string
range	object
requestedRange	object
data[].date	string (date)
data[].premium	number or null
data[].premiumPercent	number or null
data[].premiumPercentExVat	number or null
data[].shanghai	number
data[].shanghaiExVat	number
data[].western	number or null
range.minDate	string (date)
range.maxDate	string (date)
range.totalRecords	number
requestedRange.start	string (date)
requestedRange.end	string (date)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/shanghai/gold/history"

IBJA gold rate

GET/v1/india/ibjaFrom Pro

The India Bullion and Jewellers Association benchmark gold rate for 999 fine gold, in rupees per gram, one value per day. Requires the Pro plan or higher; depth follows the plan's history limit.

Parameter	In	Type	Description
range	query	string	One of 1M, 3M, 6M, 1Y, 2Y, 5Y, ALL. Default 1M.
type	query	string	latest: the newest rate only. Example: `latest`

Returns: Daily rates, oldest first.

Response field	Type	Description
success	boolean
data	array of object
data[].date	string
data[].price	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/india/ibja"

Latest India MCX prices and premiums

GET/v1/india

Latest MCX India spot prices and premium to Western pricing.

Parameter	In	Type	Description
symbols	query	string
fresh	query	string

Response field	Type	Description
success	boolean
data	object
futures	object
futuresMap	object
count	number
source	string
cacheAge	number
isStale	boolean
lastUpdated	string (date-time)
timestamp	string (date-time)
data.XAU	object
data.XAG	object
data.XAU.symbol	string
data.XAU.indiaSymbol	string
data.XAU.price	number
data.XAU.priceRaw	number
data.XAU.unit	string
data.XAU.unitRaw	string
data.XAU.premium	number
data.XAU.premiumPercent	number
data.XAU.source	string
data.XAU.timestamp	string (date-time)
data.XAG.symbol	string
data.XAG.indiaSymbol	string
data.XAG.price	number
data.XAG.priceRaw	number
data.XAG.unit	string
data.XAG.unitRaw	string
data.XAG.premium	number
data.XAG.premiumPercent	number
data.XAG.source	string
data.XAG.timestamp	string (date-time)
futures.symbol	string
futures.price	number
futures.priceINR	number
futures.timestamp	string (date-time)

13 more nested fields are in the OpenAPI document.

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/india"

India MCX premium history

GET/v1/india/historyFrom Pro

Historical MCX India premium series versus Western pricing. Requires the Pro plan or higher.

Parameter	In	Type
range	query	string
symbol	query	string
start	query	string
end	query	string

Response field	Type	Description
success	boolean
data	array of object
count	number
symbol	string
range	object
requestedRange	object
data[].date	string (date)
data[].india	number or null
data[].indiaINR	number or null
data[].premium	number or null
data[].premiumPercent	number or null
data[].western	number or null
range.minDate	string (date)
range.maxDate	string (date)
range.totalRecords	number
requestedRange.start	object or null
requestedRange.end	string (date)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/india/history"

SHFE settlement prices

GET/v1/shfe/settlementFrom Pro

Shanghai Futures Exchange settlement price history for a metal. Requires the Pro plan or higher. Every response carries asOf, ageDays and a stale flag, so you can tell a current series from one that has stopped updating without inspecting the array.

Parameter	In	Type	Description
symbolrequired	query	string	Required. cu, al, zn, pb, ni, sn, au or ag.
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y or ALL. Defaults to 1Y. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
symbol	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].total	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/shfe/settlement"

SHFE warehouse inventory

GET/v1/shfe/inventoryFrom Pro

Shanghai Futures Exchange warehouse inventory history for a metal. Requires the Pro plan or higher. Every response carries asOf, ageDays and a stale flag, so you can tell a current series from one that has stopped updating without inspecting the array.

Parameter	In	Type	Description
symbolrequired	query	string	Required. cu, al, zn, pb, ni, sn, au or ag.
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y or ALL. Defaults to 1Y. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
symbol	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].total	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/shfe/inventory"

COMEX warehouse inventory

GET/v1/comex/inventoryFrom Pro

COMEX warehouse inventory history for a metal symbol: exchange-wide registered, eligible and total per day. type=latest returns the newest day with the previous day's figures; type=depositories returns the newest day per depository, with that day's received, withdrawn and adjustment figures. For per-depository history use /v1/comex/depositories. Requires the Pro plan or higher. Every response carries asOf, ageDays and a stale flag, so you can tell a current series from one that has stopped updating without inspecting the array.

Parameter	In	Type	Description
symbolrequired	query	string	Required. Metal symbol: XAU, XAG, HG, XPT, XPD, ALI, ZN or PB (availability varies by endpoint).
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y or ALL. Defaults to 1Y. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
symbol	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].eligible	number or null
data[].registered	number or null
data[].total	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/comex/inventory"

COMEX stocks and flows by depository

GET/v1/comex/depositoriesFrom Pro

Daily COMEX warehouse stocks and flows per depository, laid out like CME's metal depository statistics report: for registered, eligible and total metal, the previous stock, received, withdrawn, net change, adjustment and today's stock. Rows are per report date, with activityDate giving the business day the movements happened. Received, withdrawn and adjustment are null on report dates before flowsAvailableFrom; stocks go back to February 2026 for most metals. Use /v1/comex/inventory for the exchange-wide totals, which go back to 1992 for gold and silver. Requires the Pro plan or higher.

Parameter	In	Type	Description
symbolrequired	query	string	Required. Metal symbol: XAU, XAG, HG, XPT, XPD, ALI, ZN or PB.
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y or ALL. Defaults to 1M. ALL returns the whole series, and MAX is accepted as a synonym for it. Ignored when start or end is given.
start	query	string	First report date, YYYY-MM-DD.
end	query	string	Last report date, YYYY-MM-DD. Defaults to today.
depository	query	string	Case-insensitive part of a depository name, e.g. jp morgan, brink or hsbc.

Response field	Type	Description
success	boolean
symbol	string
unit	string or null
range	string or null
start	string (date) or null
end	string (date)
flowsAvailableFrom	string (date) or null
asOf	string (date) or null
ageDays	number or null
stale	boolean
count	number
data	array of object
data[].date	string (date)	CME report date.
data[].activityDate	string (date) or null
data[].depository	string
data[].registered	object
data[].eligible	object
data[].total	object
data[].registered.previous	number or null
data[].registered.received	number or null
data[].registered.withdrawn	number or null
data[].registered.netChange	number or null
data[].registered.adjustment	number or null
data[].registered.today	number or null
data[].eligible.previous	number or null
data[].eligible.received	number or null
data[].eligible.withdrawn	number or null
data[].eligible.netChange	number or null
data[].eligible.adjustment	number or null
data[].eligible.today	number or null
data[].total.previous	number or null
data[].total.received	number or null
data[].total.withdrawn	number or null
data[].total.netChange	number or null
data[].total.adjustment	number or null
data[].total.today	number or null

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/comex/depositories"

COMEX volume and open interest

GET/v1/comex/volume-oiFrom Pro

COMEX volume and open interest for a metal symbol. Requires the Pro plan or higher. Every response carries asOf, ageDays and a stale flag, so you can tell a current series from one that has stopped updating without inspecting the array.

Parameter	In	Type	Description
symbolrequired	query	string	Required. Metal symbol: XAU, XAG, HG, XPT, XPD, ALI, ZN or PB (availability varies by endpoint).

Response field	Type	Description
success	boolean
symbol	string
data	object
data.date	string (date)
data.openInterest	number
data.volume	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/comex/volume-oi"

COMEX delivery notices

GET/v1/comex/delivery-noticesFrom Pro

COMEX delivery notice history for a metal symbol. Requires the Pro plan or higher. Every response carries asOf, ageDays and a stale flag, so you can tell a current series from one that has stopped updating without inspecting the array.

Parameter	In	Type	Description
type	query	string
symbolrequired	query	string	Required. Metal symbol: XAU, XAG, HG, XPT, XPD, ALI, ZN or PB (availability varies by endpoint).
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y or ALL. Defaults to 1Y. ALL returns the whole series, and MAX is accepted as a synonym for it.
year	query	string
date	query	string

Response field	Type	Description
success	boolean
symbol	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].dailyIssued	number
data[].dailyStopped	number
data[].date	string (date)
data[].exchange	string
data[].mtdCumulative	number or null
data[].settlementPrice	object or null
data[].symbol	string
data[].ytdCumulative	number or null

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/comex/delivery-notices"

SGE contract trading history

GET/v1/sge/tradingFrom Pro

Shanghai Gold Exchange contract trading history. Requires the Pro plan or higher.

Parameter	In	Type	Description
contractrequired	query	string	Required. Au99.99, Au99.95, Au(T+D), mAu(T+D), Ag(T+D) or Ag99.99.
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y or ALL. Defaults to ALL. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
contract	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].total	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/sge/trading"

SGE gold and silver benchmark fixings

GET/v1/sge/benchmarkFrom Pro

Shanghai Gold Exchange AM and PM benchmark fixings for gold or silver, one row per trading day dated in Shanghai time. Gold is in CNY per gram, silver in CNY per kilogram. New fixings are fetched on weekdays at 03:00 and 07:00 UTC, shortly after each auction. Requires the Pro plan or higher.

Parameter	In	Type	Description
metalrequired	query	string	Required. gold or silver.
range	query	string	One of 1Y, 2Y, 5Y or ALL. Defaults to ALL. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
metal	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].amPrice	number
data[].date	string (date)
data[].pmPrice	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/sge/benchmark"

SGE vault inventory

GET/v1/sge/inventoryFrom Pro

Shanghai Gold Exchange vault inventory history. Every response carries asOf, ageDays and a stale flag, so you can tell current inventory from an archived series without inspecting the array. Coverage is uneven and worth knowing before you build on it: silver vault stock updates normally, but the exchange feed has only ever produced ten gold vault-stock observations and the most recent is from January 2016, so metal=gold returns an archive rather than a current series. Requires the Pro plan or higher.

Parameter	In	Type	Description
metalrequired	query	string	Required. gold or silver. Example: `silver`
range	query	string	One of 1Y, 2Y, 5Y or ALL. Defaults to ALL. ALL returns the whole series, and MAX is accepted as a synonym for it. Example: `1Y`
type	query	string	Example: `latest`

Response field	Type	Description
success	boolean
metal	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].total	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/sge/inventory?metal=silver"

GFEX platinum and palladium settlement prices

GET/v1/gfex/settlementFrom Ultimate

GFEX settlement price history for platinum or palladium. Requires the Ultimate plan.

Parameter	In	Type	Description
symbolrequired	query	string	Required. pt or pd.
range	query	string	One of 1M, 3M, 6M, 1Y or ALL. Defaults to ALL. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
symbol	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].total	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/gfex/settlement"

GFEX premium over Western prices

GET/v1/gfex/premiumFrom Ultimate

GFEX platinum and palladium premium history versus Western pricing. Requires the Ultimate plan.

Parameter	In	Type	Description
symbol	query	string
range	query	string	One of 1M, 3M, 6M, 1Y or ALL. Defaults to 1Y. ALL returns the whole series, and MAX is accepted as a synonym for it.

Response field	Type	Description
success	boolean
data	array of object
count	number
symbol	string
cnyRate	number
requestedRange	object
data[].date	string (date)
data[].gfex	number
data[].premium	number or null
data[].premiumPercent	number or null
data[].western	number or null
requestedRange.start	string (date)
requestedRange.end	string (date)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/gfex/premium"

GFEX warehouse receipts

GET/v1/gfex/receiptsFrom Ultimate

GFEX registered warehouse receipts, per warehouse and per day. Covers lithium carbonate (LC), industrial silicon (SI) and polysilicon (PS), which is Chinese battery and solar supply-chain inventory published only in Chinese, plus platinum (XPT) and palladium (XPD). The default response is the per-warehouse breakdown for the most recent date, or an explicit date. Pass type=totals for the exchange-wide daily series instead. Warehouse names are the exchange's own and are passed through unaltered, because they are identifiers you match against exchange notices. Requires the Ultimate plan.

Parameter	In	Type	Description
symbolrequired	query	string	Required. LC, SI, PS, XPT or XPD. Example: `LC`
type	query	string	Example: `totals`
date	query	string	Example: `2026-09-17`
start	query	string	Example: `2026-01-01`
end	query	string	Example: `2026-09-17`

Response field	Type	Description
success	boolean
symbol	string
asOf	string (date)
total	number
count	number
data	array of object
data[].cancelled	number
data[].change	number
data[].date	string (date)
data[].quantity	number
data[].registered	number
data[].warehouse	string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/gfex/receipts?symbol=LC"

GFEX warehouse receipts coverage

GET/v1/gfex/receipts/coverageFrom Ultimate

Which symbols the GFEX receipts dataset covers, how many warehouses each spans, and the date range held. Requires the Ultimate plan.

This endpoint takes no parameters.

Response field	Type	Description
success	boolean
data	array of object
data[].from	string (date)
data[].name	string
data[].symbol	string
data[].to	string (date)
data[].warehouses	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/gfex/receipts/coverage"

LBMA vault holdings

GET/v1/lbma/vaultFrom Pro

LBMA vault holdings history for gold or silver. Requires the Pro plan or higher. Every response carries asOf, ageDays and a stale flag, so you can tell a current series from one that has stopped updating without inspecting the array.

Parameter	In	Type	Description
metalrequired	query	string	Required. gold or silver.
range	query	string	One of 1Y, 2Y, 5Y or ALL. Defaults to ALL. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
metal	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].total	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/lbma/vault"

LBMA clearing statistics

GET/v1/lbma/clearingFrom Pro

LBMA clearing statistics for gold or silver. Requires the Pro plan or higher. Every response carries asOf, ageDays and a stale flag, so you can tell a current series from one that has stopped updating without inspecting the array.

Parameter	In	Type	Description
metalrequired	query	string	Required. gold or silver.
range	query	string	One of 1Y, 2Y, 5Y or ALL. Defaults to ALL. ALL returns the whole series, and MAX is accepted as a synonym for it.
type	query	string

Response field	Type	Description
success	boolean
metal	string
range	string
asOf	string (date)
ageDays	number
stale	boolean
count	number
data	array of object
data[].date	string (date)
data[].transfers	number
data[].value	number
data[].volume	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/lbma/clearing"

Analytics

Positioning, rates and reference data

CFTC Commitments of Traders, visible supply, all-time highs, exchange rates, the economic calendar and funding rates.

Exchange rates

GET/v1/currency

Exchange rates for the 32 currencies the API quotes metals in: the US dollar, the ECB reference set and the pegged UAE dirham and Saudi riyal. rates holds units of each currency per one unit of base (USD by default). With date, the rates in force on that day; on weekends and holidays, the last publication before it. timestamp is in milliseconds.

Parameter	In	Type	Description
base	query	string	Currency the rates are quoted against. Default USD. Example: `EUR`
date	query	string	YYYY-MM-DD: the ECB reference rates in force that day (history from 1999-01-04). Counts as history for plan limits. Example: `2020-03-02`

Returns: Exchange rates keyed by ISO 4217 code.

Response field	Type	Description
success	boolean
base	string
date	string (date) or null
rates	object	Rate per unit of `base`, keyed by ISO 4217 code.
timestamp	number or null
source	string or null
currencies	array of object
rates.<key>	number
currencies[].code	string
currencies[].name	string or null
currencies[].symbol	string or null

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/currency"

Exchange rate history

GET/v1/currency/history

Daily ECB reference rates for one currency against base (units of currency per one base), one point per ECB publication day, back to 1999-01-04. Depth follows the plan's history limit.

Parameter	In	Type	Description
currencyrequired	query	string	The currency to chart. Example: `EUR`
base	query	string	Quoted against. Default USD. Example: `USD`
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y, ALL, MAX. Default 1M. Example: `1Y`
start	query	string	YYYY-MM-DD; overrides range. Example: `2024-01-01`
end	query	string	YYYY-MM-DD, used with start. Default today. Example: `2024-12-31`

Returns: Daily rates, oldest first.

Response field	Type	Description
success	boolean
data	array of object
data[].date	string
data[].rate	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/currency/history?currency=EUR"

Commitments of Traders positioning

GET/v1/cotFrom Pro

COT (Commitments of Traders) positioning history for a metal. Requires the Pro plan or higher.

Parameter	In	Type	Description
type	query	string
metalrequired	query	string	Required. XAU, XAG, HG, XPT or XPD.
range	query	string	One of 1M, 3M, YTD, 1Y, 5Y, 10Y or ALL. Defaults to 1Y. ALL returns the whole series, and MAX is accepted as a synonym for it.

Response field	Type	Description
success	boolean
metal	string
range	string
count	number
data	array of object
timestamp	string (date-time)
data[].cftcContractCode	string
data[].marketName	string
data[].metal	string
data[].mmLong	number
data[].mmNet	number
data[].mmShort	number
data[].mmSpreading	number
data[].nrLong	number
data[].nrNet	number
data[].nrShort	number
data[].openInterest	number
data[].orLong	number
data[].orNet	number
data[].orShort	number
data[].orSpreading	number
data[].pmLong	number
data[].pmNet	number
data[].pmShort	number
data[].reportDate	string (date)
data[].sdLong	number
data[].sdNet	number
data[].sdShort	number
data[].sdSpreading	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/cot"

Visible supply and inventory

GET/v1/supplyFrom Ultimate

Visible supply and inventory history for a metal. Requires the Ultimate plan.

Parameter	In	Type	Description
type	query	string
metalrequired	query	string	Required. XAU or XAG.
range	query	string	One of 1M, 3M, 6M, 1Y, 5Y or ALL. Defaults to 1Y. ALL returns the whole series, and MAX is accepted as a synonym for it.

Response field	Type	Description
success	boolean
metal	string
range	string
count	number
data	array of object
timestamp	string (date-time)
data[].comexEligible	number or null
data[].comexRegistered	number or null
data[].comexTotal	number
data[].date	string (date)
data[].lbmaTotal	number
data[].metal	string
data[].sgeTotal	object or null
data[].shfeTotal	number or null
data[].totalOz	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/supply"

All-time high for a metal

GET/v1/ath/{symbol}

All time high price and the date it was recorded. Symbols are metal codes such as XAU, XAG, XPT, XPD and HG, not names like GOLD.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `XAU`

Response field	Type	Description
success	boolean
data	object
data.symbol	string
data.price	number
data.recordedAt	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/ath/XAU"

Economic calendar events

GET/v1/economic-calendarFrom Pro

Upcoming and recent macroeconomic calendar events. Requires the Pro plan or higher.

Parameter	In	Type
country	query	string
impact	query	string
days	query	string

Response field	Type	Description
success	boolean
data	array of object
count	number
source	string
timestamp	string (date-time)
data[].actual	string or null
data[].country	string
data[].createdAt	string (date-time)
data[].eventDate	string (date-time)
data[].eventName	string
data[].forecast	string or null
data[].id	string
data[].impact	string
data[].previous	string or null
data[].source	string
data[].updatedAt	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/economic-calendar"

Latest perpetual funding rates

GET/v1/fundingFrom Pro

Latest perpetual funding rate for every symbol, optionally scoped to one venue. Funding is the periodic payment between longs and shorts that holds a perpetual near spot: a positive rate means longs pay shorts, so the sign and size read directly as crowd positioning. Rates are per-interval decimals, so 0.0000125 is 0.00125%. Coverage includes GOLD and SILVER perps alongside crypto and tokenised equities. Requires the Pro plan or higher.

Parameter	In	Type	Description
exchange	query	string	Example: `HYPERLIQUID`

Response field	Type	Description
success	boolean
count	number
data	array of object
data[].exchange	string
data[].fundingRate	number
data[].premium	number
data[].symbol	string
data[].time	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/funding"

Funding rate venues

GET/v1/funding/venuesFrom Pro

Venues currently publishing funding data, with how many symbols each covers and when it last printed. Requires the Pro plan or higher.

This endpoint takes no parameters.

Response field	Type	Description
success	boolean
data	array of object
data[].exchange	string
data[].latest	string (date-time)
data[].symbols	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/funding/venues"

Funding rate history for a perpetual

GET/v1/funding/{symbol}/historyFrom Pro

Funding rate history for one perpetual, oldest first. Symbols are the venue's own tickers such as BTC, ETH, GOLD, SILVER, NVDA; call /v1/funding for the full list. Set the window with range (1D, 1W, 1M, 3M, 6M, 1Y, ALL) or explicit start and end dates. Requires the Pro plan or higher.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `BTC`
exchange	query	string	Example: `HYPERLIQUID`
range	query	string	One of 1D, 1W, 1M, 3M, 6M, 1Y or ALL. Defaults to 1M. ALL returns the whole series, and MAX is accepted as a synonym for it. Example: `1M`
start	query	string	Example: `2026-01-01`
end	query	string	Example: `2026-09-01`

Response field	Type	Description
success	boolean
symbol	string
range	string
count	number
data	array of object
data[].exchange	string
data[].fundingRate	number
data[].premium	number
data[].symbol	string
data[].time	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/funding/BTC/history"

Your usage and limits

GET/v1/usage

Your plan, its per-minute and monthly limits, what you have used today and this month, and daily totals for the last 30 days. Free: calling it costs no weight.

This endpoint takes no parameters.

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/usage"

Markets

Markets, indices and instruments

Exchange status, market indices, 24/7 markets, the instrument catalogue and retail bullion dealer prices.

Exchange open and closed status

GET/v1/market-status

Current open or closed status and trading hours for supported exchanges.

Parameter	In	Type	Description
exchange	query	string

Returns: Open/closed state per venue.

Response field	Type	Description
success	boolean
exchanges	object	Keyed by venue: COMEX, LME, LBMA, SHFE, SGE, TOCOM, MCX.
timestamp	string (date-time)
exchanges.<key>	object
exchanges.<key>.name	string
exchanges.<key>.country	string
exchanges.<key>.currency	string
exchanges.<key>.isOpen	boolean
exchanges.<key>.isHoliday	boolean
exchanges.<key>.holidayName	string or null
exchanges.<key>.localTime	string	HH:mm in the venue's own timezone.
exchanges.<key>.timezone	string
exchanges.<key>.tradingHours	string	Local session windows, comma separated where a venue breaks.
exchanges.<key>.tradingDays	string
exchanges.<key>.nextOpen	object or null

3 more nested fields are in the OpenAPI document.

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/market-status"

Service health check

GET/v1/health

Service health and database connectivity. Free on every plan and weight 0, so a monitor can poll it without consuming quota.

This endpoint takes no parameters.

Response field	Type	Description
status	string
timestamp	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/health"

Latest 24/7 market prices

GET/v1/markets

Latest prices for 24/7 markets.

Parameter	In	Type	Description
sort	query	string
order	query	string

Returns: Every 24/7 market instrument with its latest price.

Response field	Type	Description
success	boolean
data	object
cacheAge	number or null
timestamp	string (date-time) or null
data.items	array of object
data.sparklines	object
data.items[].symbol	string
data.items[].name	string
data.items[].price	number
data.items[].assetClass	string or null
data.items[].exchange	string or null
data.items[].change24h	number or null
data.items[].change7d	number or null
data.items[].high24h	number or null
data.items[].low24h	number or null
data.items[].volume24h	number or null
data.items[].updatedAt	string (date-time) or null
data.sparklines.<key>	array of number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/markets"

Price history for a 24/7 market

GET/v1/markets/{symbol}/history

Historical series for a single 24/7 market. These symbols are plain names such as GOLD, SILVER, BTC and AAPL, unlike /v1/history which uses metal codes like XAU.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `GOLD`
range	query	string
interval	query	string

Response field	Type	Description
success	boolean
data	array of object
symbol	string
range	string
interval	string
count	number
timestamp	string (date-time)
data[].price	number
data[].timestamp	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/markets/GOLD/history"

Latest market index values

GET/v1/indicesFrom Basic

Latest values for market indices: DXY, SPX and DJI. DXY is a US dollar index computed by MetalCharts from daily reference exchange rates with the standard six-currency weights, updated once a day. Requires the Basic plan or higher.

Parameter	In	Type	Description
symbols	query	string

Response field	Type	Description
success	boolean
data	object
count	number
source	string
cacheAge	number
isStale	boolean
timestamp	string (date-time)
data.DJI	object
data.DXY	object
data.SPX	object
data.DJI.symbol	string
data.DJI.exchange	string
data.DJI.price	number
data.DJI.timestamp	string (date-time)
data.DJI.source	string
data.DXY.symbol	string
data.DXY.exchange	string
data.DXY.price	number
data.DXY.timestamp	string (date-time)
data.DXY.source	string
data.SPX.symbol	string
data.SPX.exchange	string
data.SPX.price	number
data.SPX.timestamp	string (date-time)
data.SPX.source	string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/indices"

History for a market index

GET/v1/indices/history/{symbol}From Basic

Historical series for a single market index. DXY is computed by MetalCharts from daily reference exchange rates with the standard six-currency weights: daily only, from January 1999. Requires the Basic plan or higher.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `DXY`
interval	query	string
range	query	string
limit	query	string

Response field	Type	Description
success	boolean
data	array of object
symbol	string
interval	string
range	object or null
count	number
source	string
data[].price	number
data[].timestamp	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/indices/history/DXY"

List tracked instruments

GET/v1/instruments

Every instrument the platform tracks, with the exchange and asset class it belongs to. Use this to discover the symbol a given endpoint expects: symbol spaces differ per route, so gold is XAU on /v1/history but GOLD on /v1/markets, and commodities are contract codes such as CL1. Filter with asset_class (commodity, crypto, equity, etf, fx, index, bond), exchange, or a case-insensitive search across symbol and name. Available on every plan including Free.

Parameter	In	Type	Description
asset_class	query	string	Example: `commodity`
exchange	query	string	Example: `COMEX`
search	query	string	Example: `gold`
limit	query	string	Example: `100`

Returns: The instrument catalogue.

Response field	Type	Description
success	boolean
count	number
data	array of object
data[].symbol	string
data[].name	string
data[].assetClass	string or null
data[].exchange	string or null
data[].marketType	string or null
data[].currency	string or null
data[].unit	string or null

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/instruments"

Instrument counts by asset class

GET/v1/instruments/summary

Instrument counts per asset class, with the exchanges each covers. A cheap way to see the shape of the catalogue before paging through it. Available on every plan including Free.

This endpoint takes no parameters.

Response field	Type	Description
success	boolean
total	number
data	array of object
data[].assetClass	string
data[].count	number
data[].exchanges	array of string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/instruments/summary"

Retail bullion dealer prices

GET/v1/bullionFrom Pro

Retail bullion prices across competing dealers, with each quote's premium over spot. Every product is normalised to its fine-ounce content so premiums are comparable across coins, bars and junk silver. best is the cheapest in-stock quote at or above spot, falling back to the cheapest such quote; a below-spot quote stays in quotes but is never best, and best is null when every fresh quote is below spot. Premium is the figure recorded at scrape time and travels with its own scrapedAt, so price and premium always agree. Filter with metal: gold, silver, platinum or palladium, or the code each product carries in metal (XAU, XAG, XPT, XPD), in any case. Quotes older than 7 days are excluded by default and never chosen as best, because individual dealer scrapers fail silently and a stale row would otherwise be presented as today's cheapest price; widen or narrow that with max_age_days, and read asOf, ageDays and staleQuotesExcluded to judge freshness yourself. Requires the Pro plan or higher.

Parameter	In	Type	Description
metal	query	string	Optional. gold, silver, platinum or palladium, or the code XAU, XAG, XPT or XPD, in any case. Example: `gold`
max_age_days	query	string	Example: `7`

Response field	Type	Description
success	boolean
maxAgeDays	number
count	number
data	array of object
data[].asOf	string (date-time)
data[].best	object
data[].fineOz	number
data[].form	string
data[].metal	string
data[].name	string
data[].productId	string
data[].purity	number
data[].quotes	array of object
data[].series	string
data[].staleQuotesExcluded	number
data[].weightLabel	string
data[].best.dealer	string
data[].best.inStock	boolean
data[].best.premiumPct	number
data[].best.priceCash	number
data[].best.scrapedAt	string (date-time)
data[].quotes[].ageDays	number
data[].quotes[].dealer	string
data[].quotes[].dealerId	string
data[].quotes[].inStock	boolean
data[].quotes[].premiumPct	number
data[].quotes[].priceCard	object or null
data[].quotes[].priceCash	number
data[].quotes[].scrapedAt	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/bullion"

Dealer quotes for a bullion product

GET/v1/bullion/{productId}From Pro

Every dealer quote for one bullion product. Product ids are slugs such as 1-oz-american-gold-eagle; call /v1/bullion for the full list. Quotes older than 7 days are excluded by default; widen with max_age_days. Requires the Pro plan or higher.

Parameter	In	Type	Description
productIdrequired	path	string	Example: `1-oz-american-gold-eagle`
max_age_days	query	string	Example: `7`

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/bullion/1-oz-american-gold-eagle"

Commodities

Energy, grains, softs and livestock futures prices and history.

Latest commodity prices

GET/v1/commoditiesFrom Basic

Latest prices for energy, agriculture, and industrial commodities. Symbols are contract codes such as CL1 (crude), CO1 (Brent), W_1 (wheat) and KC1 (coffee); call this endpoint to list them all. Requires the Basic plan or higher.

Parameter	In	Type	Description
sort	query	string
order	query	string

Response field	Type	Description
success	boolean
data	object
cacheAge	number
timestamp	string (date-time)
data.items	array of object
data.sparklines	object
data.items[].change24h	number
data.items[].change7d	number
data.items[].high24h	number
data.items[].low24h	number
data.items[].name	string
data.items[].price	number
data.items[].symbol	string
data.items[].updatedAt	string (date-time)
data.sparklines.<key>	array of number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/commodities"

Price history for a commodity

GET/v1/commodities/{symbol}/historyFrom Basic

Historical price series for a single commodity. Requires the Basic plan or higher.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `CL1`
range	query	string
interval	query	string

Response field	Type	Description
success	boolean
data	array of object
symbol	string
range	string
interval	string
count	number
timestamp	string (date-time)
data[].price	number
data[].timestamp	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/commodities/CL1/history"

Crypto

Cryptocurrencies

Prices and history for the tracked cryptocurrencies.

Latest cryptocurrency prices

GET/v1/cryptoFrom Basic

Latest cryptocurrency prices. Requires the Basic plan or higher.

Parameter	In	Type	Description
sort	query	string
order	query	string

Response field	Type	Description
success	boolean
data	object
cacheAge	number
timestamp	string (date-time)
data.items	array of object
data.sparklines	object
data.items[].change24h	number
data.items[].change7d	number or null
data.items[].high24h	number
data.items[].low24h	number
data.items[].marketCap	number
data.items[].name	string
data.items[].price	number
data.items[].symbol	string
data.items[].updatedAt	string (date-time)
data.items[].volume24h	number
data.sparklines.<key>	array of number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/crypto"

Price history for a cryptocurrency

GET/v1/crypto/{symbol}/historyFrom Basic

Historical price series for a single cryptocurrency. Requires the Basic plan or higher.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `BTC`
range	query	string
interval	query	string

Response field	Type	Description
success	boolean
data	array of object
symbol	string
range	string
interval	string
count	number
timestamp	string (date-time)
data[].price	number
data[].timestamp	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/crypto/BTC/history"

ETFs

Prices and history for metal and commodity exchange-traded funds.

Latest ETF prices

GET/v1/etfsFrom Basic

Latest prices for tracked ETFs such as GLD and SLV. Requires the Basic plan or higher.

Parameter	In	Type	Description
sort	query	string
order	query	string

Response field	Type	Description
success	boolean
data	object
cacheAge	number
timestamp	string (date-time)
data.items	array of object
data.sparklines	object
data.items[].aum	number
data.items[].change24h	number
data.items[].change7d	number
data.items[].high24h	number
data.items[].low24h	number
data.items[].marketCap	object or null
data.items[].name	string
data.items[].price	number
data.items[].provider	string
data.items[].symbol	string
data.items[].updatedAt	string (date-time)
data.items[].volume24h	number
data.sparklines.DBC	array of number
data.sparklines.GLD	array of number
data.sparklines.IAU	array of number
data.sparklines.PALL	array of number
data.sparklines.PDBC	array of number
data.sparklines.PPLT	array of number
data.sparklines.SLV	array of number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/etfs"

Price history for an ETF

GET/v1/etfs/{symbol}/historyFrom Basic

Historical price series for a single ETF. Requires the Basic plan or higher.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `GLD`
range	query	string
interval	query	string

Response field	Type	Description
success	boolean
data	array of object
symbol	string
range	string
interval	string
count	number
timestamp	string (date-time)
data[].price	number
data[].timestamp	string (date-time)

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/etfs/GLD/history"

News

News and sentiment

Market news, search, and news sentiment by metal.

Latest market news

GET/v1/news

Latest market news articles.

This endpoint takes no parameters.

Response field	Type	Description
success	boolean
articles	array of object
count	number
source	string
timestamp	string (date-time)
articles[].category	string
articles[].description	string
articles[].entities	object
articles[].id	string
articles[].imageUrl	string
articles[].keyTopics	array of string
articles[].marketImpact	string
articles[].publishedAt	string (date-time)
articles[].relevanceScore	number
articles[].sentiment	string
articles[].sentimentScore	number
articles[].source	string
articles[].subcategory	string
articles[].symbols	array of string
articles[].tickers	array of string
articles[].title	string
articles[].url	string
articles[].entities.locations	array of string
articles[].entities.orgs	array of string
articles[].entities.people	array of string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news"

Paginated news feed

GET/v1/news/feed

Paginated market news feed.

Parameter	In	Type
category	query	string
symbols	query	string
sources	query	string
limit	query	string
offset	query	string
since	query	string
timePeriod	query	string
sort	query	string
impact	query	string
sourceTypes	query	string
excludeSourceTypes	query	string

Response field	Type	Description
success	boolean
articles	array of object
grouped	object
count	number
total	number
hasMore	boolean
timestamp	string (date-time)
articles[].category	string
articles[].description	string
articles[].entities	object
articles[].id	string
articles[].imageUrl	string
articles[].keyTopics	array of string
articles[].marketImpact	string
articles[].publishedAt	string (date-time)
articles[].relevanceScore	number
articles[].sentiment	string
articles[].sentimentScore	number
articles[].source	string
articles[].subcategory	string
articles[].symbols	array of string
articles[].tickers	array of string
articles[].title	string
articles[].url	string
articles[].entities.locations	array of string
articles[].entities.orgs	array of string
articles[].entities.people	array of string
grouped.Today	array of string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news/feed"

Search news articles

GET/v1/news/search

Search news articles by keyword. Costs 3 weight per request.

Parameter	In	Type	Description
q	query	string

Response field	Type	Description
success	boolean
article	object
timestamp	string (date-time)
article.id	string
article.title	string
article.description	string
article.url	string
article.source	string
article.publishedAt	string (date-time)
article.imageUrl	string
article.sentiment	string
article.symbols	array of object
article.category	string
article.sentimentScore	number
article.relevanceScore	number
article.marketImpact	string
article.keyTopics	array of string
article.subcategory	string
article.entities	object
article.tickers	array of string
article.entities.orgs	array of string
article.entities.people	array of object
article.entities.locations	array of object

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news/search"

News filter values with counts

GET/v1/news/filters

Every filter value available on the news endpoints, with a count per value: sources, categories and symbols. Call this to build a filter UI rather than hard-coding the options.

This endpoint takes no parameters.

Response field	Type	Description
success	boolean
filters	object
totalArticles	number
timestamp	string (date-time)
filters.sources	array of object
filters.categories	array of object
filters.symbols	array of object
filters.sourceTypes	array of object
filters.sources[].count	number
filters.sources[].label	string
filters.sources[].value	string
filters.categories[].count	number
filters.categories[].label	string
filters.categories[].value	string
filters.symbols[].count	number
filters.symbols[].label	string
filters.symbols[].value	string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news/filters"

News categories

GET/v1/news/categories

The distinct news categories currently in use, for populating a category filter.

This endpoint takes no parameters.

Response field	Type	Description
success	boolean
categories	array of object
timestamp	string (date-time)
categories[].count	number
categories[].icon	string
categories[].id	string
categories[].label	string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news/categories"

News sentiment candles for a metal

GET/v1/news/sentiment/candles/{symbol}From Ultimate

News sentiment aggregated into OHLC-style candles, so sentiment can be charted alongside price. Requires the Ultimate plan.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `XAU`
interval	query	string
range	query	string

Response field	Type	Description
success	boolean
symbol	string
interval	string
range	string
data	array of object
count	number
timestamp	string (date-time)
data[].avgConfidence	number
data[].avgScore	number
data[].bearishCount	number
data[].bullishCount	number
data[].close	number
data[].high	number
data[].low	number
data[].neutralCount	number
data[].open	number
data[].timestamp	string (date-time)
data[].volume	number

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news/sentiment/candles/XAU"

News sentiment for a metal

GET/v1/news/sentiment/{symbol}From Ultimate

AI-scored news sentiment for one metal, aggregated across articles. Requires the Ultimate plan.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `XAU`
limit	query	string

Response field	Type	Description
success	boolean
symbol	string
sentiments	array of object
count	number
timestamp	string (date-time)
sentiments[].articleId	string
sentiments[].articleTitle	string
sentiments[].assetClass	string
sentiments[].confidence	number
sentiments[].impact	string
sentiments[].publishedAt	string (date-time)
sentiments[].reasoning	string
sentiments[].relationship	string
sentiments[].score	number
sentiments[].sentiment	string
sentiments[].symbol	string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news/sentiment/XAU"

Latest news for a symbol

GET/v1/news/{symbol}

Latest news articles filtered to a specific asset symbol.

Parameter	In	Type	Description
symbolrequired	path	string	Example: `XAU`
includeTwitter	query	string
sourceTypes	query	string
limit	query	string

Response field	Type	Description
success	boolean
symbol	string
articles	array of object
count	number
source	string
timestamp	string (date-time)
articles[].category	string
articles[].description	string
articles[].entities	object
articles[].id	string
articles[].imageUrl	string
articles[].keyTopics	array of string
articles[].marketImpact	string
articles[].publishedAt	string (date-time)
articles[].relevanceScore	number
articles[].sentiment	string
articles[].sentimentScore	number
articles[].source	string
articles[].subcategory	string
articles[].symbols	array of string
articles[].tickers	array of string
articles[].title	string
articles[].url	string
articles[].entities.locations	array of string
articles[].entities.orgs	array of string
articles[].entities.people	array of string

curl -H "Authorization: Bearer mc_live_YOUR_KEY" \
  "https://api.metalcharts.org/v1/news/XAU"

Limits

How rate limits and allowances work

The numbers for each plan are on the pricing page. The rules are the same on every plan:

What a request costs: Every call costs weight. Spot prices, market status, instruments and most other endpoints cost 1. History and news cost 2. News search and sentiment cost 3. Checking your own usage at /v1/usage costs 0. Both limits are counted in weight, so a 10,000 allowance is 10,000 spot calls or 5,000 history calls.
The per-minute limit is per key: Each API key has its own per-minute limit, counted in fixed one-minute windows that reset at the start of every minute (UTC). Go over it and that key gets a 429 with a Retry-After header giving the seconds until the next minute. Your other keys are unaffected.
The monthly allowance is per account: On plans that have one, the monthly allowance is shared by all of your keys and counted per calendar month in UTC. It resets at 00:00 UTC on the 1st. We email you at 80% and 100% of it. Requests keep working to 10% past it; after that every request returns a 429 saying the monthly quota is exceeded, until the reset or until you upgrade.
What counts and what doesn't: Every request with a valid key for data your plan includes counts toward both limits. A request refused with a 429 counts toward the per-minute limit, so a key that keeps retrying stays refused, but not toward the monthly allowance. A request with a missing or invalid key (401), or for data your plan doesn't include (403), counts toward neither.
No surprise bills: Going over a limit never charges you and never upgrades your plan. You change plans yourself from the pricing page or the API console: an upgrade charges only the difference for the rest of the billing period, a downgrade credits the unused time to your next invoices, and the new limits apply to your keys within 20 seconds.
Every response tells you where you stand: Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used and X-RateLimit-Reset for the current minute. On plans with a monthly allowance they also carry X-RateLimit-Month-Limit, X-RateLimit-Month-Remaining, X-RateLimit-Month-Used, X-RateLimit-Month-Grace-Limit (where refusals start) and X-RateLimit-Month-Reset.

Start with a free key

200 requests a month, no card required, and every endpoint on this page documented in OpenAPI 3.0.

Get a free key Metals API overview