Gold and Silver Price API for Bullion Dealers

Metals-API 9 min read
Gold and Silver Price API for Bullion Dealers

Bullion dealers must quote live buy/sell prices for gold and silver, update ecommerce product pages in real time, and reconcile with historical spot moves when hedging. By the end of this walkthrough, you’ll fetch current XAU/XAG prices, compute USD per troy ounce and per gram for quoting, and backfill charts from a date range—using two Metals-API endpoints you can integrate directly into a pricing engine or storefront.

What bullion dealers actually need from a price API

Day-to-day operations hinge on two types of data:

Illustration: Gold and Silver Price API for Bullion Dealers
  • Real-time spot prices for gold (XAU) and silver (XAG) to power quotes, ecommerce SKUs, and buyback offers.
  • Recent history to calculate moves, drive charting, and set margin controls or automated hedges.

We’ll focus on two endpoints that map to these needs: 1) Latest Rates for current spot, and 2) Time-series for daily closes across a range. If you also quote two-way prices, we’ll briefly show Bid/Ask as an advanced add-on.

For symbol reference and metadata, see the up-to-date catalog at Metals-API Supported Symbols. For endpoint details, parameters, and response shapes, use the Metals-API Documentation.

Units, base currency, and how to read the rates

Metals-API returns exchange rates relative to a base (default USD) with unit “per troy ounce.” Practically, that means rates.XAU is ounces of gold per 1 USD (oz/USD). To get the more familiar “USD per ounce,” invert the number: USD/oz = 1 / rates.XAU. Some responses also include USDXAU, which is already USD per 1 XAU (1 troy ounce).

  • 1 troy ounce = 31.1034768 grams. Convert per-ounce pricing to per-gram by dividing by 31.1034768.
  • Timestamps are Unix seconds, and dates are provided in UTC in the response.
  • Silver follows the same logic: rates.XAG is oz/USD; invert to get USD per oz.

Endpoint 1: Latest gold and silver spot for live quoting

Use the Latest Rates endpoint to power your live price tiles, ecommerce product prices, or intake quotes at the counter. For gold and silver dealers, you’ll commonly derive these values:

  • USD per oz (XAU, XAG) for retail list prices and comparisons.
  • USD per gram for jewelry and scrap operations.
  • Buy and sell prices by applying your premium/discount to spot.

Example request (curl)

The following request fetches the latest rates. Replace YOUR_API_KEY with your key after you Register.

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

Official sample response

{"success":true,"timestamp":1795039680,"date":"2026-11-18","base":"USD","rates":{"XAU":0.00026852125345721,"USD":1,"USDXAU":3724.100000000016}}

How to use these fields

  • success: Request status.
  • timestamp/date: When the rates were captured (Unix seconds and UTC date).
  • base: USD indicates rates are quoted relative to USD.
  • rates.XAU: Ounces of gold per 1 USD (oz/USD). Invert to get USD per ounce if USDXAU is not present.
  • rates.USDXAU: USD per 1 XAU (1 troy ounce). This is the direct USD/oz price; prefer this field when present.

Turn spot into dealer prices (JavaScript)

This example consumes the Latest Rates endpoint, computes USD/oz for XAU, and demonstrates how you would handle XAG if included in your plan response. It also calculates per-gram and applies simple premiums for quoting.

import https from "node:https";

function fetchJSON(url) {
  return new Promise((resolve, reject) => {
    https.get(url, (res) => {
      let data = "";
      res.on("data", (chunk) => (data += chunk));
      res.on("end", () => {
        try { resolve(JSON.parse(data)); } catch (e) { reject(e); }
      });
    }).on("error", reject);
  });
}

(async () => {
  const apiKey = process.env.METALS_API_KEY || "YOUR_API_KEY";
  const url = `https://metals-api.com/api/latest?access_key=${apiKey}`;
  const json = await fetchJSON(url);

  if (!json.success) {
    throw new Error("Metals-API error: " + JSON.stringify(json));
  }

  // USD per ounce for Gold (prefer direct USDXAU if available; otherwise invert rates.XAU).
  const usdPerOzXAU = json.rates.USDXAU
    ? json.rates.USDXAU
    : (1 / json.rates.XAU);

  // If your response includes XAG, derive USD per oz similarly:
  const hasXAG = json.rates.XAG !== undefined;
  const usdPerOzXAG = hasXAG ? (1 / json.rates.XAG) : null;

  // Convert to USD per gram
  const TROY_OZ_TO_G = 31.1034768;
  const usdPerGramXAU = usdPerOzXAU / TROY_OZ_TO_G;
  const usdPerGramXAG = usdPerOzXAG ? (usdPerOzXAG / TROY_OZ_TO_G) : null;

  // Apply simple dealer premium/discount (example: +3% sell, -1.5% buy)
  const sellPremium = 0.03;
  const buyDiscount = 0.015;

  const goldSellPerOz = usdPerOzXAU * (1 + sellPremium);
  const goldBuyPerOz  = usdPerOzXAU * (1 - buyDiscount);

  const silverSellPerOz = usdPerOzXAG ? (usdPerOzXAG * (1 + sellPremium)) : null;
  const silverBuyPerOz  = usdPerOzXAG ? (usdPerOzXAG * (1 - buyDiscount)) : null;

  console.log({
    date: json.date,
    timestamp: json.timestamp,
    gold: {
      usd_per_oz: usdPerOzXAU,
      usd_per_gram: usdPerGramXAU,
      dealer_sell_per_oz: goldSellPerOz,
      dealer_buy_per_oz: goldBuyPerOz
    },
    silver: hasXAG ? {
      usd_per_oz: usdPerOzXAG,
      usd_per_gram: usdPerGramXAG,
      dealer_sell_per_oz: silverSellPerOz,
      dealer_buy_per_oz: silverBuyPerOz
    } : "XAG not present in this sample response"
  });
})();

Tip: Cache the latest response briefly (e.g., 15–60 seconds) in your application layer to reduce duplicate calls during high-traffic bursts on ecommerce carts while keeping quotes responsive. For plan-specific refresh intervals and features, review the Documentation.

Endpoint 2: Time-series for charts, P&L, and premium calibration

Dealers often adjust retail premiums and buyback discounts based on recent volatility. The Time-series endpoint returns daily rates between a start and end date, so you can calculate percent changes, average costs, and generate customer-facing charts.

Sample time-series response (XAU and XAG)


{
    "success": true,
    "timeseries": true,
    "start_date": "2026-11-11",
    "end_date": "2026-11-18",
    "base": "USD",
    "rates": {
        "2026-11-11": {
            "XAU": 0.000485,
            "XAG": 0.03825,
            "XPT": 0.000915
        },
        "2026-11-13": {
            "XAU": 0.000483,
            "XAG": 0.0382,
            "XPT": 0.000913
        },
        "2026-11-18": {
            "XAU": 0.000482,
            "XAG": 0.03815,
            "XPT": 0.000912
        }
    },
    "unit": "per troy ounce"
}

Interpretation is identical to Latest: values are oz/USD. For USD/oz chart points, invert the daily rate. For example, USD/oz gold on 2026-11-18 ≈ 1 / 0.000482.

  • Compute daily returns: return_t = (USD/oz_t) / (USD/oz_{t-1}) - 1
  • Calibrate premiums: increase when realized volatility exceeds your threshold; decrease when calm.

For request parameters and date limits, use the Documentation.

Optional: Two-way quotes with Bid/Ask

If your plan includes bid/ask, you can quote tighter spreads at the counter and display two-way prices online. This helps align customer-facing quotes with your hedging desk.


{
    "success": true,
    "timestamp": 1795039737,
    "base": "USD",
    "date": "2026-11-18",
    "rates": {
        "XAU": {
            "bid": 0.000481,
            "ask": 0.000483,
            "spread": 2.0e-6
        },
        "XAG": {
            "bid": 0.0381,
            "ask": 0.0382,
            "spread": 0.0001
        },
        "XPT": {
            "bid": 0.000911,
            "ask": 0.000913,
            "spread": 2.0e-6
        }
    },
    "unit": "per troy ounce"
}

These quotes are also in oz/USD. Invert each to get USD/oz bid and ask, then apply your store margin to display final buy/sell prices.

Digital transformation for XAU/XAG: connecting pricing to operations

Gold (XAU) sits at the center of digitizing precious metals workflows. With standardized JSON pricing and consistent timestamps, Metals-API reduces integration friction across:

  • POS systems: compute customer buyback and sell quotes in real time.
  • Ecommerce: dynamically price bullion SKUs (1 oz, 10 oz, 100 oz) and coins with product-specific premiums.
  • ERP: back-calculate COGS and mark-to-market values for inventory and P&L.
  • Analytics: detect volatility regimes and adjust premiums or hedging rules for gold and silver.

For market coverage and methodology references, see Metals-API MCP. For external benchmarks and education, dealers often refer to LBMA prices and data and CME Group metals markets alongside their live spot feeds.

Practical integration details that save time

  • Base currency: Responses default to USD. Rates are relative to base (oz/USD). If USDXAU is present, it already reflects USD per ounce—use it directly for display and calculations.
  • Units: Unit is “per troy ounce.” Convert to grams with 31.1034768. For kilo bars, multiply USD/oz by 32.1507466; for tolas, multiply by ~0.375 troy oz.
  • Timestamps and timezone: timestamp is Unix seconds; date is UTC. Store both to align with hedging fills and OMS logs.
  • Weekends/closures: Metals can show reduced activity over weekends and holidays. When building charts, handle gaps by forward-filling or labeling non-trading days appropriately.
  • Caching: Cache Latest responses briefly to cap API calls during peak traffic. For storefront category pages, hydrate with cached prices; for checkout, refresh once per session or just-in-time.
  • Error handling: On partial data (e.g., XAU present, XAG absent), display available quotes and retry the missing symbol on a backoff schedule.
  • Premium logic: Keep premium tiers per product (bar vs coin), quantity breaks, and payment method (ACH vs card) in your own config; multiply tiered premiums by USD/oz or USD/gram from the API.
  • Audit trail: Persist the raw JSON and computed USD/oz/gram alongside price changes for compliance and reconciliation.

Symbol quick reference for bullion storefronts

Symbol Metal What the API’s rate means How to get USD per ounce Common retail units
XAU Gold Ounces per USD (oz/USD) Invert: 1 / XAU or use USDXAU if present 1 oz, 10 oz, 1 kg; per gram for jewelry
XAG Silver Ounces per USD (oz/USD) Invert: 1 / XAG 1 oz, 10 oz, 100 oz bars; per gram for scrap

From raw feed to customer-ready prices: a minimal workflow

  1. Call Latest Rates and compute USD/oz and USD/gram for XAU and XAG.
  2. Apply product-specific premiums/discounts to derive sell and buy prices.
  3. Cache and publish prices to ecommerce, POS, and quotes API.
  4. Use Time-series daily rates to track volatility and adjust premiums.
  5. Optionally, incorporate Bid/Ask for tighter, two-way quotes.

Security and reliability tips

  • Store your API key server-side; don’t embed in client JavaScript.
  • Implement retries with exponential backoff and a circuit breaker around your price fetcher.
  • Validate fields: ensure base is USD and unit is per troy ounce before computing downstream values.
  • Monitor for stale data: compare new timestamp to your last-seen; if unchanged past your tolerance, alert or switch to secondary display logic.

What this unlocks for bullion dealers

By programmatically transforming XAU/XAG spot into USD per ounce and per gram with audited timestamps, you can automate price discovery, publish transparent quotes across web and store, and drive analytics that calibrate premiums to actual volatility—streamlining the full loop from customer pricing to inventory and hedging. For endpoint coverage and parameters, keep the Documentation open while you wire up the integration.

FAQ

How do I get USD per ounce from the API if I only see XAU?
If the response includes USDXAU, use that directly. Otherwise, USD/oz = 1 / rates.XAU because rates.XAU is ounces per USD.

How should I handle silver (XAG) if it isn’t present in my latest response?
Build your code to detect missing symbols and retry on a short backoff. Continue serving gold prices while you refresh silver, and log the event for reconciliation.

What’s the recommended cadence for refreshing live storefront prices?
Most dealers update tiles every 30–60 seconds and refresh at checkout time. Cache results to minimize bursts; use the timestamp in the payload to display “last updated” to users.

How do I show per-gram prices for jewelry or scrap?
Compute USD/gram by dividing USD/oz by 31.1034768. Keep separate premiums for bullion products vs. jewelry and scrap to reflect different operational costs.

Can I use the time-series endpoint to backfill charts?
Yes. Fetch the date range you need and invert each oz/USD rate to USD/oz for chart points. Handle weekends/holidays by forward-filling or indicating non-trading days.

Ready to wire XAU and XAG into your quoting engine and storefront? Get an API key and start integrating today: Register.