Access Guatemalan Quetzal (GTQ) prices using this API

Pricing precious and industrial metals in Guatemalan Quetzal (GTQ) is a common requirement for jewelers selling retail in Guatemala, commodity traders hedging local inventories, fintech apps quoting user balances, and manufacturers indexing bills-of-materials. With Metals-API, you can access GTQ prices for gold, silver, platinum, palladium, copper, aluminum and more in real time and historically—then integrate them into your trading tools, ERP, pricing engines, and dashboards. This guide shows how to work with GTQ-denominated metals using Metals-API, explains units and conversions (troy ounce vs gram), covers key endpoints with realistic JSON responses, and provides practical implementation advice for reliability, performance, and accuracy.

Why GTQ-denominated metals pricing matters and what you can build today

Developers, quants, and product managers working in or with Guatemala often need to express metals prices in local currency to remove USD exposure from user-facing quotes, align invoicing with accounting ledgers, and improve price transparency for local stakeholders. With Metals-API, you can:

• Quote live retail prices in GTQ for gold jewelry and silverware, down to per-gram granularity.
• Backfill GTQ-denominated historical charts for research and investor reporting.
• Automate GTQ purchase orders and hedging workflows against intraday spot, OHLC, or bid/ask data.
• Alert on GTQ fluctuation thresholds to manage margin and reprice SKUs.
• Run cost-plus calculations for manufacturing BOMs indexed to copper (XCU) or aluminum (XAL) in GTQ.

If you’re ready to try it, you can explore the API now. See the Metals-API Website and get a free API key to prototype GTQ pricing in minutes, and review all supported symbols via the Metals-API Supported Symbols page for a complete list of metals and currencies.

How GTQ quoting works with Metals-API

Metals-API returns metals and currency exchange rates in consistent JSON. By default, exchange rates are relative to USD, and metal rates are expressed “per troy ounce.” Understanding the base currency and units is essential for correct GTQ conversions.

• Base currency: API responses are by default relative to USD. That means the “rate” for a metal symbol (like XAU) is a quantity of that metal per 1 USD (for example, XAU = 0.000482 means 1 USD buys 0.000482 troy ounces of gold).
• To compute USD price per troy ounce: price_per_oz_usd = 1 / XAU_rate.
• To compute GTQ price per troy ounce: multiply the USD price per troy ounce by the USD→GTQ exchange rate.
• To compute per-gram prices: 1 troy ounce = 31.1034768 grams. price_per_gram_gtq = price_per_oz_gtq / 31.1034768.

Because Metals-API also provides currency rates, you can get both the metal rate and the GTQ currency rate from the same platform and combine them deterministically. You’ll see this pattern in the “quickstart” section below.

Units and conversions: troy ounces, grams, and carats

The metals industry uses troy ounces as the standard weight unit for precious metals pricing. If you display user-facing quotes in grams, always convert from troy ounces with high precision.

• 1 troy ounce (ozt) = 31.1034768 grams.
• If you’re quoting gold jewelry by carat, you can use the Carat endpoint to obtain carat-specific rates and then convert to GTQ using the same USD→GTQ factor you computed for spot metal. This is especially helpful for retail price engines where purity affects markup.

Make sure you keep the “unit” field from responses. Metals-API explicitly returns a “unit” field (for example, “per troy ounce” or “troy ounces”), which documents the measurement basis for the numbers you process.

Quickstart: combine metals spot with GTQ FX and compute per-gram quotes

The most robust GTQ quote combines:

1. The latest metal rate relative to USD (for example, XAU from the Latest or OHLC endpoint).
2. The USD→GTQ currency rate (via Latest, Time-series, or Convert endpoints).

Below is a realistic flow using cURL for quick testing and a JavaScript snippet for integration. For a complete reference of endpoints and parameters, consult the Metals-API Documentation.

Example: cURL to fetch latest metal rates and USD→GTQ

First, fetch the latest rates for metals you care about. Replace YOUR_ACCESS_KEY with your key.

curl -s "https://metals-api.com/api/latest?access_key=YOUR_ACCESS_KEY&symbols=XAU,XAG,XPT,XPD,XCU,XAL"

Example JSON (realistic structure):

{
"success": true,
"timestamp": 1789432163,
"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
},
"unit": "per troy ounce"
}

Then, retrieve the USD→GTQ exchange rate. One approach is to query the latest endpoint including GTQ among fiat symbols:

curl -s "https://metals-api.com/api/latest?access_key=YOUR_ACCESS_KEY&symbols=GTQ"

A typical response will include GTQ as a currency rate relative to USD (structure consistent with other currencies on Metals-API).

JavaScript example: compute XAU price per gram in GTQ

The following minimal JavaScript fetches XAU and GTQ, then derives the GTQ per gram price. You can extend this to other metals or to inventory-level pricing.

// Minimal example: derive GTQ per gram for XAU from two latest calls
async function quoteGoldPerGramGTQ() {
const accessKey = process.env.METALS_API_KEY; // store securely
const metalsRes = await fetch(`https://metals-api.com/api/latest?access_key=${accessKey}&symbols=XAU`);
const metalsJson = await metalsRes.json();

if (!metalsJson.success) throw new Error("Failed to fetch XAU");

const fxRes = await fetch(`https://metals-api.com/api/latest?access_key=${accessKey}&symbols=GTQ`);
const fxJson = await fxRes.json();

if (!fxJson.success) throw new Error("Failed to fetch GTQ");

const xauRate = metalsJson.rates.XAU; // ounces per 1 USD
const usdPerOunce = 1 / xauRate;

const usdToGtq = fxJson.rates.GTQ; // GTQ per 1 USD
const gtqPerOunce = usdPerOunce * usdToGtq;

const gramsPerTroyOunce = 31.1034768;
const gtqPerGram = gtqPerOunce / gramsPerTroyOunce;

return {
date: metalsJson.date,
gtqPerOunce,
gtqPerGram,
unit: "GTQ",
};
}

Key fields used:

• success: verify true before using rates.
• timestamp and date: drive cache keys, logs, and user-facing “as of” labels.
• base: if it’s “USD,” your XAU rate is ounces per USD. If your plan allows changing base, recompute accordingly and document it.
• rates: a map of symbol to rate, with “unit” describing the basis (for metals, “per troy ounce”).

Deep dive: endpoint-by-endpoint techniques for GTQ workflows

Below we walk through how each major feature can be used to support GTQ-denominated pricing, charting, analytics, and risk-control. Keep in mind that the API returns consistent JSON and timestamps, and data is by default relative to USD unless specified otherwise by your plan and query.

Latest Rates: powering live GTQ quotes on product pages and trading UIs

Purpose: Fetch real-time exchange rate data updated per plan (for example, every 60 or 10 minutes). Use it to power live quotes, price labels, and intraday analytics in GTQ.

How to apply for GTQ:

1. Get the latest metal rates for your symbols (e.g., XAU, XAG, XPT, XPD, XCU, XAL).
2. Get USD→GTQ rate.
3. Convert per-ounce USD prices to GTQ per ounce and GTQ per gram.

Example JSON (as returned for metals):

{
"success": true,
"timestamp": 1789432163,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": 0.000482,
"XAG": 0.03815,
"XPT": 0.000912,
"XPD": 0.000744
},
"unit": "per troy ounce"
}

Field notes for GTQ conversion:

• timestamp: Unix epoch seconds, helpful for caching TTL and time-series alignment.
• rates.XAU: ounces per USD. Invert to get USD per ounce, then multiply by GTQ per USD.
• unit: always confirm for precious metals calculations; if you later consume OHLC, the unit remains consistent.

Common pitfalls:

• Forgetting to invert metals rates: metals are quoted as quantity per USD, not USD per ounce. Always invert.
• Precision drift: retain sufficient precision during inversions and gram conversions; use decimal libraries for finance-sensitive apps.
• Weekend/holiday staleness: commodity and FX markets may have reduced activity. Use timestamp and date to label data freshness, and consider fallbacks to prior close.

Historical Rates: backfilling GTQ-denominated charts and P&L

Purpose: Query historical rates by appending a date and derive GTQ-denominated values across time. Historical data is generally available since 2019.

Workflow for GTQ:

1. For each historical date, retrieve historical metal rates (e.g., XAU) and USD→GTQ for the same date.
2. Invert the historical metal rate to get USD per ounce and multiply by the corresponding historical USD→GTQ rate.
3. Aggregate into time series for charting and analytics.

Example JSON (historical metals):

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

Field notes:

• date: Align FX and metal calls to the same date to avoid cross-date currency mismatches.
• timestamp: Useful for verifying the effective time and for intraday backfills when available.

Edge handling:

• Non-business days: If the requested historical date falls on a weekend or holiday, ensure you understand whether the data represents last available close. Surface this context to end users.
• Data availability: For some symbols, earliest availability may vary. Consult the Metals-API Supported Symbols list for coverage.

Time-Series: building GTQ analytics across custom ranges

Purpose: Retrieve daily historical rates between two dates. Use this to construct GTQ-denominated charts, moving averages, volatility, and VaR backtests.

Example JSON (time-series metals):

{
"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"
}

How to use for GTQ:

• Call time-series for metals you need.
• Call time-series (or historical per date) for USD→GTQ across the same range.
• Join on date, invert metal rates to USD per ounce, multiply by GTQ-per-USD to get GTQ per ounce, then derive GTQ per gram.

Performance considerations:

• Windowing: If you maintain rolling analytics windows (e.g., 30D or 90D), cache results and only fetch the delta for new days.
• Compression: Store processed GTQ time-series server-side rather than recomputing on each client request.

Fluctuation: alerting on GTQ moves and managing margins

Purpose: Retrieve information about how rates fluctuate day-to-day over a date window. Useful for setting GTQ-based alerts and repricing triggers.

Example JSON (fluctuation for metals):

{
"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"
}

GTQ application:

• Convert start_rate and end_rate to USD per ounce by inversion, then multiply each by the corresponding USD→GTQ start and end currency rates to get GTQ per ounce at both endpoints. Recompute change_pct in GTQ terms if needed.
• Set alert thresholds in GTQ terms (e.g., “XAU per gram GTQ moved more than 1.5% since last reprice”).

Tip: Because change_pct is computed in the base currency, recompute it if you want GTQ-native percentage movement. Differences are usually small but matter if GTQ has nontrivial FX moves within the window.

OHLC: GTQ intraday bars for charting and auditability

Purpose: Retrieve open, high, low, and close for metals over a period. Great for candlestick charts, intraday backtests, and reconciling price events.

Example JSON (OHLC for metals):

{
"success": true,
"timestamp": 1789432163,
"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"
}

GTQ conversion approach:

• Invert each OHLC value for a given metal to get USD per ounce.
• Multiply each by the corresponding USD→GTQ rate at the open/high/low/close timestamps if available, or use a representative rate (e.g., close) if your use case allows.
• For candlesticks, produce OHLC in GTQ per ounce then convert to GTQ per gram if needed.

Auditability practices:

• Log source timestamp and base currency in your price objects.
• Attach your computed GTQ OHLC to the original metals OHLC and FX rates for traceability.

Bid/Ask: managing spreads in GTQ and setting retail markups

Purpose: Retrieve real-time Bid and Ask prices for the metals you trade. This is critical for execution-sensitive apps, market-making UIs, and retail price calculators that include spread-aware markups.

Example JSON (bid/ask):

{
"success": true,
"timestamp": 1789432163,
"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"
}

GTQ conversions and applications:

• Invert bid and ask separately to get USD per ounce bid and ask. Then multiply by USD→GTQ to get GTQ bid and ask per ounce (and per gram if necessary).
• Retail pricing engines often set the user-facing price closer to ask for purchases and closer to bid for buybacks. Express these clearly in GTQ to avoid customer confusion.

Risk controls:

• Use spread to set minimum markup floors so that GTQ quotes cannot dip below your execution cost once converted.
• Pin your margin to GTQ so that FX volatility doesn’t erode local-currency profits.

Convert: translating values and amounts cleanly between units and currencies

Purpose: Convert any amount from one currency/metal to another. This is particularly useful for FX conversions, or when translating USD amounts into GTQ for invoices. It also helps when you want to convert between metals or from USD to a metal amount.

Example JSON (convert USD→XAU):

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

How to use for GTQ:

• Convert USD invoice totals to GTQ using Convert, or retrieve USD→GTQ from Latest and multiply locally for bulk operations.
• If your workflow starts with a GTQ budget and you need to know how many ounces you can buy, combine USD→GTQ FX with USD↔XAU conversions carefully. Where direct metal↔GTQ conversions aren’t provided, chain through USD deterministically.

Notes:

• “result” is expressed in the target unit (“troy ounces” in the example). Ensure your UI labels match.
• “info.rate” provides the effective conversion rate at the timestamp; log it for audits.

Carat: purity-aware GTQ quotes for retail gold pricing

Purpose: Retrieve gold rates by carat. If you sell 14K, 18K, or 22K jewelry, this endpoint saves you from manually applying purity factors and reduces pricing error.

GTQ application approach:

• Retrieve carat-specific rate relative to USD, invert to get USD price per troy ounce of that carat standard, then convert to GTQ via USD→GTQ.
• Convert to per-gram GTQ using the troy-ounce to gram conversion for item-level price tags.

Practical tip: Maintain a purity table in your code for nonstandard alloys and document when you apply carat vs. fine gold assumptions in customer-facing labels.

Lowest/Highest: bounding GTQ price ranges for the day

Purpose: Retrieve lowest and highest prices for a selected date. Useful for “today’s range” in GTQ or for setting automated discount/markup thresholds.

GTQ application:

• Pull lowest-highest for your symbols, invert to USD, multiply by USD→GTQ to compute the GTQ bounds.
• Display range bands on charts and validate internal alerts stay within expected GTQ envelopes.

Historical LME: long-horizon industrials pricing and GTQ cost indices

Purpose: Access historical rates for LME symbols dating back to 2008. Manufacturers and commodity desks in Guatemala can create GTQ-indexed input-cost curves and procurement KPIs over longer horizons.

GTQ application:

• Fetch LME history for copper or aluminum symbols, invert if needed, then convert to GTQ across the series.
• Use resulting GTQ series to reindex BOM assumptions and price-variance analyses.

Intraday: single-symbol, high-resolution views for execution decisions

Purpose: Query intraday exchange rate data for a single symbol. For short-term hedging or high-frequency pricing, this endpoint helps you keep GTQ quotes tighter and more responsive.

GTQ application:

• Consume intraday metal ticks or intervals, invert to USD per ounce, then multiply by concurrent USD→GTQ intraday rates for real-time GTQ numbers.
• Cache short-term results and apply circuit-breakers if spreads widen or FX moves abruptly.

Authentication, base currency, symbols, and response format

Authentication: Pass your API key via the access_key parameter. Keep your key secure (environment variables, secret managers) and never expose it in client-side code shipped to browsers unless you’ve implemented a secure proxy. To get started, visit the Metals-API Website and obtain your free API key.

Base currency: Responses are by default relative to USD. Many workflows rely on this consistent base to simplify inversions and conversions. If your plan supports changing base, document your logic carefully and keep unit tests aligned with expected base.

Symbols: Metals-API supports a wide array of precious and industrial metal symbols plus fiat currencies. Explore coverage at the Metals-API Supported Symbols page, and include GTQ in your workflows.

Response format: All data is returned in JSON. Fields include success, timestamp, base, date, rates, and unit. For special endpoints you’ll also see structures for open/high/low/close, bid/ask, spread, or query/info/result (for Convert).

Practical integration guidance for GTQ workflows

Timestamps and timezone

• Use the timestamp field (epoch seconds) as your source of truth for data recency.
• When presenting “as of” labels to Guatemalan users, convert to local time (America/Guatemala, UTC-6, no DST) to avoid confusion.
• Log both UTC timestamps and formatted local times for auditability.

Caching to save requests and stabilize quotes

• Cache metals and FX snapshots keyed by symbol and rounded timestamp buckets (e.g., minute or plan-appropriate interval).
• For e-commerce, consider a short cache (30–120 seconds) to avoid mid-cart price flicker while maintaining quote realism.
• For backfills and charts, cache results server-side indefinitely and invalidate only when you detect corrections or reprocessing needs.

Handling weekends and market closures

• Commodities and FX may have reduced updates on weekends or holidays; responses remain valid as of the provided timestamp.
• In UI labels, show “Last updated [local time]” to set expectations.
• Automated repricers should impose guardrails (e.g., pause repricing) if new data hasn’t arrived within expected plan intervals.

Data validation and sanitization

• Always check success === true and the presence of required fields before using data.
• Validate numerics: reject NaN, null, or out-of-bounds values (e.g., negative rates).
• Apply schema checks for response shape changes and instrument-specific fields (e.g., bid/ask vs. OHLC).

Error handling and recovery

• Gracefully handle HTTP/network errors with exponential backoff.
• Fallback to the most recent valid cached snapshot if the latest call fails.
• Surface “degraded mode” indicators in admin dashboards when serving cached values beyond typical freshness windows.

Performance and scaling

• Batch symbols: Request multiple metals in one Latest call (e.g., XAU,XAG,XPT) to minimize round trips.
• Precompute derived GTQ series for dashboards rather than converting on every page view.
• Use asynchronous pipelines for bulk historical jobs: fetch time-series, join FX, invert, and store GTQ results in your data warehouse.

Security considerations for production apps

• Store the access_key in a secure vault or environment variable; never commit it to source control.
• Proxy API calls through your backend if your clients are browser-based to protect the key and support server-side caching.
• Monitor usage and anomaly patterns; alert if call volume spikes unexpectedly.

GTQ-specific use cases with step-by-step implementations

Use case: E-commerce pricing for gold jewelry in GTQ

1. Fetch XAU from Latest and the USD→GTQ rate.
2. Invert XAU to get USD per ounce; multiply by USD→GTQ to get GTQ per ounce.
3. Convert per-ounce GTQ to per-gram GTQ for item weights; apply carat adjustments if needed via the Carat endpoint.
4. Add markup tiers and local taxes; cache the resulting per-gram GTQ price for 60 seconds for stability.
5. Label “as of” time in America/Guatemala.

Use case: Intraday hedging for a refiner quoting buy/sell in GTQ

1. Use Bid/Ask to maintain GTQ bid and GTQ ask curves (invert then multiply by USD→GTQ).
2. Refresh at plan granularity; apply a spread floor and GTQ-based margin to prevent loss at execution.
3. If Intraday is available, tighten refresh windows and implement circuit-breakers for spread anomalies.

Use case: Manufacturing BOM reindexing for copper and aluminum in GTQ

1. Pull a Time-series for XCU and XAL over 12–36 months.
2. Get USD→GTQ time-series and join on date.
3. Invert and multiply to build GTQ per tonne or per kilogram equivalents (derive unit conversions from troy ounce as needed or maintain a separate industrial conversion factor if your internal costing requires weight units beyond troy ounces).
4. Recompute BOM unit costs and variance in GTQ; publish dashboards to procurement.

Use case: Research dashboards for GTQ investors

1. Use OHLC to build candlestick charts; convert O/H/L/C to GTQ per ounce then to per gram for retail context.
2. Pull Fluctuation to render side panels showing GTQ percentage moves over daily or weekly windows.
3. Cache server-side for consistent session views; provide a “refresh” control that pulls a new snapshot on demand.

Tellurium (TE) spotlight: digital transformation of niche metals pricing in GTQ

Tellurium (TE) is a great example of how digital transformation in metal markets can unlock value for specialized supply chains, including those in photovoltaics, semiconductors, and advanced alloys. Even when a niche metal doesn’t trade with the liquidity of gold or silver, the same API-driven approach transforms how teams plan, price, and hedge.

Technological innovation and smart integration

• Data pipelines: Use Metals-API to drive TE-linked indices denominated in GTQ for local project finance modeling.
• Smart technology: Integrate IoT-driven inventory telemetry with API-based GTQ valuations to reconcile warehouse stocks in real time.
• Analytics and insights: Run sensitivity analyses showing how TE-linked component costs affect GTQ project budgets under different FX and commodity scenarios.

Future trends and possibilities

• Automated risk transfer: GTQ-smart contracts that settle based on Metals-API-sourced reference prices.
• Decarbonization premiums: GTQ-adjusted green premia layered on top of base metal GTQ prices for sustainability-focused procurement.

Regardless of liquidity, the same best practices—timestamp alignment, inversion correctness, FX pairing, and robust caching—ensure dependable GTQ valuations for TE and other specialized materials.

End-to-end data architecture patterns for GTQ

Server-side orchestration

• Workers fetch Latest and FX at plan cadence; results are normalized to USD per ounce and USD→GTQ then stored in a key-value store (e.g., Redis) with timestamps.
• An analytics job builds GTQ time-series nightly from Time-series and Fluctuation data, writing to a warehouse (e.g., BigQuery, Snowflake) and exposing APIs for charts.
• JavaScript clients request a compact “/quotes?symbols=XAU,XAG&currency=GTQ” from your backend; the backend serves precomputed GTQ with an “as of” timestamp.

Data quality controls

• Sanity checks: If a new XAU rate deviates more than N standard deviations from a rolling mean, flag for review.
• Cross-validation: Compare GTQ quotes derived via two methods (Convert→XAU vs. Latest→XAU plus Latest→GTQ) for consistency.

Audit trail

• Log raw JSON for each upstream call along with derived GTQ values and formulas used for inversion and multiplication.
• Persist the version of your conversion code to reproduce results later.

Detailed endpoint walkthroughs with GTQ considerations

Latest: real-time snapshots

Purpose: Provide the most recent rates for metals and currencies.

Key parameters:

• access_key: your API key.
• symbols: a comma-separated list of metal and/or currency symbols to reduce payload size.

Success response example:

{
"success": true,
"timestamp": 1789432163,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": 0.000482,
"GTQ": 7.82
},
"unit": "per troy ounce"
}

Error scenario example:

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

GTQ guidance:

• After fetching XAU and GTQ, compute GTQ-per-ounce = (1 / XAU) * GTQ.
• For user-facing displays, precompute GTQ-per-gram and round appropriately (e.g., two decimals for retail, more for B2B).

Historical: point-in-time accuracy

Purpose: Get rates at a specific historical date (e.g., YYYY-MM-DD).

Success response example:

{
"success": true,
"timestamp": 1789345763,
"base": "USD",
"date": "2026-09-14",
"rates": {
"XAU": 0.000485,
"GTQ": 7.80
},
"unit": "per troy ounce"
}

Error example (invalid date):

{
"success": false,
"error": {
"code": "invalid_date",
"message": "The specified date is invalid or outside available range."
}
}

GTQ guidance:

• Always fetch GTQ for the same date as the metal to avoid FX mismatch.
• When backfilling, store both original rates and derived GTQ conversions for repeatability.

Time-series: multi-day windows

Purpose: Retrieve daily rates over a specified range.

Success response example (metals slice):

{
"success": true,
"timeseries": true,
"start_date": "2026-09-08",
"end_date": "2026-09-15",
"base": "USD",
"rates": {
"2026-09-08": { "XAU": 0.000485, "GTQ": 7.79 },
"2026-09-10": { "XAU": 0.000483, "GTQ": 7.81 },
"2026-09-15": { "XAU": 0.000482, "GTQ": 7.82 }
},
"unit": "per troy ounce"
}

Error example (date window too large for plan):

{
"success": false,
"error": {
"code": "date_range_exceeded",
"message": "The specified date range exceeds your plan's limits."
}
}

GTQ guidance:

• Join metal and GTQ rates by date; compute derived GTQ series once and cache.
• For analytics, compute percentage changes in GTQ space directly.

Fluctuation: day-to-day changes

Purpose: Compare start and end rates and compute absolute and percentage change.

Success response example:

{
"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"
}

GTQ guidance:

• Recompute change_pct using GTQ-converted start and end prices if you want local-currency sensitivity.
• Use the results to trigger repricing or alerts in dashboards.

OHLC: structured intraday bars

Purpose: Retrieve open, high, low, close values for candlesticks and analytics.

Success response example:

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

GTQ guidance:

• Invert O/H/L/C and multiply by the relevant USD→GTQ to derive GTQ candlesticks.
• If FX at sub-daily granularity isn’t available, document which FX snapshot you used for user transparency.

Bid and Ask: execution-aware pricing

Purpose: Retrieve executable bid/ask references where supported by your plan.

Success response example:

{
"success": true,
"timestamp": 1789432163,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": { "bid": 0.000481, "ask": 0.000483, "spread": 2.0e-6 }
},
"unit": "per troy ounce"
}

GTQ guidance:

• Convert bid and ask separately to avoid underquoting in GTQ.
• Anchor markups in GTQ to preserve local margins independent of USD swings.

Carat: purity-specific gold pricing

Purpose: Provide carat-based gold pricing that maps naturally to retail SKUs.

GTQ guidance:

• Use carat outputs, invert to USD per ounce of the carat standard, convert to GTQ, then per gram for shelf labels.
• Document purity assumptions and loss factors for manufacturing cuts or scrap.

Lowest/Highest: daily bands for control limits

Purpose: Bound daily GTQ ranges for alerts, hedging limits, and UI badges.

GTQ guidance:

• Derive GTQ low/high with the same inversion+multiplication as elsewhere; store range for the session.

Historical LME and Intraday: industrial depth and responsiveness

Purpose: Support long history and short-term responsiveness for industrial metals.

GTQ guidance:

• Historical LME: build GTQ indices for procurement SLAs and budgeting.
• Intraday: refine GTQ hedging and showroom quotes for time-sensitive operations.

Realistic response scenarios and how to use them

Success case with metals and FX

{
"success": true,
"timestamp": 1789432163,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": 0.000482,
"GTQ": 7.82
},
"unit": "per troy ounce"
}

Use the inversion and multiplication to derive:

• USD per ounce = 1 / 0.000482
• GTQ per ounce = USD per ounce * 7.82

Error case: temporary outage

{
"success": false,
"error": {
"code": "rate_limit",
"message": "You have exceeded the number of requests allowed for your plan interval."
}
}

Recovery strategies:

• Use cached snapshot; degrade gracefully.
• Backoff and retry later; alert on dashboards.

Empty or partial results

{
"success": true,
"timestamp": 1789432163,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": 0.000482
},
"unit": "per troy ounce",
"warnings": [
"GTQ temporarily unavailable; using metals-only payload."
]
}

Action:

• Fallback to a cached GTQ FX rate if still acceptable for your SLA, or withhold GTQ-specific quotes until FX resumes.

Advanced techniques and best practices for GTQ at scale

Numerical accuracy

• Use decimal or big-number libraries to avoid floating-point drift in inversion and gram conversions.
• Keep at least 6–8 decimal places internally; round only at the UI layer.

Consistency across endpoints

• Normalize all data to a common internal representation (USD per ounce, USD→GTQ) before deriving GTQ values.
• Ensure OHLC, Bid/Ask, and Latest paths use identical conversion logic to avoid reconciliation issues.

Observability

• Log endpoint latency, success rates, and the age of data (now - timestamp) in metrics dashboards.
• Set alerts if the data age exceeds expected intervals for your plan.

Versioning and change management

• Wrap Metals-API access behind a thin module so changes in parameters or symbols are localized.
• Create contract tests to validate JSON shapes and critical field presence (success, timestamp, base, rates, unit).

Compliance and audit

• Persist the raw payload plus derived GTQ computations and keys for at least the retention period required by your auditors.
• Include “as of” timestamps on invoices and exportable reports.

Implementation checklist for GTQ rollouts

• Obtain your API key: Visit the Metals-API Website and sign up to get a free API key.
• Identify required symbols: Confirm coverage on the Metals-API Supported Symbols page, including GTQ.
• Design data model: Store metals rates, FX rates, and derived GTQ values with timestamps and units.
• Code conversions: Implement invert-and-multiply correctly; add per-gram conversion.
• Cache and retry: Add server-side caching, exponential backoff, and fallback logic.
• Label freshness: Display “as of” times in America/Guatemala and UTC for audits.
• Harden security: Keep access_key secret and terminate client requests at your backend.
• Monitor: Track success rates, data age, and outliers; alert on anomalies.

Comparing key symbols and how they map to GTQ workflows

Symbol	Description	Unit from API	GTQ Application
XAU	Gold	per troy ounce	Retail quotes per gram in GTQ; hedging and P&L
XAG	Silver	per troy ounce	Jewelry and industrial components priced in GTQ
XPT	Platinum	per troy ounce	Catalyst and jewelry GTQ valuations
XPD	Palladium	per troy ounce	Auto catalyst supply-chain GTQ costs
XCU	Copper	per troy ounce	Manufacturing BOM costs in GTQ
XAL	Aluminum	per troy ounce	Packaging and aerospace GTQ indices
GTQ	Guatemalan Quetzal	per 1 USD	Convert USD-denominated metals into local currency

Additional resources

• API reference and examples: Metals-API Documentation
• Symbol coverage and metadata: Metals-API Supported Symbols
• Get started and obtain your key: Metals-API Website
• Background on time zones for display logic: Time in Guatemala (Wikipedia)
• General FX market hours context: Investopedia: Forex Market Hours

Conclusion

Accessing Guatemalan Quetzal (GTQ) prices for precious and industrial metals is straightforward with Metals-API. By pairing metal rates (quoted per troy ounce relative to USD) with the USD→GTQ exchange rate and carefully handling inversions and unit conversions, you can deliver accurate, performant, and auditable GTQ pricing across retail e-commerce, trading floors, ERPs, and research dashboards. Implement robust caching and error handling, surface timestamps and units, and standardize your internal representation (USD per ounce and USD→GTQ) to keep your architecture simple and consistent. When you’re ready to build, review the Metals-API Documentation, confirm your symbols at Metals-API Supported Symbols, and get your free key from the Metals-API Website to start integrating GTQ-denominated metals today.

FAQ

How do I compute a GTQ price per gram from the API response?

Fetch XAU and GTQ from Latest. Compute USD per ounce as 1 / XAU, then multiply by GTQ (GTQ per USD) to get GTQ per ounce. Divide by 31.1034768 to get GTQ per gram.

Which endpoints are best for GTQ e-commerce pricing?

Use Latest for live quotes, optionally Bid/Ask for execution-aware pricing, and Carat for retail gold purity. Cache results for short intervals to stabilize cart totals.

Can I build GTQ candlestick charts?

Yes. Use OHLC to retrieve O/H/L/C, invert each to USD per ounce, multiply by USD→GTQ, and render in GTQ per ounce or per gram. Label timestamps in local time.

How do I monitor daily moves in GTQ?

Use Fluctuation to get start and end rates, then recompute change_pct in GTQ by converting both endpoints to GTQ per ounce before calculating the percentage.

What about industrial metals like copper and aluminum?

Use Time-series for XCU and XAL, pair with GTQ FX history, and compute GTQ cost indices for BOMs and procurement dashboards. Historical LME provides deeper history where applicable.

How should I store my API key?

Keep it server-side in environment variables or a secret manager. Route requests through your backend to avoid exposing the key in client code.

Do I need to handle weekends and holidays?

Yes. Expect fewer updates; rely on timestamp and date for freshness. Consider presenting “Last updated” labels and pausing aggressive repricing during closures.

Where can I find all supported symbols?

See the full list at Metals-API Supported Symbols.