Get Platinum Ask (XPT-ASK) Price Data through this API

Gold historical prices power real-world decisions: backfilling long-range XAU charts in a trading terminal, running volatility studies for a quant model, benchmarking jewelry margins by carat, or auditing ERP purchase orders against the reference close. This guide shows how to fetch reliable Gold (XAU) historical data with Metals-API, interpret the responses, design a resilient integration, and turn that data into actionable analytics. We’ll cover practical concerns developers care about, like timestamps, units (troy ounces vs grams), base currency, weekend/holiday handling, caching strategies, and security. You’ll also see realistic JSON examples and an end-to-end request flow to operationalize XAU history in your stack.

What “historical XAU prices” actually mean in an API integration

When you request historical Gold (XAU) prices, you’re typically after one or more of the following:

Daily close values for charting and returns calculations
OHLC (open, high, low, close) for a specific session/date
Daily time series between two dates to compute signals or backtests
Fluctuation summaries across a range (net change and percentage)
Precise conversion from a historical USD value into troy ounces of gold (or vice versa)

Metals-API provides endpoints for each of these scenarios. You can pull a single historical date, a date range, OHLC fields, or even summarize fluctuations over a window. All responses clearly state the base currency, the unit, and a timestamp so your downstream code can normalize, cache, and analyze consistently.

Quick links, docs, and how to get started fast

Explore all parameters, examples, and response schemas: Metals-API Documentation
Verify symbols for Gold and other instruments: Metals-API Supported Symbols
Create a free key and try your first request: Metals-API Website

Core concepts you need before fetching XAU history

Base currency and units

By default, Metals-API returns exchange rates relative to USD, and units are per troy ounce. This matters because:

Base currency USD means values are “XAU per 1 USD” unless you change the base.
Unit per troy ounce means you must convert to grams or kilograms if your downstream logic expects metric units (1 troy ounce = 31.1034768 grams).

Timestamps and timezone

Responses include a Unix timestamp (seconds since epoch). Store and transport this timestamp instead of parsing human-readable dates wherever possible to avoid timezone drift.
Date fields (YYYY-MM-DD) represent the session date. For backfills, prefer the date string to address daylight saving considerations while retaining the epoch in metadata for precise ordering.

Weekend and market closures

Commodities and precious metals have non-trading days (weekends, holidays). If a requested date falls on a closure, the historical endpoint will return the latest known value as of that date’s context. Design your ETL to either accept the carried-forward value or skip non-trading days, depending on your analytics rules.

Caching to save requests and cost

Historical prices don’t change. Cache them indefinitely by date and symbol.
For “latest” or intraday polling, respect freshness intervals per your plan and implement server-side caching to avoid duplicate calls under load.

End-to-end: Fetch a single historical Gold (XAU) price

Let’s pull a single day’s value for XAU using the Historical Rates capability. You’ll specify the date, your API key, the base currency, and the target symbol list. While the examples below use USD and XAU, you can change base and symbols as needed.

Example curl request: one historical XAU day

curl "https://metals-api.com/api/2026-09-14?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU"

Representative JSON response and field usage

{
"success": true,
"timestamp": 1789346959,
"base": "USD",
"date": "2026-09-14",
"rates": {
"XAU": 0.000485,
"XAG": 0.03825,
"XPT": 0.000915,
"XPD": 0.000748
},
"unit": "per troy ounce"
}

How to read this for Gold:

success: Boolean indicator of request success. Always check before consuming rates.
timestamp: Unix epoch seconds for when these rates were recorded/resolved. Persist this.
base: “USD” means values express metal units per 1 USD. For example, XAU = 0.000485 oz per USD.
date: Historical date requested or resolved for the dataset. Use as the session key in your database.
rates.XAU: The exchange rate for gold in troy ounces per USD. To compute USD per ounce, invert: 1 / 0.000485 ≈ 2061.86 USD/oz.
unit: “per troy ounce”. Normalize or convert for downstream consistency.

JavaScript example: parsing and normalizing XAU

// Fetch a single historical XAU rate and compute USD per ounce.
fetch("https://metals-api.com/api/2026-09-14?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU")
.then(r => r.json())
.then(data => {
if (!data.success) throw new Error("API request failed");
const xauPerUsd = data.rates.XAU; // troy ounces per 1 USD
const usdPerOz = 1 / xauPerUsd;
const gramsPerOz = 31.1034768;
const usdPerGram = usdPerOz / gramsPerOz;

console.log({
date: data.date,
usdPerOz: Number(usdPerOz.toFixed(2)),
usdPerGram: Number(usdPerGram.toFixed(4)),
timestamp: data.timestamp
});
})
.catch(console.error);

Building a complete historical time series for XAU

Backtests, factor models, and chart UIs often require a continuous series. The Time-series capability returns daily values between two dates. Your job is to persist, gap-check, and normalize.

Example request: daily range for XAU

curl "https://metals-api.com/api/timeseries?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU&start_date=2026-09-08&end_date=2026-09-15"

Representative JSON response with multiple days

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

Key implementation notes:

rates is a map of date → symbol → value. Iterate deterministically, sort by date key, and upsert into your time-series table keyed on (symbol, date).
Missing days can result from weekends/holidays. Decide whether to forward-fill values for analytics or leave gaps for exchange-true behavior.
Convert XAU-per-USD to USD-per-oz at ingest if that’s your canonical representation. Store both if you do bi-directional conversions often.

Summarize XAU moves over a period with fluctuations

For alerting, reports, or dashboards, the Fluctuation feature returns start and end rates along with absolute and percentage changes. This lets you trigger notifications and annotate charts without fetching and computing deltas yourself.

Example fluctuation request

curl "https://metals-api.com/api/fluctuation?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU&start_date=2026-09-08&end_date=2026-09-15"

Representative fluctuation JSON

{
"success": true,
"fluctuation": true,
"start_date": "2026-09-08",
"end_date": "2026-09-15",
"base": "USD",
"rates": {
"XAU": {
"start_rate": 0.000485,
"end_rate": 0.000482,
"change": -3.0e-6,
"change_pct": -0.62
},
"XAG": {
"start_rate": 0.03825,
"end_rate": 0.03815,
"change": -0.0001,
"change_pct": -0.26
},
"XPT": {
"start_rate": 0.000915,
"end_rate": 0.000912,
"change": -3.0e-6,
"change_pct": -0.33
}
},
"unit": "per troy ounce"
}

For Gold use cases, you’ll primarily consume rates.XAU.start_rate, end_rate, change, and change_pct to power:

Daily/weekly email digests
Price movement badges in dashboards
Risk monitoring (threshold-based alerts)

OHLC for gold: precise session analytics

When your research requires more granularity than a single close, the OHLC feature provides Open/High/Low/Close for a date. This is useful for candlestick charts, intraday strategy validation, or volatility bucketing.

Example OHLC request

curl "https://metals-api.com/api/ohlc/2026-09-15?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU"

Representative OHLC JSON

{
"success": true,
"timestamp": 1789433359,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": {
"open": 0.000485,
"high": 0.000487,
"low": 0.000481,
"close": 0.000482
},
"XAG": {
"open": 0.03825,
"high": 0.0383,
"low": 0.0381,
"close": 0.03815
},
"XPT": {
"open": 0.000915,
"high": 0.000918,
"low": 0.00091,
"close": 0.000912
}
},
"unit": "per troy ounce"
}

For Gold analytics:

Use rates.XAU.open/high/low/close to construct candles.
Compute intraday ranges: (high - low) and their ratios to close for volatility features.
Normalize to USD-per-oz if your charting system expects price rather than ounces-per-USD.

Cross-checking and validation with bid/ask context

Even when doing historical work, you may want to corroborate the latest bid/ask context to understand current spreads or to calibrate transaction cost assumptions in your models.

Example bid/ask request

curl "https://metals-api.com/api/bid-ask?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU"

Representative bid/ask JSON

{
"success": true,
"timestamp": 1789433359,
"base": "USD",
"date": "2026-09-15",
"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"
}

How to use this with historical XAU:

Estimate slippage and effective spread for backtest PnL assumptions.
Compare end-of-day historical closes to intraday bid/ask levels to detect anomalies in your pipeline.

Converting historical USD amounts into gold weight (and back)

The Convert capability is handy if you need to express a historical USD amount in troy ounces of gold, e.g., “How many ounces would $10,000 buy on 2026-09-14?” Likewise, you can convert ounces to USD for historical valuations.

Example conversion request

curl "https://metals-api.com/api/convert?access_key=YOUR_ACCESS_KEY&from=USD&to=XAU&amount=10000"

Representative conversion JSON

{
"success": true,
"query": {
"from": "USD",
"to": "XAU",
"amount": 1000
},
"info": {
"timestamp": 1789433359,
"rate": 0.000482
},
"result": 0.482,
"unit": "troy ounces"
}

Notes for historical accuracy:

Use the historical date’s rate if you need a date-specific conversion. If your plan supports it, include the date parameter where applicable or fetch the historical rate first and apply the amount conversion offline using the returned rate.
The result unit is troy ounces. Convert to grams if necessary.

Validating symbols and planning your instrument coverage

Before shipping to production, confirm symbols for Gold and related metals you might benchmark against. Use the symbols directory to ensure your code only requests supported instruments and to discover complementary metals or currencies.

Reference: Metals-API Supported Symbols

Integrating historical XAU into trading, fintech, and ERP workflows

Trading research and quant analytics

Backfill daily XAU closes via the Time-series capability and compute rolling returns, Sharpe ratios, and drawdowns.
Use OHLC to design breakout or mean-reversion strategies with intraday ranges approximated from session High/Low.
Calibrate slippage using current Bid/Ask spreads, and stress test PnL against spread widening scenarios.

Fintech product pricing

Price gold-linked savings or rewards products by periodically updating the reference XAU price. Use caching and a polling cadence aligned with your plan’s refresh interval.
For historical statements, fetch the exact historical date’s rate to avoid retroactive changes.

Jewelry and manufacturing ERP

Audit historical purchase orders: Pull the historical daily rate for the PO date; convert to grams and compare to vendor invoices.
Benchmark BOM costs: For a gold component, compute the USD-per-gram cost on a specific date from the XAU rate.

Practical handling of units: troy ounces, grams, and carats

Gold is quoted in troy ounces. 1 troy ounce = 31.1034768 grams.
For jewelry, if you work with carats (for gemstones) or karats (for gold purity), be explicit in your code and UI. The Carat capability in Metals-API is specifically for gold by carat. Ensure you understand input bases and outputs before integrating purity-based pricing.
Always store a canonical unit internally (e.g., USD-per-gram) and convert for UI. This reduces rounding errors across systems.

Designing a robust ingestion pipeline for XAU history

Suggested architecture

Ingestion service: Fetches historical and timeseries data in batches, normalizes units, and writes to a time-series database.
Caching layer: Immutable cache for historical results keyed by (symbol, date). TTL = infinite.
Normalization module: Inverts ounces-per-USD to USD-per-ounce when needed; computes USD-per-gram; handles currency conversions if you set a different base.
Validation: Schema-validate every API response; check for success=true; verify date coverage and monotonic timestamps; alert on anomalies.
Analytics service: Consumes normalized data to compute indicators, fluctuations, and risk metrics.
API proxy: Secure your Metals-API key behind a server-side proxy to prevent client-side exposure.

Database schema tips

Primary key: (symbol, date). Secondary index on date for range scans.
Fields: xau_per_usd (float), usd_per_oz (float), usd_per_gram (float), timestamp (int), unit (string), base (string).
For OHLC: open, high, low, close fields, plus the inverted USD values if that’s your canonical price.

Performance and cost optimization

Batch requests by date range using Time-series instead of calling individual dates.
Cache all historical responses. They won’t change; store raw JSON for quick replays and auditing.
Deduplicate concurrent calls by symbol/date using request coalescing in your client or proxy layer.
Downsample for UI charts if you don’t need daily granularity everywhere; store full history, serve curated aggregates.

Error handling and recovery

Always check success in the response. If false, do not consume rates.
Implement exponential backoff with jitter for transient network issues.
On partial data (e.g., missing a single day in a range), log and retry the specific gap later. Don’t block the entire batch if you can proceed.
Persist last-good snapshot so analytics can operate in degraded mode if the upstream is temporarily unreachable.

Security best practices

Never embed your Metals-API key in client-side code. Use a server-side proxy or backend service.
Restrict egress on your infra to only allow outbound requests to Metals-API domains.
Rotate keys periodically; monitor for unusual request patterns.

Quality assurance: validating data properties

Monotonic checks: While prices don’t have to be monotonic, your timestamps and date ordering should be. Log any inversions.
Unit sanity: Confirm unit equals “per troy ounce” when expecting metal rates; raise an alert if the unit changes.
Inversion correctness: Test your usd_per_oz = 1 / xau_per_usd math across boundary conditions and rounding policies.

Covering the full lifecycle: latest to historical continuity

Many teams start with the Latest capability for a live panel and then periodically cut over to a fixed historical record at end-of-day. To maintain continuity:

Use Latest for intraday; store snapshots with timestamp.
At end-of-day, pull the Historical rate for the date and mark it as the official close.
If you collect OHLC, reconcile your intraday highs/lows with the session high/low and flag discrepancies for review.

Realistic end-to-end workflow for a historical XAU backfill

Determine your coverage window (e.g., from product inception date to current day).
Call Time-series with start_date and end_date for XAU, base=USD.
Persist rates date-by-date, computing usd_per_oz and usd_per_gram at ingest.
For specific analytics (e.g., candlesticks), call OHLC by date and upsert open/high/low/close fields.
Compute fluctuations for report windows (weekly, monthly) using the Fluctuation feature or your local deltas.
Expose the normalized dataset to charts, factor models, and ERP reports.

Examples you can reuse in your tests

Latest snapshot for XAU

{
"success": true,
"timestamp": 1789433359,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": 0.000482,
"XAG": 0.03815,
"XPT": 0.000912,
"XPD": 0.000744,
"XCU": 0.294118,
"XAL": 0.434783,
"XNI": 0.142857,
"XZN": 0.344828
},
"unit": "per troy ounce"
}

Usage: Read rates.XAU and invert to produce USD-per-oz for real-time display. Persist timestamp for ordering.

Historical daily for a specific date

{
"success": true,
"timestamp": 1789346959,
"base": "USD",
"date": "2026-09-14",
"rates": {
"XAU": 0.000485,
"XAG": 0.03825,
"XPT": 0.000915,
"XPD": 0.000748
},
"unit": "per troy ounce"
}

Usage: Store under (XAU, 2026-09-14). Compute usd_per_oz = 1 / 0.000485.

Time-series across multiple sessions

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

Usage: Iterate rates’ keys in chronological order, merge into your timeseries table.

Fluctuation summary for reporting

{
"success": true,
"fluctuation": true,
"start_date": "2026-09-08",
"end_date": "2026-09-15",
"base": "USD",
"rates": {
"XAU": {
"start_rate": 0.000485,
"end_rate": 0.000482,
"change": -3.0e-6,
"change_pct": -0.62
}
},
"unit": "per troy ounce"
}

Usage: Directly populate KPI widgets or roll-up reports without extra calculations.

Common pitfalls and how to avoid them

Confusing base direction: Remember values are ounces-per-USD by default. Invert to get USD-per-oz.
Mixing units: If another system expects grams, convert once and store canonical USD-per-gram to prevent inconsistent rounding.
Skipping success flag: Always check success; on false, treat as an error and retry later.
Assuming continuous dates: Trading calendars have gaps. Your code should tolerate missing weekend dates and optionally forward-fill only where appropriate.
No caching: Historical data should be cached indefinitely to minimize cost and latency.

Advanced techniques for time-series analysis

Volatility estimation: Use OHLC to compute Parkinson or Garman-Klass volatility estimates rather than relying on close-to-close only.
Regime detection: Pull multi-year Time-series and segment with rolling Z-scores, drawdowns, or HMMs for strategy gating.
Cross-asset signals: Combine XAU with related metals (XAG, XPT) and currency crosses to build relative value spreads.
Event studies: Align historical XAU prices to macro events; compute abnormal returns using a baseline from Time-series data.

Testing and monitoring in production

Contract tests: Validate response structure against documented schemas from the Metals-API Documentation.
Freshness checks: Monitor that your ingestion service writes new dates on schedule; alert if staleness exceeds SLOs.
Numerical drift: Track the distribution of usd_per_oz; flag improbable jumps to catch upstream or local conversion bugs.

Discoverability and symbol management

As your product grows, you may add platinum (XPT), silver (XAG), or industrial metals for hedging or correlation studies. Keep a scheduled job that refreshes the symbol catalog from the directory so your UI and validation rules stay in sync. Start with the catalog here: Metals-API Supported Symbols.

When to use intraday vs daily

Intraday: Live panels, real-time alerts, and tick-like responsiveness. Cache aggressively within your plan’s update interval.
Daily (Historical/Time-series): Backtesting, portfolio statements, ERP auditing, and reports that need stable, reproducible values.

Data governance and auditing

Immutable storage: Keep raw JSON for each date alongside normalized fields. This makes audits and reprocessing trivial.
Provenance: Store the timestamp, unit, base, and your request parameters with every record.
Reconciliation workflows: Periodically re-fetch random historical dates and diff against your stored values to detect drift or corruption.

Linking out to research context and market references

API home and key creation: Metals-API Website — get your free API key and start testing.
Full feature details and usage patterns: Metals-API Documentation.
Symbol coverage confirmation: Metals-API Supported Symbols.
Reference reading on gold market conventions: LBMA (London Bullion Market Association).

Putting it all together: a blueprint for XAU historicals

Here’s a concise implementation plan:

Get an API key at the Metals-API Website.
Validate XAU availability in the symbol directory.
Backfill with Time-series for your desired date range; persist raw and normalized data.
Add OHLC pulls for dates where you need intraday ranges.
Generate period summaries with Fluctuation for alerts/dashboards.
Secure your integration, implement caching, and monitor freshness and outliers.

Conclusion

Historical Gold (XAU) data is foundational for trading analytics, fintech product pricing, and manufacturing cost controls. Metals-API gives you the primitives you need—single-date historical values, time-series ranges, OHLC breakdowns, and fluctuation summaries—along with consistent timestamps, explicit units, and a clear base currency. By caching immutable history, normalizing units early, and validating responses, you’ll build a robust data backbone for charts, risk models, and operational reporting.

Ready to implement? Explore the Metals-API Documentation, verify supported symbols, and get your key at the Metals-API Website to start pulling XAU history today.

FAQ

What unit does Metals-API use for Gold?
Per troy ounce by default. Convert to grams using 1 oz = 31.1034768 g if needed.
What does base=USD imply?
Rates are ounces-per-USD. Invert to get USD-per-ounce.
How do I handle weekends and holidays?
Expect gaps in the date map. Forward-fill only if your analytics rules require it, or skip non-trading days.
Can I get OHLC for historical sessions?
Yes. Use the OHLC capability with a date to retrieve open, high, low, close for XAU.
How can I reduce API usage?
Cache historical responses indefinitely and coalesce concurrent requests. Use time-series for batches instead of single-date loops.
Is there a way to summarize changes over time quickly?
Yes. Use the Fluctuation capability to get start_rate, end_rate, absolute change, and percentage change.
Where do I find all symbols?
See the directory here: Metals-API Supported Symbols.
How do I keep my API key secure?
Call Metals-API from your backend or a secure proxy, never from client-side code. Rotate keys periodically.

Ready to use Metals-API?

Try it now!