Getting started with Patna Silver (PATN-XAG) - Per Gram Price API in Multiple Currencies

You need to quote and monitor Patna Silver (PATN-XAG) per gram in multiple currencies for pricing, hedging, or reporting. By the end of this guide, you will be able to: a) correctly request live and historical Silver (XAG) prices from Metals-API, b) convert per–troy-ounce prices to per-gram, c) understand the restriction on the PATN-XAG symbol and how to handle it, and d) return consistent prices in multiple currencies with caching and weekend logic that won’t surprise your users.

What PATN-XAG is and why you hit a restriction

PATN-XAG represents a city-specific price reference for silver in Patna, India. Metals-API treats Indian city symbols differently from global metal symbols like XAG (silver, globally). If you try to fetch PATN-XAG via the general latest endpoint, you’ll receive a restricted-symbols error. This is intentional: Indian city symbols belong to a separate, specialized endpoint.

Here is the exact response you’ll see if you try to request PATN-XAG via the /latest endpoint:

{"success":false,"error":{"code":403,"type":"restricted_symbols","info":"The specified symbols are restricted to the gold-price-india endpoint only.","restricted_symbols":["PATN-XAG"],"endpoint_required":"\/api\/gold-price-india","message":"Indian gold city symbols can only be used with the \/api\/gold-price-india endpoint."}}

What this means for your integration:

• If your use case strictly requires the Patna city quotation (PATN-XAG), consult the endpoint indicated by the error envelope inside the Metals-API Documentation. Do not call PATN-XAG from /latest, /timeseries, or /convert—those will remain restricted for this symbol.
• If you can operate with the global silver benchmark (XAG), you can call /latest and /timeseries for XAG and derive per-gram and multi-currency outputs reliably. This is how most trading tools, pricing engines, and dashboards are architected when they don’t require city-level quotes.

Plan the data flow for per-gram and multi-currency output

When you query the Metals-API /latest endpoint for XAG, you will receive a rate quoted per troy ounce (default) and relative to USD (base = USD). To obtain per-gram pricing in USD, invert or scale as follows:

• Metals-API default: rates.XAG = ounces of XAG per 1 USD (oz/USD).
• USD per ounce (USD/oz) = 1 / rates.XAG.
• USD per gram = (USD/oz) / 31.1034768.

To emit per gram in another currency (e.g., INR, EUR), add a currency conversion step on the USD-per-gram value using supported fiat symbols. You can explore available fiat symbols via the Metals-API Supported Symbols page, then consult the Documentation for how to convert currencies with the Convert endpoint.

Curl: Get latest global silver (XAG), then derive per gram

Below is a minimal request for the latest rates including only XAG. This is the building block for per-gram calculations.

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

A representative JSON envelope (illustrative values) looks like:

{
"success": true,
"timestamp": 1790727031,
"base": "USD",
"date": "2026-09-30",
"rates": {
"XAG": 0.03815
},
"unit": "per troy ounce"
}

Fields you’ll use:

• timestamp and date: Use for caching, audit, and display. Time is effectively UTC.
• base: USD. The rate in rates.XAG is quoted per 1 USD.
• rates.XAG: ounces per USD. You will invert to USD per ounce, then scale to per gram.
• unit: per troy ounce (1 troy oz = 31.1034768 grams).

Compute per gram and multi-currency output in Python

The following Python example fetches XAG from /latest, computes USD per gram, and shows where you’d apply a currency conversion for other currencies. Replace YOUR_API_KEY with your key from the Register flow.

import requests

API_KEY = "YOUR_API_KEY"
LATEST_URL = "https://metals-api.com/api/latest"

TROY_OUNCE_TO_GRAM = 31.1034768

def get_usd_per_gram_xag():
params = {
"access_key": API_KEY,
"symbols": "XAG"
}
r = requests.get(LATEST_URL, params=params, timeout=10)
data = r.json()
if not data.get("success"):
raise RuntimeError(f"API error: {data}")
rate_oz_per_usd = data["rates"]["XAG"] # oz/USD
usd_per_oz = 1.0 / rate_oz_per_usd # USD/oz
usd_per_gram = usd_per_oz / TROY_OUNCE_TO_GRAM
return {
"timestamp": data["timestamp"],
"date": data["date"],
"usd_per_gram": usd_per_gram,
"unit": "USD per gram"
}

quote = get_usd_per_gram_xag()
print(quote)

# If you need per-gram in other currencies (e.g., INR, EUR),
# convert quote["usd_per_gram"] using a currency conversion step
# supported by Metals-API's convert endpoint and fiat symbols.

Typical output structure (values illustrative):

{
"timestamp": 1790727031,
"date": "2026-09-30",
"usd_per_gram": 0.84,
"unit": "USD per gram"
}

In production, round to your quoting convention (e.g., 4–6 decimals), and cache results for your polling interval to reduce request volume.

Using the Convert endpoint to support multiple currencies

Once you have USD per gram, you can convert to other currencies using the convert endpoint. The convert endpoint can convert any amount from one currency to another or between metals and currencies. Below is a minimal example converting 1 USD to XAG (illustrative values). You can similarly convert 1 USD to INR (or another fiat symbol) if that symbol is supported—see the Symbols page for eligible fiat codes.

curl "https://metals-api.com/api/convert?access_key=YOUR_API_KEY&from=USD&to=XAG&amount=1"

Illustrative response:

{
"success": true,
"query": {
"from": "USD",
"to": "XAG",
"amount": 1
},
"info": {
"timestamp": 1790727031,
"rate": 0.03815
},
"result": 0.03815,
"unit": "troy ounces"
}

How to use it for per-gram in other currencies:

• Obtain the USD per gram for XAG as shown earlier.
• Convert 1 USD to your target currency with the convert endpoint (if supported), or request the needed currency rate from the API.
• Multiply the USD-per-gram by the USD-to-Target-Currency rate to get TargetCurrency per gram.

For the full set of parameters and examples across fiat and metals, refer to the Documentation.

City symbol restriction: working with PATN-XAG specifically

If you must show a Patna-specific silver price (PATN-XAG), use the specialized endpoint referenced in the error envelope. Do not attempt PATN-XAG on /latest, /timeseries, /convert, or bid/ask—it will remain restricted. The restriction response you saw is:

{"success":false,"error":{"code":403,"type":"restricted_symbols","info":"The specified symbols are restricted to the gold-price-india endpoint only.","restricted_symbols":["PATN-XAG"],"endpoint_required":"\/api\/gold-price-india","message":"Indian gold city symbols can only be used with the \/api\/gold-price-india endpoint."}}

Action items:

• Check the Documentation for the Indian city pricing endpoint and parameters.
• Validate if the city endpoint returns ounce-based or gram-based units, then apply the same ounce-to-gram scaling if needed.
• If you quote in multiple currencies, keep the currency conversion step downstream using supported fiat symbols.

Backfilling and trendlines: time-series XAG for Patna-adjacent logic

When you cannot access historical PATN-XAG through the city endpoint or do not need the city basis historically, many teams use the global XAG time series for analytics and overlay a local basis adjustment separately. Here’s an example retrieving daily XAG from the /timeseries endpoint (illustrative values):

curl "https://metals-api.com/api/timeseries?access_key=YOUR_API_KEY&start_date=2026-09-23&end_date=2026-09-30&symbols=XAG"

{
"success": true,
"timeseries": true,
"start_date": "2026-09-23",
"end_date": "2026-09-30",
"base": "USD",
"rates": {
"2026-09-23": {
"XAG": 0.03825
},
"2026-09-25": {
"XAG": 0.0382
},
"2026-09-30": {
"XAG": 0.03815
}
},
"unit": "per troy ounce"
}

Use cases this enables:

• Building rolling-volatility or momentum measures for XAG.
• Training a model for procurement cost forecasting, then layering city-basis logic for Patna.
• Pre-populating charts before users pick a specific city basis.

Checking bid/ask for tighter quoting logic

If your subscription includes bid/ask, you can obtain spread-aware pricing for XAG. This is useful when you need to decide whether to show mid, bid, ask, or cost-plus for a cart or RFQ. Example (illustrative values):

curl "https://metals-api.com/api/bid-ask?access_key=YOUR_API_KEY&symbols=XAG"

{
"success": true,
"timestamp": 1790727031,
"base": "USD",
"date": "2026-09-30",
"rates": {
"XAG": {
"bid": 0.0381,
"ask": 0.0382,
"spread": 0.0001
}
},
"unit": "per troy ounce"
}

Convert to per gram the same way, choosing which side or mid to use:

• mid oz/USD = (bid + ask) / 2
• USD/oz = 1 / (mid oz/USD)
• USD/gram = (USD/oz) / 31.1034768

Endpoints recap and when to use them

• Latest: Quick snapshot of global XAG for per-gram and multi-currency flows; cache and refresh on your plan’s interval.
• Time-series: Backfill and compute analytics across days for XAG, then transform to per-gram as needed.
• Convert: Convert currency amounts or metals to currencies. Use this to translate USD per gram into your target fiat currency.
• Indian city endpoint: Required for PATN-XAG. Use it only for that symbol per the restriction response. Implementation details are in the Documentation.

Units, base currency, inversion, and precision

Key details that save time during implementation:

• Units: The metals unit is “per troy ounce” in the API responses shown. Always convert to grams using 31.1034768 grams per troy ounce.
• Base currency: Responses are by default relative to USD (base = USD). The field rates.XAG is in oz per USD. To obtain USD per oz, invert (1 / rates.XAG).
• Per gram price: USD/gram = (1 / rates.XAG) / 31.1034768. For other currencies, multiply your USD/gram by the USD→TargetCurrency conversion rate you fetch via Metals-API convert/currency support.
• Timestamps and timezone: timestamp is seconds since epoch; date is UTC day. Use these for caching, chart labeling, and compliance logs.
• Precision: Quant teams typically carry 6–8 decimal places internally for rates, then round on display (e.g., 4 decimals for per-gram retail quotes).

Caching, update intervals, and weekend logic

To keep response times low and respect plan limits, implement request consolidation and caching:

• Cache the /latest XAG response for at least the refresh cadence allowed by your plan (e.g., 60-minute or 10-minute intervals as applicable). Store both timestamp and the computed USD/gram to avoid recomputation on every request.
• Batch updates: If you price many SKUs in the same currency at once, fetch XAG once, then fan out the computed per-gram value across items in memory.
• Non-trading days: Metals quotes can be steady or unchanged over weekends and holidays. Your UI should gracefully show the latest available date and avoid implying an intraday move when the market is closed.
• Fallback: If an update fails, continue serving the last known good quote with a banner like “Last updated YYYY-MM-DD HH:MM UTC” until the next retry window.

Silver in manufacturing and digital operations: why per gram matters

Silver (XAG) is a core input for electronics, solar, medical devices, and precision components. In many BOMs, billable quantities are tracked in grams, not ounces. Developers integrating Metals-API into ERP, MES, or smart manufacturing systems typically:

• Normalize to per-gram to align with material consumption metrics (grams per unit, grams per batch).
• Convert into the local buying currency for budgeting and PO approvals.
• Run time-series analytics to model consumption cost under different hedging schedules, then use city-basis adjustments only when specific procurement sources require it (e.g., PATN-XAG).

Because industrial workflows tend to be event-driven (shift start, batch open/close), implementing a simple cache invalidation policy tied to shift boundaries can reduce API traffic without losing fidelity.

Add OHLC or fluctuation if your workflow needs a “move”

If your product highlights daily movement or triggers alerts, use OHLC or fluctuation endpoints for XAG. Here is an OHLC example (illustrative values) focusing solely on XAG:

curl "https://metals-api.com/api/open-high-low-close/2026-09-30?access_key=YOUR_API_KEY&symbols=XAG"

{
"success": true,
"timestamp": 1790727031,
"base": "USD",
"date": "2026-09-30",
"rates": {
"XAG": {
"open": 0.03825,
"high": 0.0383,
"low": 0.0381,
"close": 0.03815
}
},
"unit": "per troy ounce"
}

For each OHLC field, apply the same inversion and gram scaling when you need USD/gram open, high, low, close. You can then display per-gram candles or compute a daily range in grams for internal alerts.

Full example: Putting it together end-to-end

This example demonstrates a pragmatic flow to deliver per-gram and multi-currency outputs for XAG, with a guard for PATN-XAG attempts.

# 1) Try to fetch the city symbol (PATN-XAG) - expect restriction if you call /latest
curl "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=PATN-XAG"

# Response (real, from a live call that did not succeed):
# {"success":false,"error":{"code":403,"type":"restricted_symbols","info":"The specified symbols are restricted to the gold-price-india endpoint only.","restricted_symbols":["PATN-XAG"],"endpoint_required":"\/api\/gold-price-india","message":"Indian gold city symbols can only be used with the \/api\/gold-price-india endpoint."}}

# 2) Fallback to global XAG for per-gram baseline
curl "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=XAG"

# 3) (Optional) Get a short time-series for charting
curl "https://metals-api.com/api/timeseries?access_key=YOUR_API_KEY&start_date=2026-09-23&end_date=2026-09-30&symbols=XAG"

# 4) Convert USD to a target fiat for multi-currency per-gram output (replace TO with a supported fiat code)
curl "https://metals-api.com/api/convert?access_key=YOUR_API_KEY&from=USD&to=TO&amount=1"

Precision, rounding, and display rules for per-gram

Decide how to present small per-gram values without confusing rounding artifacts:

• Internal math: carry at least 6–8 decimals.
• Retail display: 3–4 decimals often balances readability and accuracy. For wholesale or B2B RFQs, 4–6 decimals may be expected.
• Always state unit as “per gram” and currency code (e.g., INR/gram) in UI and exports.

Verifying symbol availability and capabilities

Before deploying, confirm symbol support and any special handling:

• Check XAG and relevant fiat codes on the Symbols page.
• Review endpoint specifics (latest, timeseries, convert, city-specific) in the Documentation.
• If you need managed connectivity, historical depth, or compliance controls, explore MCP.

JSON examples you can build on

To summarize, here are four focused JSON envelopes you can copy to wire up your data parsing. The first is the real restriction response for PATN-XAG, the others are illustrative XAG-focused responses.

PATN-XAG restriction (real)

{"success":false,"error":{"code":403,"type":"restricted_symbols","info":"The specified symbols are restricted to the gold-price-india endpoint only.","restricted_symbols":["PATN-XAG"],"endpoint_required":"\/api\/gold-price-india","message":"Indian gold city symbols can only be used with the \/api\/gold-price-india endpoint."}}

Latest for XAG (illustrative values)

{
"success": true,
"timestamp": 1790727031,
"base": "USD",
"date": "2026-09-30",
"rates": {
"XAG": 0.03815
},
"unit": "per troy ounce"
}

Time-series for XAG (illustrative values)

{
"success": true,
"timeseries": true,
"start_date": "2026-09-23",
"end_date": "2026-09-30",
"base": "USD",
"rates": {
"2026-09-23": { "XAG": 0.03825 },
"2026-09-25": { "XAG": 0.0382 },
"2026-09-30": { "XAG": 0.03815 }
},
"unit": "per troy ounce"
}

Convert USD→XAG (illustrative values)

{
"success": true,
"query": {
"from": "USD",
"to": "XAG",
"amount": 1
},
"info": {
"timestamp": 1790727031,
"rate": 0.03815
},
"result": 0.03815,
"unit": "troy ounces"
}

Practical production tips

• Throttle and batch: Align polling frequency with your plan’s update interval. Batch downstream consumers against a single cached quote to avoid redundant calls.
• Graceful degradation: Preserve last-known-good plus timestamp on transient failures. Annotate UI with “as of” times in UTC.
• Per-gram normalization: Centralize ounce→gram conversion in one module. Unit tests should assert gram results for a set of known ounce prices.
• FX separation: Keep metal price acquisition and FX conversion decoupled. This lets you memoize each independently and swap target currencies without refetching metals.
• Compliance logging: Store the original JSON envelope plus your computed values and timestamp. This aids audits for pricing disputes.

Silver in advanced manufacturing and digital supply chains

For smart factories and digital supply chains, silver’s role spans conductive pastes, solder alloys, and high-reliability contacts. Per-gram normalization enables:

• Dynamic BOM repricing in MES/ERP systems where work orders reserve precise gram quantities.
• Shift-based hedging signals combining time-series XAG and internal demand forecasts.
• Supplier negotiations informed by spread-aware per-gram mid prices and city-basis adjustments (e.g., PATN-XAG) when applicable.

When modeling costs, consider pairing per-gram XAG with intraday OHLC to reflect operational purchase windows. For analytics-heavy workflows, archive the time-series responses to maintain continuity even if an upstream endpoint rate-limits during peak load.

FAQ

Q1: Why does my PATN-XAG request to /latest fail?
Because PATN-XAG is restricted to a specialized Indian city pricing endpoint. The API returns a 403 with the endpoint you must use. Implement that endpoint for PATN-XAG and do not call /latest or /timeseries for it.

Q2: How do I get per-gram prices when the API returns per troy ounce?
Invert the oz/USD rate to USD/oz, then divide by 31.1034768 to get USD/gram. Apply fiat conversion afterward if you need another currency.

Q3: Can I show multiple currencies without extra metals calls?
Yes. Cache one /latest XAG quote, compute USD/gram once, then apply one or more currency conversions for each target currency using supported fiat symbols. This minimizes metals endpoint requests.

Q4: How should I handle weekends and holidays?
Expect fewer or unchanged updates. Display the last available date/time in UTC and avoid implying intraday movement when markets are closed. Keep a cached last-known-good and retry on your next interval.

Q5: What if I also need bid/ask spreads?
Use the bid/ask endpoint for XAG if your plan allows it, then convert the chosen side (bid, ask, or mid) to per-gram as described. This is essential for tight RFQ or cart pricing.

Ready to ship? Create your API key and start returning Patna-linked or global silver per-gram prices in minutes. Register, review the Documentation for the city endpoint and core metals endpoints, verify symbols on Symbols, and explore managed connectivity via MCP.