Get DB Gold Double Short ETN (DZZ) - Per Ounce Historical Prices using this API for a specific date range

Building a quant backtest, risk model, or signal for DB Gold Double Short ETN (DZZ) almost always starts with high-quality gold per-ounce history. DZZ is a -2x leveraged note on daily gold moves, so the underlying driver is spot gold (XAU) in USD per troy ounce. This article shows exactly how to fetch per-ounce historical prices for gold over any date range using Metals-API and then apply them to DZZ analysis—whether you’re calibrating a -2x gold strategy, validating NAV tracking, constructing factor exposures, or powering a research dashboard.

Why DZZ analysis begins with XAU per troy ounce

DZZ seeks to reflect -2x of the daily performance of gold. While the ETN’s indicative value incorporates fees, compounding, and market mechanics, the core dependency is clean, reliable gold pricing. Metals-API gives you normalized, consistent, per troy ounce XAU/USD history and OHLC bars suitable for computing daily moves, comp returns, and volatility that you can map into any DZZ model. The result: your backtests are driven by the underlying signal rather than noisy proxies.

What you will build in this guide

• Download per-ounce gold history (XAU) for a specific date range via the Time-Series and Historical endpoints.
• Interpret Metals-API response fields (base, rates, timestamps, unit) to compute USD-per-ounce values consistently.
• Use OHLC data to model daily -2x moves and analyze compounding effects relevant to DZZ.
• Handle weekends/holidays, caching, timestamps, and performance at scale.
• Integrate the data into your DZZ analytics pipeline in a secure, production-grade way.

Before you start, review the current symbol list on the Metals-API Supported Symbols page. For DZZ analysis, you will use XAU. If you need documentation detail beyond the scope of this article, head to the Metals-API Documentation. To get started right away, visit the Metals-API Website and get your free API key.

Key endpoints to retrieve per-ounce XAU price history

This walkthrough focuses on three endpoints that are most useful for DZZ-oriented workflows:

• Time-Series: Retrieve daily XAU history across a date range.
• Historical: Fetch a single day’s XAU price (useful for fill, verification, or sparse sampling).
• OHLC: Pull per-day open/high/low/close values for XAU to reconstruct daily -2x path dependence.

We will not list every feature or endpoint here. For broader capabilities, see the Metals-API Documentation and supported symbols reference.

Understanding Metals-API pricing conventions (must-know for DZZ)

• Base currency: The API returns exchange rates relative to USD by default (base = "USD").
• Rates meaning: rates.XAU is quoted as ounces per USD (oz/USD). To get USD per ounce, compute price = 1 / rates.XAU.
• Unit: Metals-API quotes “per troy ounce” by default for precious metals. One troy ounce equals approximately 31.1034768 grams, not the same as an avoirdupois ounce.
• Timestamps/timezone: Timestamps are UNIX epoch seconds; dates are in YYYY-MM-DD. Treat them as UTC-aligned trading days for your downstream normalization.
• Market closures: Weekends/holidays may not have updates; the time-series endpoint returns business days with data points. In your backtest, forward-fill or skip non-trading days consistently.

Requesting a gold time series for a specific date range

Use the Time-Series endpoint to pull a contiguous block of daily per-ounce gold data. This is the starting point for any strategy that maps XAU moves into DZZ’s -2x profile.

Example: curl request for a one-week window

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

Example JSON response (truncated to XAU)

{
"success": true,
"timeseries": true,
"start_date": "2026-09-15",
"end_date": "2026-09-22",
"base": "USD",
"rates": {
"2026-09-15": {
"XAU": 0.000485
},
"2026-09-17": {
"XAU": 0.000483
},
"2026-09-22": {
"XAU": 0.000482
}
},
"unit": "per troy ounce"
}

Interpreting the time-series response

• success: Boolean indicating the call worked. Guard on this before parsing.
• timeseries: Confirms it is a time-series result set.
• start_date/end_date: Echoed parameters for validation/auditing.
• base: "USD" indicates each rate is denominated with USD as the base.
• rates.{date}.XAU: ounces per USD for the date. To get USD/oz, calculate 1 / XAU.
• unit: per troy ounce, confirming the unit context for XAU.

From XAU rate to USD per ounce

• Given XAU = 0.000482 oz/USD, USD per ounce = 1 / 0.000482 ≈ 2074.27 USD/oz.
• This inversion is critical when computing daily percentage returns for mapping to DZZ’s -2x daily objective.

JavaScript example: fetch XAU and compute USD/oz series

async function fetchGoldSeries(startDate, endDate, apiKey) {
const url = `https://metals-api.com/api/timeseries?access_key=${apiKey}&start_date=${startDate}&end_date=${endDate}&base=USD&symbols=XAU`;
const res = await fetch(url, { method: "GET" });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const json = await res.json();
if (!json.success) throw new Error("API returned success=false");

const usdPerOz = [];
for (const [date, obj] of Object.entries(json.rates)) {
const xauRate = obj.XAU; // ounces per USD
const priceUsdPerOz = 1 / xauRate; // USD per ounce
usdPerOz.push({ date, price: priceUsdPerOz });
}
// Sort by date ascending in case of unordered keys
usdPerOz.sort((a, b) => (a.date < b.date ? -1 : 1));
return { unit: json.unit, base: json.base, data: usdPerOz };
}

Tip: cache responses keyed by (start_date, end_date, symbols) to reduce duplicate requests. When backfilling long ranges, break into monthly/quarterly chunks and parallelize carefully while respecting your plan’s concurrency and request limits.

Single-day historical lookups (validation, sparse pulls, or patching)

If you need to verify a particular date, fill in a missing point, or drive a UI that loads one day at a time, use the Historical endpoint by appending a YYYY-MM-DD date to the path.

Example: curl for a specific date

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

Example JSON response

{
"success": true,
"timestamp": 1789949526,
"base": "USD",
"date": "2026-09-21",
"rates": {
"XAU": 0.000485
},
"unit": "per troy ounce"
}

Field breakdown you will actually use

• date: The pricing date for the rate.
• rates.XAU: ounces per USD for that date.
• timestamp: Epoch seconds; aligns with data availability timing. For end-of-day logic, use the date key for business-day grouping.
• unit: “per troy ounce,” confirming unit conversion assumptions.

Daily OHLC for gold and why it matters for DZZ

DZZ targets daily -2x of gold’s performance. Modeling this correctly often requires daily opens and closes to replicate the compounding path. The OHLC endpoint returns open, high, low, and close for XAU per date, which helps validate return computations and stress-test intraday extremes if your risk model considers ranges.

Example: OHLC request concept

Query the OHLC endpoint for a specific date window. If your plan supports it, request XAU bars for each date you need. Refer to the documentation for exact usage and availability per plan.

Example JSON response (XAU OHLC)

{
"success": true,
"timestamp": 1790035926,
"base": "USD",
"date": "2026-09-22",
"rates": {
"XAU": {
"open": 0.000485,
"high": 0.000487,
"low": 0.000481,
"close": 0.000482
}
},
"unit": "per troy ounce"
}

Using OHLC fields

• Convert each open/high/low/close to USD/oz by inversion (1/rate).
• Daily return for DZZ modeling: compute from close-to-close on the USD/oz prices, then multiply by -2 for idealized performance before fees and tracking effects.
• Risk analysis: Use ranges (high/low) to analyze intraday drawdowns for leveraged exposure.

From gold USD/oz to a DZZ-style daily path

The following are common steps used by quants and data analysts to derive a DZZ-style indicative series from Metals-API gold data. This process is illustrative; always verify your method against the ETN’s official indicative value methodology, prospectus, and data provider notes.

1. Fetch USD per ounce series for XAU across your backtest window (via Time-Series).
2. Compute daily returns r_t = (P_t / P_{t-1}) - 1 using close-to-close prices.
3. Multiply returns by -2 to emulate the target leverage on a daily basis: R_t = -2 * r_t.
4. Compound the daily leveraged returns to build a synthetic value series: V_t = V_{t-1} * (1 + R_t).
5. Incorporate ETN fees and tracking methodology if you have the necessary inputs (these are not provided by Metals-API). For auditability, keep the fee adjustments modular.
6. Compare your synthetic path to publicly available DZZ indicative levels or adjusted close series to evaluate tracking quality. You can find reference data on major finance portals (e.g., Nasdaq DZZ page or ETFdb overview of DZZ).

Note: DZZ is exchange-traded and subject to market pricing, spreads, and roll/financing considerations when relevant. Metals-API does not provide ETN/ETF prices or issuer-specific data; it provides the underlying metals pricing needed for rigorous modeling.

Practical details developers often miss

• Unit consistency: Everything is per troy ounce. If your portfolio accounting is in grams or kilograms, convert after deriving USD/oz to avoid compounding rounding errors.
• Base currency: Default base is USD. If you need gold priced in another currency, evaluate conversion pathways in your architecture, but for DZZ (USD-listed), USD as base is typically correct.
• Weekend/holiday handling: Metals markets may have limited updates on weekends/holidays. For daily compounding, use the business-day grid provided by the time-series endpoint. If your reference DZZ series uses exchange trading days, align calendars carefully.
• Caching: Cache historical responses aggressively. Historical data changes rarely; avoid redundant API calls in loops. Use immutable object storage (e.g., S3) with date-partitioned keys.
• Retry/backoff: Implement exponential backoff on transient failures and respect your plan’s rate limits.
• Precision: Use decimal libraries for inversion and percentage calculations to reduce floating-point drift, especially over long levered compounding windows.

Authentication and request structure

• API key: Include your access_key parameter in each request’s query string.
• Security: Do not hardcode keys into client-side web apps; use a secure backend proxy or serverless function to call Metals-API. Store keys in a secrets manager.
• Transport: Always use HTTPS.

Get started now: visit the Metals-API Website and sign up for a free API key, then follow the quick-start documentation to make your first request.

Endpoint deep dive for DZZ-focused workflows

1) Time-Series endpoint

Purpose: Pull daily historical rates for XAU across a contiguous range—ideal for backtesting and research pipelines.

• Method: GET /api/timeseries
• Key parameters:
  • access_key: Your API key.
  • start_date: YYYY-MM-DD.
  • end_date: YYYY-MM-DD.
  • base: USD (recommended for DZZ analysis).
  • symbols: XAU.

Example — standard success

{
"success": true,
"timeseries": true,
"start_date": "2026-09-15",
"end_date": "2026-09-22",
"base": "USD",
"rates": {
"2026-09-15": {"XAU": 0.000485},
"2026-09-17": {"XAU": 0.000483},
"2026-09-22": {"XAU": 0.000482}
},
"unit": "per troy ounce"
}

Example — empty or sparse dates

{
"success": true,
"timeseries": true,
"start_date": "2026-12-24",
"end_date": "2026-12-27",
"base": "USD",
"rates": {
"2026-12-24": {"XAU": 0.000500}
// 2026-12-25 and weekend days may be omitted if no updates
},
"unit": "per troy ounce"
}

Example — error scenario

{
"success": false,
"error": {
"code": "invalid_access_key",
"info": "You have not supplied a valid API Access Key."
}
}

Field-by-field guidance

• rates: A map from date to symbol map. Always check for the presence of the date key before accessing rates[date].XAU.
• Data alignment: Build a canonical date index; left-join the returned dates; forward-fill if your backtest requires continuous compounding across non-trading days.
• Performance: For multi-year spans, paginate by years or quarters and aggregate offline.
• Security: Avoid exposing your key in client browser requests; proxy via backend.

2) Historical endpoint

Purpose: Fetch a single day’s XAU rate for validation, targeted fills, or UI interactions.

• Method: GET /api/YYYY-MM-DD
• Key parameters:
  • access_key
  • base=USD
  • symbols=XAU

Success example

{
"success": true,
"timestamp": 1789949526,
"base": "USD",
"date": "2026-09-21",
"rates": {
"XAU": 0.000485
},
"unit": "per troy ounce"
}

Error example — malformed date

{
"success": false,
"error": {
"code": "invalid_date",
"info": "You have provided an invalid date."
}
}

Usage notes

• Use as a building block for patching holes after primary time-series pulls.
• Log returned date/timestamp for audit trails.
• Ensure consistent inversion to USD/oz in a shared utility function.

3) OHLC endpoint

Purpose: Retrieve open, high, low, and close for XAU. Essential for daily return precision when modeling -2x compounding and for risk stats like intraday drawdown.

• Method: Refer to “Open/High/Low/Close (OHLC) Price Endpoint” in the docs; availability may vary by plan.
• Key fields: rates.XAU.open, high, low, close — all as ounces per USD; invert to USD per ounce.

Success example

{
"success": true,
"timestamp": 1790035926,
"base": "USD",
"date": "2026-09-22",
"rates": {
"XAU": {
"open": 0.000485,
"high": 0.000487,
"low": 0.000481,
"close": 0.000482
}
},
"unit": "per troy ounce"
}

Using OHLC to compute returns

• Close-to-close return for day t: r_t = (Close_t / Close_{t-1}) - 1, using USD/oz values.
• -2x daily modeled return: R_t = -2 * r_t.
• Compounded value: V_t = V_{t-1} * (1 + R_t). Initialize V_0 = 100 (or your chosen base).

Flawless inversion and precision handling

Because Metals-API expresses precious metals as ounces per USD, correct and precise inversion is non-negotiable.

• Inversion: price_usd_per_oz = 1.0 / xau_rate.
• Use high-precision decimal arithmetic to avoid rounding drift over many compounding steps. Apply banker's rounding or IEEE 754 decimal with sufficient scale.
• Unit annotations: Carry unit metadata with your series (USD/oz) through the pipeline to prevent mixing series in gram or kilogram conversions.

Calendar alignment for DZZ vs. XAU

DZZ trades on exchange business days, while gold spot markets have their own session times and holiday calendars. Your backtest should define a canonical day boundary and calendar:

• Approach A (common): Use Metals-API date keys as daily anchors and match the closest DZZ trading day. Omit non-overlapping days or carry-forward returns with care.
• Approach B (exchange-led): Use the exchange calendar for DZZ, then left-join the XAU series; forward-fill the most recent XAU close to calculate the implied daily move for closed gold markets (prefer paired-day returns where possible).
• Document assumptions: Log your calendar mapping in the research report for reproducibility.

Caching, rate usage, and performance strategy

• Immutable caching: Store historical JSON responses in object storage keyed by start-end-symbols. Reuse them in pipelines and notebooks.
• Chunking: For long histories, break into quarters or months. Concurrency should respect service constraints and your plan’s throughput.
• Indexing: Convert API JSON into columnar formats (Parquet/Feather) for analytics; partition by year and symbol.
• Warm caches: Pre-fetch recent 1–3 months daily to speed dashboards; schedule backfills during off-peak hours.

Error handling and recovery

• Guard on success flag and HTTP status. If success=false, inspect error.code and error.info and route to remediation logic.
• Retries: Exponential backoff with jitter. Cap retries to avoid thundering herds.
• Fallbacks: If a single date fetch fails, proceed with partial data and mark the gap for a later patch run via the Historical endpoint.
• Monitoring: Emit metrics on response times, error rates, and missing dates. Alert if anomalies exceed thresholds.

Security best practices

• Key storage: Use environment variables or a secret manager (e.g., AWS Secrets Manager, GCP Secret Manager).
• Access pattern: Call Metals-API from backend systems. If you must call from client apps, proxy through an authenticated backend that injects the access key server-side.
• Least privilege: Only distribute the key to services that truly need it. Rotate periodically.

Data validation and QA checklist

• Schema validation: Confirm presence and types of success, base, unit, date keys, and rates.XAU.
• Numerical sanity: Flag negative or zero rates; assert 0 < XAU < 1 (since it’s ounces per USD), except under extreme regimes.
• Continuity: Verify no unexpected large gaps; compare to prior ranges to detect anomalies.
• Cross-check: Randomly sample dates and validate against a second trusted source for peace of mind.

Putting it together: from API to DZZ research artifacts

1. Pull XAU daily series for your analysis window using Time-Series (and OHLC for precision).
2. Compute USD/oz from the inverted XAU rates.
3. Derive daily returns and map to -2x for a DZZ-style return series.
4. Compound returns to form a synthetic DZZ value index, applying fees/drag if you track them separately.
5. Validate against an external DZZ reference series for select dates (e.g., Nasdaq DZZ data).
6. Export to your research store (e.g., Parquet) for downstream use in portfolio analytics, VaR, or signal generation.

Additional tips for robust DZZ modeling

• Rebalancing effects: Remember that leveraged exposures reset daily; long-run returns will deviate from -2x of cumulative underlying return due to volatility decay/benefit.
• OHLC-enhanced stress: Use high-low ranges to test worst/best plausible daily scenarios in a risk engine.
• Scenario testing: Feed USD/oz paths into Monte Carlo frameworks to estimate future distribution of DZZ-like outcomes.

Real-time vs. historical for DZZ workflows

• Backtesting: Use Time-Series and Historical endpoints.
• Live monitoring: You might sample the latest price during the day for risk oversight, but note that DZZ’s indicative value and exchange price can deviate intraday. Align refresh cadences to your tolerance.
• End-of-day processes: Standardize on an EOD snapshot time; pin your D+1 jobs to that cutoff for deterministic results.

Practical conversion: grams, kilograms, and portfolio reporting

• USD/oz to USD/g: divide by 31.1034768.
• USD/oz to USD/kg: multiply by 32.1507466.
• Keep unit metadata in column names or a sidecar schema registry to prevent misinterpretation when merging data.

Example end-to-end flow using curl + a simple transform

Step 1 — Fetch a date range:

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

Step 2 — Use your ETL to invert rates to USD/oz and compute daily returns. Step 3 — Multiply daily returns by -2, then compound. Step 4 — Persist results with metadata: symbol=XAU, derived_index=DZZ_synthetic, unit=USD/oz.

Troubleshooting common pitfalls

• Misreading the rate: If your computed USD/oz looks off by several orders of magnitude, you probably forgot to invert.
• Time gaps: Weekends/holidays missing? That’s expected. Define a strict calendar and forward-fill only if it aligns to your DZZ methodology.
• Data drift: If your synthetic DZZ diverges from real DZZ more than expected, assess fee modeling, compounding alignment, trading day mismatches, and any adjustments announced by the issuer.
• API throttling: Cache, chunk long pulls, and schedule heavy jobs during off-peak windows.

Governance, lineage, and reproducibility

• Data lineage: Persist raw API JSON and document the transform steps and code versions.
• Version control: Tag model versions when you change fee assumptions or compounding rules.
• Notebooks vs pipelines: Use notebooks for discovery, then migrate to CI/CD-managed pipelines for production stability.

Scaling architecture for enterprise backtests

• Batch orchestration: Use Airflow or similar to schedule periodic refreshes and re-computations (e.g., monthly roll-ups).
• Columnar analytics: Convert to Parquet, partition by year and symbol, and query with Spark/DuckDB/Trino.
• API gateway: Centralize Metals-API access behind an internal gateway that injects keys and enforces quotas.
• Monitoring: Track SLA metrics (latency, error rate), data freshness, and schema drift.

Compliance and audit

• Retention: Keep raw responses for a defined retention period to support audits.
• Reproducibility: Archive the configuration (start_date, end_date, base, symbols) alongside output datasets.
• Access controls: Enforce role-based access to raw and transformed datasets.

Linking to sources and extended reading

• Metals-API Website — Get your API key and start querying per-ounce gold history today.
• Metals-API Documentation — Parameters, endpoints, and implementation details.
• Metals-API Supported Symbols — Confirm XAU and related symbol metadata.
• Nasdaq DZZ overview and pricing — External reference for comparisons.
• ETFdb DZZ page — Context on the ETN and methodology (external, for comparison and research).

Conclusion

To research and model DB Gold Double Short ETN (DZZ), you need robust, per-ounce gold prices over clean, well-defined date ranges. Metals-API provides precisely that: normalized XAU data with daily history and OHLC, returned as JSON and standardized to per troy ounce. With careful inversion (oz/USD to USD/oz), calendar alignment, and daily compounding, you can construct a transparent -2x gold analysis to validate DZZ behavior, develop risk views, and power production dashboards.

If you are ready to build, secure a free key on the Metals-API Website, verify XAU on the supported symbols list, and follow the implementation guide to integrate the Time-Series, Historical, and OHLC endpoints into your DZZ analytics pipeline.

FAQ

Does Metals-API return DZZ prices directly?

No. Metals-API provides metals pricing such as gold (XAU) per troy ounce. To analyze DZZ, use XAU USD/oz data to compute daily returns and map them into a -2x leveraged series. For official DZZ prices or indicative values, use exchange or issuer data sources.

What unit is the gold price in?

Per troy ounce. Convert to grams or kilograms as needed after you compute USD/oz by inverting the XAU rate.

How do I convert the XAU rate to USD per ounce?

Metals-API rates are ounces per USD. Invert to get USD per ounce: price = 1 / rates.XAU.

How should I handle weekends and holidays?

Expect fewer or no updates. Align your backtest on a business-day calendar and decide whether to skip non-trading days or forward-fill depending on your DZZ methodology.

Can I get open/high/low/close for more precise modeling?

Yes. Use the OHLC endpoint for XAU if your plan supports it. Convert each field to USD/oz and compute close-to-close returns for daily compounding.

What about API limits and performance?

Cache historical responses, chunk long ranges, and schedule heavy jobs off-peak. Monitor errors and implement retry with backoff.

Where do I find all available symbols?

See the Metals-API Supported Symbols page.

How do I start?

Get a free API key on the Metals-API Website, then follow the Metals-API Documentation to make your first time-series request for XAU.