{Symbol} Convert API

You need to quote, convert, and settle gold (XAU) amounts in real time—for example, pricing a 14 g gold pendant at checkout, converting a trade P&L from ounces to USD, or normalizing datasets for backtesting. By the end of this guide you’ll be able to use the XAU Convert API to convert between USD and XAU precisely, fetch the latest gold price in both oz/USD and USD/oz terms, and wire the results into your app with correct units, timestamps, and caching.

What we’re solving: precise USD ↔ XAU conversions for pricing and P&L

Most gold workflows need two things:

• Convert an input amount (USD or weight) into its XAU equivalent (troy ounces of gold) or vice versa.
• Display or use the latest spot price “USD per troy ounce” for quoting, hedging, or valuation.

Metals-API provides both with two endpoints you’ll actually use day-to-day:

• Convert endpoint: compute USD ↔ XAU conversions at time of request.
• Latest endpoint: read the current XAU rate in oz/USD and USD/oz, then do your own math locally.

If you’re integrating or testing symbols beyond gold, the definitive list is here: Metals-API Supported Symbols. This article stays focused on XAU only.

How XAU quotes work in Metals-API (read before you code)

Metals-API’s default base currency is USD. That means:

• rates.XAU = troy ounces of gold per 1 USD (oz/USD).
• rates.USDXAU = USD per 1 troy ounce (USD/oz), i.e., the direct spot price you likely display.

Both representations are equivalent. For example, if rates.XAU = 0.0002395 oz per USD, then USDXAU ≈ 1 / 0.0002395 ≈ 4174.6 USD per oz. Use USDXAU when available to avoid floating-point inversion errors.

Units and conversions you will use:

• All XAU quantities are in troy ounces (ozt), not avoirdupois ounces.
• 1 troy ounce = 31.1034768 grams.
• To price grams in USD: grams ÷ 31.1034768 = ozt, then multiply by USDXAU.
• To get XAU from USD using latest: XAU = USD × rates.XAU.

Read the full API surface here: Metals-API Documentation. For account setup and keys: Register.

Quick start: USD ↔ XAU using the Convert endpoint

The Convert endpoint is a one-call computation that returns the converted amount. Typical use cases include checkout quoting, invoice generation, and settlement calculations where you want the API to do the math immediately for a given amount.

Convert USD to XAU (curl)

curl -G https://metals-api.com/api/convert \
--data-urlencode "access_key=YOUR_API_KEY" \
--data-urlencode "from=USD" \
--data-urlencode "to=XAU" \
--data-urlencode "amount=1000"

Interpretation:

• from=USD, to=XAU: return troy ounces of gold equivalent to the USD amount.
• amount=1000: ask the API to convert $1,000 into XAU.

This is ideal when you need a one-off converted figure without handling inversion or units yourself.

Get the latest XAU price for your own conversions

When you want full control, fetch the current rate and compute locally. You’ll use the Latest endpoint with symbols restricted to XAU and USDXAU.

Latest gold price (curl)

curl -G "https://metals-api.com/api/latest" \
--data-urlencode "access_key=YOUR_API_KEY" \
--data-urlencode "symbols=XAU,USDXAU"

Official response sample (use these fields)

The following is an official Metals-API response for XAU. Use these field names and shapes in your integration:

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

What you’ll actually use:

• timestamp: Unix time (seconds). Use it for caching and UI “as of” display.
• date: Calendar date of the rate.
• base: USD. All rates are quoted relative to 1 USD unless you change base (see docs).
• rates.XAU: troy ounces per 1 USD (oz/USD). For converting USD → XAU.
• rates.USDXAU: USD per troy ounce (USD/oz). For pricing ounces or weights in USD.

Python example: read USDXAU and compute grams → USD and USD → XAU

import requests

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

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

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

ts = data["timestamp"]
xau_per_usd = data["rates"]["XAU"] # oz per 1 USD
usd_per_oz = data["rates"]["USDXAU"] # USD per 1 oz (spot)

# Example 1: price a 14 g item in USD
grams = 14.0
troy_oz = grams / 31.1034768
usd_price = troy_oz * usd_per_oz

# Example 2: convert $1,000 to XAU
usd_amount = 1000.0
xau_amount = usd_amount * xau_per_usd

print({
"as_of_timestamp": ts,
"usd_per_oz": usd_per_oz,
"xau_from_1000_usd": xau_amount,
"usd_for_14g": usd_price
})

Notes:

• Always prefer rates.USDXAU for USD/oz; no inversion required.
• For USD → XAU, multiply by rates.XAU (oz/USD).

End-to-end checkout flow for XAU pricing

Let’s wire a realistic flow for a jewelry checkout that prices items by weight and locks an FX-like rate during the payment window.

1. Fetch latest once per N seconds using symbols=XAU,USDXAU and cache locally keyed by timestamp.
2. Compute per-SKU base price = (grams ÷ 31.1034768) × USDXAU.
3. Add making costs, margin, and taxes in USD; round using your business rule (e.g., to $0.01 or $0.05).
4. At checkout finalization, either:
   • Re-quote using latest and show “as of” timestamp, or
   • Call Convert (from=USD, to=XAU or from=XAU, to=USD) to snapshot the payable/receivable at that moment.

For an ops view or risk report, reuse the cached USDXAU to compute fair values and P&L without extra API hits.

Operational details that save time

• Base currency: Default is USD. That’s why you see XAU (oz/USD) and USDXAU (USD/oz). If you change the base, field meanings change—review the Documentation before doing so.
• Units: XAU is always troy ounces. Convert grams or kilograms to troy ounces before multiplying by USDXAU.
• Timestamps and timezone: timestamp is Unix seconds; display it in your user’s timezone. date corresponds to the rate’s calendar date.
• Caching: Cache the full latest payload keyed by timestamp. Avoid polling faster than your plan’s update frequency; reuse cached values across user sessions and services until a newer timestamp arrives.
• Weekends/market closures: If the market is closed, latest may retain the last available price. For backfills, use the Historical or Time-Series endpoints to align to business days; for live quotes, display the “as of” time clearly.
• Numerical precision: Keep USDXAU and computed USD values in Decimal or high-precision floats internally. Round only when rendering or committing to a ledger.
• Error handling: Check success in responses. If false, do not use partial fields; log and retry with backoff.

Choosing between Convert and Latest

• Use Convert when you want an API-returned converted amount for a specific from/to/amount triple, e.g., $1,250 → XAU, or 0.5 XAU → USD for an order settlement. It’s concise and reduces your app-side math.
• Use Latest when you need the rate itself (USDXAU or XAU per USD), want to price many items from one fetch, or plan to cache and share the rate across services.

For larger data pulls (e.g., charting or VaR backtests), see Time-Series and Historical in the Documentation. Start with symbols here: Symbols.

Patterns for developers integrating XAU pricing

Pattern A: Local conversions from latest

Fetch once, compute many prices:

• Fetch latest with symbols=XAU,USDXAU.
• In memory: price SKUs (weight-based), compute P&L, and expose a “current gold spot” label.
• Refresh on a timer or when a new timestamp appears.

Pattern B: Snapshot conversions with Convert

For commits or settlements:

• On “place order,” call /api/convert to snapshot the exact amount in your settlement currency or in XAU.
• Store the response (including timestamp and rate) with the transaction for auditability.

Pattern C: Mixed mode

• Use latest for UI and cart calculations; re-confirm totals with convert at payment to lock in the precise amount reflected by an API-returned rate and timestamp.

Integrating into pricing engines, trading tools, and ERP

Because Metals-API returns both oz/USD (XAU) and USD/oz (USDXAU), you can keep your engine unit-agnostic. Use dependency injection to pass an IPriceSource that provides:

• get_spot_usd_per_oz() → float or Decimal
• get_xau_per_usd() → float or Decimal
• get_as_of_unix() → int

This decouples UI/ERP/trading logic from the wire format and helps with testing (stub responses keyed by timestamp). For data governance or permissioning, review your product’s access controls against your account in MCP.

Validation and monitoring

• Cross-check USDXAU against an independent reference during integration or monitoring windows. Public sources include LBMA price pages and CME Gold futures quotes (not identical instruments; use for sanity checks).
• Alert on stale timestamps (e.g., if no newer timestamp after your expected cadence).
• Log symbol lists and parameters used in each request for reproducibility.

Security and reliability

• Store your Metals-API key in a secure secret manager; do not embed it in mobile apps.
• Use connection and read timeouts (e.g., 10 s) and retries with exponential backoff.
• Memoize conversions during a checkout session to avoid re-quoting unexpectedly.

Common XAU conversions you’ll implement

• USD → XAU: xau = usd × rates.XAU.
• XAU → USD: usd = xau × rates.USDXAU.
• Grams → USD: usd = (grams ÷ 31.1034768) × rates.USDXAU.
• USD → grams: grams = (usd × rates.XAU) × 31.1034768.

End-to-end example workflow with both endpoints

1. On app start, call latest (symbols=XAU,USDXAU), store timestamp and rates in cache.
2. Price all SKUs client-side using cached USDXAU; show “as of” with timestamp.
3. At payment:
   • Call convert with from=USD, to=XAU, amount=cart_total_usd to get the exact XAU for ledgering, or
   • Call convert with from=XAU, to=USD if your cart is denominated in weight.
4. Persist the convert response along with the cached latest payload used for pre-quote, so support can reconcile any deltas.

Why developers choose Metals-API for XAU integrations

• Unified, simple JSON across latest and convert.
• Consistent units (troy ounces) and clear reversal field USDXAU.
• Coverage of real-time and historical needs through a consistent REST design.

Explore more at metals-api.com. For symbols and attributes, always confirm in Symbols.

FAQ

Q: Should I use rates.XAU or rates.USDXAU?
A: Use rates.USDXAU (USD/oz) when you need to price weights in USD. Use rates.XAU (oz/USD) when converting USD to ounces. They’re reciprocals; prefer USDXAU to avoid doing 1/x locally.

Q: How do I convert grams to USD correctly?
A: Convert grams to troy ounces by dividing by 31.1034768, then multiply by rates.USDXAU. Example: usd = (grams ÷ 31.1034768) × USDXAU.

Q: How should I handle weekends or market closures?
A: latest may return the last available price until a new tick is published. Display the timestamp to users. For backfills and analytics, pull historical or time-series data aligned to business days (see Documentation).

Q: Can I cache results to reduce requests?
A: Yes. Cache by timestamp and symbols requested. Update only when you observe a newer timestamp. Share the cache across services to avoid redundant calls.

Q: Where do I find all valid symbols for gold-related workflows?
A: Check the definitive list in Symbols. This article focuses on XAU.

Ready to implement the XAU Convert API and ship pricing, conversion, and P&L features? Get your API key now: Register. For configuration and permissions, visit MCP, and keep the Documentation handy as you integrate. Learn more about the service at metals-api.com.