{Symbol} Price API

You need to display the live gold price in your app, quote accurate USD/oz for checkout, or evaluate a hedge in near real time. By the end of this guide you’ll request the latest XAU price from Metals-API, read both oz per USD and USD per oz, convert to grams or kilograms, and cache responses safely for production.

Goal: Live XAU price you can ship today

We’ll implement a straightforward flow for gold (XAU):

• Fetch the latest XAU quote using the latest endpoint.
• Read USD per troy ounce directly from USDXAU (or invert XAU if needed).
• Convert to grams/kilograms for display or pricing engines.
• Optionally pull a single historical snapshot for context, and use Bid/Ask when you need trade-aware quotes.

If you are exploring other instruments, see the full set of symbols on the Metals-API Supported Symbols page.

Latest XAU: request, response, and fields you’ll actually use

The latest endpoint returns XAU quoted relative to USD by default. Two fields matter most for pricing:

• rates.XAU — troy ounces per 1 USD (oz/USD)
• rates.USDXAU — USD per 1 troy ounce (USD/oz)

If USDXAU is present, use it directly for USD per ounce. If it isn’t present on your plan or response, compute USD/oz as 1 / rates.XAU.

cURL you can copy

curl "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=XAU"

Official sample JSON (XAU only)

{"success":true,"timestamp":1790899860,"date":"2026-10-02","base":"USD","rates":{"XAU":0.00023954390839841,"USD":1,"USDXAU":4174.59999999999}}

What these fields mean for your code

• success: Boolean success flag. Check this before using rates.
• timestamp: Unix epoch seconds for when the price snapshot was generated.
• date: ISO date associated with the snapshot (e.g., trading day).
• base: The reference currency (default USD). All rates are relative to this.
• rates.XAU: Troy ounces per 1 USD (oz/USD). Invert if you need USD/oz.
• rates.USDXAU: USD per troy ounce (USD/oz). Use this directly when present.

Units: Metals-API quotes metals per troy ounce by default. 1 troy ounce = 31.1034768 grams.

Python example: get USD/oz and convert to grams

import requests

API_KEY = "YOUR_API_KEY"
URL = "https://metals-api.com/api/latest"
params = {
"access_key": API_KEY,
"symbols": "XAU"
}

r = requests.get(URL, params=params, timeout=10)
data = r.json()

if not data.get("success"):
raise RuntimeError(f"Metals-API error: {data}")

# Prefer USDXAU if available; otherwise invert XAU (oz per USD)
rates = data.get("rates", {})
usd_per_oz = rates.get("USDXAU")
if usd_per_oz is None:
xau_oz_per_usd = rates.get("XAU")
if not xau_oz_per_usd:
raise RuntimeError("Missing XAU rate in response.")
usd_per_oz = 1.0 / xau_oz_per_usd

# Convert to per-gram and per-kilogram
TROY_OUNCE_TO_GRAMS = 31.1034768
usd_per_gram = usd_per_oz / TROY_OUNCE_TO_GRAMS
usd_per_kg = usd_per_gram * 1000

print({
"timestamp": data.get("timestamp"),
"date": data.get("date"),
"usd_per_oz": usd_per_oz,
"usd_per_gram": usd_per_gram,
"usd_per_kg": usd_per_kg
})

Tip: Cache the full JSON payload for your polling interval and include the timestamp with any downstream price. If your UI or pricing logic only needs USD/oz and per-gram values, compute them once and store them alongside the raw response for auditability.

Units, inversion, and conversions (don’t skip this)

• Base currency: Responses here are relative to USD (base: "USD"). If you need another base, check the plan capabilities in the Metals-API Documentation.
• Two equivalent representations:
  • rates.XAU = oz per USD (oz/USD)
  • rates.USDXAU = USD per oz (USD/oz)
• Invert carefully: USD/oz = 1 / (oz/USD). Work in floating point with sufficient precision and avoid premature rounding.
• Troy ounces to metric: multiply or divide by 31.1034768 (grams per troy ounce).
• Display rounding: round at the presentation layer (e.g., USD/oz to 2 decimals; grams to 4–6 decimals if needed) but keep full precision internally.

Add context: historical snapshots and trade-aware quotes

Beyond real-time pricing, you will often need context for charts or sanity checks.

• Historical Rates endpoint: Request a single historical snapshot by date for XAU. Use it to validate moves day-over-day, backfill yesterday’s close, or populate a chart data point. See the endpoint details in the documentation.
• Bid and Ask endpoint: When your application cares about executable prices (e.g., quoting to customers or marking positions), use Bid/Ask to read bid, ask, and spread for XAU. This helps you avoid mid-price assumptions in a trading workflow.

If you need more than point-in-time values (e.g., daily bars), review the Open/High/Low/Close (OHLC) and time-series endpoints in the Metals-API Documentation.

Which XAU endpoint when? (Quick compare)

Production details that save time

Caching and polling

• Cache responses for at least your chosen polling interval to avoid redundant requests across services.
• Fan-out from your cache to downstream systems (web, mobile, pricing jobs) to reduce API load and maintain a consistent price across your stack.

Timestamps and trading days

• Use the timestamp for ordering and audit. It is Unix epoch seconds.
• The date field represents the associated calendar/trading date. When building time-series, expect gaps for non-trading days and fill or skip as your charting rules require. The example time-series payloads in the docs illustrate non-contiguous dates.

Error handling and resilience

• Always check success before reading rates and handle missing fields gracefully (e.g., compute USD/oz by inversion when USDXAU isn’t present).
• Implement retry with backoff on transient network errors. Log the full payload on parse errors for debugging.

Precision and rounding

• Keep raw decimal precision throughout calculations, and only round in the presentation layer. Metals pricing is sensitive to small differences, especially for large notional amounts.

Units in your UI and contracts

• Label units explicitly (USD/oz, USD/g, oz, g). Gold uses troy ounces by default; mixing with avoirdupois ounces is a common source of bugs.
• If you need per-gram or per-kilogram prices, compute once per response and reuse the computed values consistently.

Symbols, variants, and future expansion

• Confirm codes you plan to support on the Symbols page before you ship.
• If you later need related data (e.g., other precious metals for spread analysis), add those symbols to the same requests and reuse your parsing code.

End-to-end example: quoting a gold product in real time

1. Call latest with symbols=XAU and cache the response for your polling interval.
2. Read USDXAU or compute USD/oz by inversion. Convert to USD/g.
3. Apply your premium/markup and manufacturing costs per gram.
4. Round to your storefront rules (e.g., nearest $0.10) for display, but store the unrounded values for audit and customer service replays.
5. When the cached price expires, repeat the step and atomically update your prices sitewide.

Going beyond “last price”

• Day-over-day comparison: Pull yesterday’s historical snapshot and compute pct change to color-code your UI.
• Spread-aware pricing: Use Bid/Ask when you quote to customers so you aren’t pricing at a mid you can’t execute.
• Basic risk metrics: Derive 1–5 day realized range from OHLC or time-series to gate trading rules or inventory hedging. Find these endpoints in the documentation.

Security, keys, and environments

• Keep your API key in secure config or a secrets manager. Do not embed it in client-side code.
• Use separate keys or projects per environment (dev, staging, prod) so you can trace usage.
• For operational needs, consider the Managed Commercial Plans (MCP) for tailored support and integration options: Metals-API MCP.

Reference and further reading

• Endpoint parameters, authentication, and response fields: Metals-API Documentation
• All supported symbols and codes (verify XAU and any others you plan to use): Metals-API Supported Symbols
• LBMA overview on troy ounces and gold market conventions: London Bullion Market Association

FAQ

How do I get USD per troy ounce for XAU?
Use rates.USDXAU if present. Otherwise compute 1 / rates.XAU, since rates.XAU is oz per USD.

What unit are XAU prices returned in?
By default, metals are quoted per troy ounce. Convert to grams by dividing USD/oz by 31.1034768.

What should I do on weekends or market closures?
Expect gaps in historical series and minimal updates during closures. If you need a continuous chart, forward-fill from the last available snapshot with a clear “as of” timestamp in your UI.

How often should I poll the latest endpoint?
Match your polling interval to the update frequency available on your plan and cache results. Avoid unnecessary duplicate requests across services by centralizing the fetch.

Can I convert from USD to a fixed weight directly?
Yes. Get USD/oz (USDXAU or 1 / XAU) and divide by 31.1034768 for USD/g. Multiply by your grams or kilograms to price inventory or SKUs.

Ready to integrate XAU into your product? Create your API key now: Register. Then implement the latest call from this guide and fine-tune your workflow with the endpoints in the docs.