{Symbol} Real-Time Price API

You need to show a live gold price in your product, price an order in USD per troy ounce, or hedge exposure the moment a quote changes. By the end of this guide you will call the Metals-API latest endpoint for XAU (gold), read both ounces-per-USD and USD-per-ounce from one response, convert between units, and ship resilient code that handles timestamps, caching, and market closures.

What you can ship today with a live XAU quote

Developers, quants, and product teams use a real-time XAU stream to:

• Price jewelry and bullion catalogs dynamically in USD/oz, or USD/g with gram conversion.
• Power trading dashboards that show last price, spreads, and intraday moves.
• Trigger alerts, orders, and hedges when XAU crosses risk limits in USD/oz.
• Feed ERP/MRP workflows that re-value gold inventory and costs with the latest tick.

Metals-API delivers this via a simple JSON endpoint. You can find the full API reference in the Metals-API Documentation and available tickers in the Metals-API Supported Symbols. If you need managed connectivity and scale, see Metals-API MCP.

How XAU quotes are returned (base, units, inversion)

Metals-API quotes are, by default, delivered with base=USD. That means rates.XAU is “troy ounces of gold per 1 USD.” This is the inverse of the more familiar “USD per troy ounce.”

• rates.XAU = ounces per 1 USD (oz/USD). Multiply this by a USD amount to get ounces.
• rates.USDXAU = USD per 1 ounce (USD/oz). Multiply this by ounces to get USD value.

Many developers simply read rates.USDXAU to get USD/oz directly. If you only see rates.XAU, invert it: USD/oz = 1 / rates.XAU. The API also returns rates.USD = 1 by definition when base=USD.

Units: unless otherwise stated, metal rates are “per troy ounce.” For grams, convert using 1 troy ounce = 31.1034768 grams.

Quick start: Get the latest XAU

Use the latest endpoint and filter to XAU. The API returns both XAU and USDXAU in the same payload.

curl

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

Official JSON response

{"success":true,"timestamp":1791072480,"date":"2026-10-04","base":"USD","rates":{"XAU":0.0002415575631673,"USD":1,"USDXAU":4139.8000000000475}}

What to use from this payload:

• timestamp: Unix epoch seconds (UTC). Use this to time-stamp your cache and logs.
• date: Quoted calendar date of the rates.
• base: The base currency. Default is USD.
• rates.XAU: Ounces per 1 USD (oz/USD).
• rates.USDXAU: USD per 1 ounce (USD/oz). Use this directly in pricing UIs or P&L.

Python: fetch and convert

import requests
from decimal import Decimal, ROUND_HALF_UP

API_URL = "https://metals-api.com/api/latest"
API_KEY = "YOUR_API_KEY"

def get_xau_quote():
params = {
"access_key": API_KEY,
"symbols": "XAU"
}
r = requests.get(API_URL, params=params, timeout=10)
r.raise_for_status()
data = r.json()
if not data.get("success", False):
raise RuntimeError(f"API error: {data}")
ts = int(data["timestamp"])
base = data["base"]
rates = data["rates"]
# ounces per USD
oz_per_usd = Decimal(str(rates["XAU"]))
# USD per ounce (provided)
usd_per_oz = Decimal(str(rates["USDXAU"]))
return {
"timestamp": ts,
"base": base,
"oz_per_usd": oz_per_usd,
"usd_per_oz": usd_per_oz
}

def price_order_in_usd(ounces, usd_per_oz):
total = (Decimal(str(ounces)) * usd_per_oz).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
return total

if __name__ == "__main__":
quote = get_xau_quote()
print(f"USD/oz: {quote['usd_per_oz']}, oz/USD: {quote['oz_per_usd']}, ts={quote['timestamp']}")
# Example: price a 3.5 oz order
total_usd = price_order_in_usd(ounces=3.5, usd_per_oz=quote["usd_per_oz"])
print(f"3.5 oz costs ${total_usd}")

Apply the quote: conversions you’ll actually need

USD per ounce (rates.USDXAU) is typically what you display. Common operations:

• USD value of ounces: USD = ounces × rates.USDXAU.
• Ounces from USD budget: ounces = USD / rates.USDXAU. Or USD × rates.XAU (same result).
• Per gram pricing: USD/g = rates.USDXAU / 31.1034768; g/USD = rates.XAU × 31.1034768.
• Markup handling: final USD/oz = rates.USDXAU × (1 + markup_pct).

Remember the unit is troy ounce. If you show kilograms, convert with 1 kg = 32.1507466 troy ounces.

Update frequency, caching, and non-trading days

Depending on your plan, the latest endpoint updates on a schedule (for example, every 60 or 10 minutes). Use the timestamp field to determine freshness and design your caching. Suggested practices:

• Cache the last good response for slightly longer than your plan’s update cadence to avoid redundant calls (e.g., cache 65–90 seconds if your cadence is ~60s).
• Always display the as-of time to users (convert the Unix timestamp to local time if needed).
• On weekends or market holidays, expect the date to remain at the last market session; program your UI to show “As of YYYY-MM-DD HH:MM UTC.”
• Fallback: if the latest call fails, keep serving the most recent cached value and flag it as stale.

Beyond last price: intraday moves and spreads

When you need richer context than a last price, Metals-API provides focused endpoints you can add without changing your data model:

• Intraday endpoint: pull time-sliced intraday XAU for a single symbol to render minute-by-minute moves or compute VWAP. See intraday details in the documentation.
• Bid and Ask endpoint: retrieve top-of-book bid/ask for XAU to compute real trading spreads and slippage-aware valuations.

Keep these requests symbol-scoped to XAU to reduce payload sizes and response times. For other metal or currency codes, refer to the symbol directory.

Common pitfalls and how to avoid them

• Confusing base and quote. With base=USD, rates.XAU is oz/USD. If you need USD/oz, read rates.USDXAU or invert safely using high-precision decimals.
• Unit confusion. XAU is quoted per troy ounce, not avoirdupois ounce. Always convert grams/kilograms explicitly.
• Relying on system float. Use Decimal (Python) or BigNumber (JS) when inverting or multiplying, to prevent rounding drift in P&L.
• Ignoring timestamp. Display “as of” times and check staleness before firing alerts or orders.
• Over-polling. Respect the update cadence; add client-side caching and conditional fetch logic (e.g., only refresh if ts has changed).

Resilient error handling

• Network and HTTP errors: retry with jittered backoff (e.g., 200ms → 400ms → 800ms, max 3–5 attempts) and short timeouts.
• Partial outages: if success=false, keep your last good value and surface a non-blocking warning.
• Data validation: assert presence of rates.XAU and/or rates.USDXAU and sanity-check the magnitude before using it (e.g., reject zeros or negative values).
• Circuit breaking: if repeated failures occur, reduce poll frequency and stop spamming retries.

Security and deployment notes

• Do not ship your Metals-API key in client-side code. Proxy calls from your backend.
• Scope logs. Redact the access_key from request logs and monitoring dashboards.
• Separate keys per environment (dev/stage/prod) so you can rotate without downtime.

If you require dedicated infrastructure and SLAs, explore MCP for Managed Cloud plans.

How Metals-API empowers your stack

Metals-API provides real-time and historical pricing for precious and industrial metals with a simple REST surface. You can start with a single XAU latest quote and evolve to intraday, bid/ask, OHLC, and time-series without replatforming. The consistent JSON schema and explicit timestamps make it straightforward to integrate with ETL pipelines, research notebooks, risk engines, and e-commerce backends.

There is no free trial. If copper coverage is your primary need, the Copper Monthly option is available at $19.99/month. Review plan details and endpoint availability in the docs.

Implementation checklist for XAU real-time

• Decide which price to display: rates.USDXAU (USD/oz) is the common choice.
• Call latest with symbols=XAU and cache for the duration of your update cadence.
• Render “as of” using the timestamp (UTC) and user’s local time as needed.
• Convert for your UI: USD/oz → USD/g or USD/kg with precise constants.
• Add resilience: retries, stale-cache fallback, and validation.
• Optionally add intraday or bid/ask endpoints for richer analytics.

Notes on data interpretation

Metals-API aggregates data from multiple venues to produce consistent rates. The “latest” value is suitable for pricing and research dashboards; if you need a specific benchmark methodology, supplement your context with external references like the LBMA gold price overview. Your application’s behavior around benchmarks, fixing times, and venue selection should be explicit to end users.

Troubleshooting guide

• rates.USDXAU missing: invert rates.XAU with high precision: usd_per_oz = 1 / rates.XAU.
• Values look identical across requests: you may be fetching faster than your plan’s update cadence. Check timestamp; add a “only refresh when ts changes” guard.
• “success”: false: log the full JSON, keep serving cached last-good, and alert ops. Re-check your access_key and symbols.
• Weekend behavior: expect the date not to advance until the next market session. This is normal.

Endpoint references for XAU

Core you’ll use now:

• Latest: GET /api/latest with symbols=XAU

As your product grows, consider:

• Intraday (single-symbol time slices)
• Bid and Ask (spreads for trading-aware pricing)
• Time-series or OHLC (for charting and analytics)

See request parameters, plan eligibility, and response fields in the Metals-API Documentation. Confirm available tickers in Supported Symbols.

FAQ

Q: What’s the fastest way to show USD per oz for gold?
A: Call /api/latest with symbols=XAU and read rates.USDXAU from the response. It’s already USD/oz.

Q: The response shows ounces per USD. How do I invert safely?
A: Use high-precision math: USD/oz = 1 / rates.XAU. In Python, use Decimal; in JS, use a big number library.

Q: How should I handle weekends and holidays?
A: Expect the timestamp and date to reflect the last available market session. Keep serving cached values and label the as-of time.

Q: Can I fetch multiple symbols at once?
A: Yes, pass a comma-separated list to symbols, but for this guide we focus on XAU. Check the docs for exact parameter formatting.

Q: Is there a free trial?
A: No. To get access, create an account and choose a plan that fits your needs.

Ready to put a live XAU price into your app? Create your account and get your API key here: Register. If you need managed scale and SLAs, explore MCP. For more details on endpoints and parameters, see the Documentation and verify codes on the Symbols page.