API to Get the Paraguayan Guaraní (PYG) - N/A Price

You need to quote metal prices and portfolio P&L in Paraguayan guaraní (PYG) alongside USD, and you want a reliable way to fetch the latest USD⇄PYG rate you can cache, audit, and plug directly into pricing, hedging, or reporting. By the end of this guide, you’ll be able to call Metals-API to fetch real-time PYG rates, parse the response, and safely convert USD metal prices to PYG in your app.

When PYG matters in metals workflows

Even if your exchange-quoted metals are in USD per troy ounce, downstream billing, ERP, or e-commerce often needs local currency. For a Paraguayan jewelry retailer, a copper cathode exporter invoicing in PYG, or a fintech dashboard serving LATAM users, pairing USD metal prices with a trusted USD⇄PYG rate is essential.

This walkthrough focuses on the minimum you need to ship:

• Fetch the latest PYG rates you can cache for pricing and analytics.
• Convert USD-denominated inputs into PYG deterministically.
• Optionally derive PYG per unit metal prices when you have a USD/oz metal quote.

If you’re new to the service, start with an API key: Register. You can also skim the full parameter list in the Documentation and confirm the symbol codes on the Symbols page.

What you’ll call: keep it simple with Latest rates (PYG)

We’ll use the Latest endpoint because it returns the current rate snapshot suitable for pricing, quotes, and intraday updates. Metals-API uses USD as the default base currency and supports both direct and inverse synthetic symbols:

• rates.PYG: number of PYG per 1 USD (PYG/USD).
• rates.USDPYG: number of USD per 1 PYG (USD/PYG).

That gives you both directions without extra math. If you only request PYG, you’ll still get PYG per USD; requesting USDPYG gives you the exact inverse in the same payload.

curl request (copy-paste ready)

curl "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=PYG,USDPYG,USD"

Official JSON response example

{"success":true,"timestamp":1791418260,"date":"2026-10-08","base":"USD","rates":{"PYG":5834.520921,"USD":1,"USDPYG":0.00017139367799689134}}

What the fields mean and how you’ll use them

• success: boolean for quick health check. Only parse prices when true.
• timestamp: Unix epoch seconds for the snapshot. Use it for cache keys and audit trails.
• date: ISO date for human-facing displays and reporting.
• base: "USD" indicates all rates are quoted relative to 1 USD unless an inverse pair is named.
• rates.PYG: 5834.520921 means 1 USD equals 5,834.520921 PYG.
• rates.USDPYG: 0.00017139367799689134 means 1 PYG equals 0.00017139367799689134 USD.
• rates.USD: identity 1. Use it to sanity-check base handling.

End-to-end example in JavaScript

This snippet fetches the latest snapshot and exposes a minimal conversion helper you can reuse across your app. It calls the same Latest endpoint and reads the exact fields above.

async function fetchPygRates() {
const url = "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=PYG,USDPYG,USD";
const res = await fetch(url, { method: "GET" });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

if (!data.success) throw new Error("API returned success=false");

const { timestamp, date, base, rates } = data;
const pygPerUsd = rates.PYG; // PYG per 1 USD
const usdPerPyg = rates.USDPYG; // USD per 1 PYG

// Helper conversions
function usdToPyg(usdAmount) {
return usdAmount * pygPerUsd;
}
function pygToUsd(pygAmount) {
return pygAmount * usdPerPyg;
}

return {
timestamp,
date,
base,
pygPerUsd,
usdPerPyg,
usdToPyg,
pygToUsd
};
}

// Example usage:
fetchPygRates()
.then(({ date, pygPerUsd, usdToPyg, pygToUsd }) => {
console.log(`Snapshot date: ${date}`);
console.log(`1 USD = ${pygPerUsd} PYG`);
console.log(`100 USD = ${usdToPyg(100)} PYG`);
console.log(`1,000,000 PYG = ${pygToUsd(1_000_000)} USD`);
})
.catch(err => console.error(err));

Turning USD/oz metal quotes into PYG prices

When you already have a USD-per-oz price for a metal from your venue or from Metals-API’s metal endpoints, converting to PYG is a straightforward multiplication by rates.PYG. Two common ways to proceed:

• If you have USD per troy ounce for a metal (e.g., USD/oz for XAU), then PYG per oz = (USD per oz) × rates.PYG.
• If you instead fetch Metals-API’s metal rates using base=USD where rates.XAU is troy ounces per USD, compute USD per oz as 1 / rates.XAU, then PYG per oz = (1 / rates.XAU) × rates.PYG.

Units matter. Metal quantities in Metals-API are quoted per troy ounce unless otherwise specified. If you price inventory in grams or kilograms, convert units after obtaining PYG per ounce (1 troy ounce = 31.1034768 grams).

Add basic resilience: caching, staleness, and non-trading days

Most production stacks front Metals-API calls with short-term caching to cut latency and quota usage while keeping prices fresh:

• Cache key: use the date + symbols + base. For intraday freshness, also include the rounded timestamp bucket (e.g., minute or 10-minute granularity depending on your plan).
• Display vs. compute: display the date and/or time derived from timestamp so users understand snapshot timing, while your pricing engine always uses the numeric rates values.
• Weekend/holiday behavior: currency markets have reduced liquidity on weekends and regional holidays. When calling Latest, expect the last available snapshot; the timestamp and date will reflect the most recent publication. Avoid assuming “market open” semantics.
• Retry policy: retry idempotent GETs on network errors and on HTTP 429/5xx with exponential backoff. Persist the last-good snapshot so your UI can gracefully degrade.

Historical context: compare PYG over time

To analyze trends or backfill chart data, query the Historical or Time-series endpoints. They return the same structure (base, date, rates), making it easy to compute PYG changes over time or to normalize metal PYG prices for analytics. Keep your symbol list focused (PYG and optionally USDPYG) to minimize payload size.

• Historical Rates Endpoint: request a specific YYYY-MM-DD date to reproduce a past valuation or EOD report.
• Time-series Endpoint: fetch a span of daily snapshots for a trend line or VaR backtest.

See parameters, date ranges, and examples in the Documentation. Confirm available symbols for your plan on the Symbols page.

Parameter recap for PYG work

Keep your requests minimal and explicit. For most applications:

• Endpoint: /api/latest
• Query params: access_key=YOUR_API_KEY, symbols=PYG,USDPYG,USD
• Parsing: read rates.PYG and rates.USDPYG; use timestamp and date for audit and display.

Operational notes that save time

• Base currency: By default, base is USD. If you need a different base for your own math, either switch base where supported or keep USD base and use the inverse pair (USDPYG) directly.
• Timestamps and timezone: timestamp is Unix epoch seconds (UTC). Convert to local time for UX, but use UTC in logs for consistency.
• Unit conversions for metals: Metals are quoted per troy ounce. Always normalize inputs to troy ounces before pricing or hedging to avoid unit drift.
• Rounding: Apply rounding only at presentation. Retain full-precision rates internally to limit cumulative error in inventory valuation.
• Data governance: Persist the timestamp with each applied rate for reproducibility in financial reports and audits.

Using Convert for point conversions (optional)

If you prefer server-side conversion rather than multiplying by rates locally, the Convert endpoint can return a converted amount (e.g., 10,000 USD to PYG) along with the rate and timestamp. This is helpful when you want the API to encapsulate the math and return a single audited result. See request/response formats in the Documentation.

Smart integration ideas: digital transformation with PYG

Once you have PYG wired in, you can build smarter experiences without adding API calls:

• Client-side pricing: cache the last-good rates in memory or local storage and recompute USD⇄PYG conversions instantly while the UI renders, updating when a fresh snapshot arrives.
• Alerting: use Time-series to flag day-over-day PYG moves that meaningfully impact local-margin in PYG even if metal USD prices are flat.
• ERP/web store sync: precompute PYG per SKU nightly using a scheduled job; override in real time for big swings by refreshing the latest snapshot and adjusting pricing buffers.

Metals-API is built for embedding into trading dashboards, ERP price engines, and ecommerce price tags. Explore available endpoints and examples on metals-api.com, and consider the MCP options if you need managed support for production workloads.

Testing and validation checklist

• Log the full JSON payload, not just the rates, for traceability.
• Validate success is true and required fields exist before updating cached values.
• Handle 0 or undefined rates defensively; fall back to the last-good snapshot.
• Unit-test core math: usdToPyg(pygToUsd(x)) ≈ x within your decimal tolerance.
• Pin a precision policy (e.g., store amounts in integer guaraní; round at the edges of your system).

Security and keys

• Do not hardcode YOUR_API_KEY in public clients. Route requests through your backend or use secure serverless functions.
• Rate-limiting: implement backoff and circuit breakers. Cache to avoid redundant calls.
• Monitor for drift: add SLOs on update staleness (e.g., max age 15 minutes) and alert on misses.

Reference: find symbols and endpoints

Keep your integration tight by confirming available symbols and endpoint parameters:

• Browse endpoint parameters and response fields: Metals-API Documentation
• Review symbol codes for currencies and metals: Metals-API Supported Symbols
• Home: overview and product updates at metals-api.com

FAQ

Q: What’s the base currency in the Latest endpoint?
A: USD is the default base. With base=USD, rates.PYG is PYG per 1 USD. If you request the inverse synthetic symbol (USDPYG), you also get USD per 1 PYG in the same payload.

Q: How do I compute PYG per troy ounce of a metal?
A: If your input is USD per ounce, multiply by rates.PYG. If your input is ounces per USD (e.g., rates.XAU when base=USD), first compute USD per ounce as (1 / rates.XAU), then multiply by rates.PYG. Always keep unit conversions explicit.

Q: How often do rates update?
A: Update frequency depends on your subscription. Use timestamp from the payload to determine freshness, and cache snapshots to smooth usage. See the Documentation for details.

Q: Can I convert specific amounts server-side?
A: Yes. Use the Convert endpoint to get a converted amount plus the applied rate and timestamp. For bulk conversions, it’s more efficient to fetch Latest once and multiply locally.

Q: How should I handle weekends and holidays?
A: Expect the Latest endpoint to return the most recent published snapshot. Always rely on timestamp/date for display and staleness checks, not an assumption of market “open.”

Ready to wire PYG into your pricing and analytics? Get your API key and start integrating today: Register. For guidance on operating at scale or managed options, review the MCP page.