Real-Time Malappuram Gold 22k (MALA-22k) - Per Gram Price API — Node.js integration guide for 2026

Metals-API 10 min read
Real-Time Malappuram Gold 22k (MALA-22k) - Per Gram Price API — Node.js integration guide for 2026

You need to display the live per-gram price of 22-karat gold for a Malappuram-facing use case in a Node.js app, and you want the calculation to be reproducible, cached, and easy to extend into charts or alerts. By the end of this guide, you’ll fetch the latest XAU quote from Metals-API, convert USD/oz to USD/gram, apply 22k purity, and wire it into a clean Node.js function you can call from a route, worker, or pricing engine.

What “Malappuram 22k gold per gram” means in data terms

Metals-API provides prices for gold using the symbol XAU. Rates are quoted relative to a base currency (by default USD) and use the troy ounce as the unit of measure. “22k” reflects gold purity (22/24 = 0.9167), and “per gram” means we must convert from troy ounces to grams (1 troy ounce = 31.1034768 grams).

Illustration: Real-Time Malappuram Gold 22k (MALA-22k) - Per Gram Price API — Node.js integration guide for 2026
  • Core metal symbol: XAU (gold)
  • Base currency: USD by default
  • Unit in the API: troy ounce
  • Desired unit: grams
  • Desired purity: 22k (91.6667% of 24k)

Region-specific adjustments (e.g., Malappuram retail premiums, GST, making charges) are not part of the raw XAU market rate. You typically apply them after deriving the base 22k per-gram price from XAU.

Endpoint choice and minimal data you actually need

For real-time display, you only need the Latest Rates endpoint. It returns both XAU (troy ounces per 1 USD) and USDXAU (USD per troy ounce) when requested. You’ll use USDXAU directly to avoid doing an inversion in your app. If you later build spark-lines or day-over-day moves, add a historical or time-series call; for this guide we’ll keep it to Latest only to reduce moving parts and request volume.

  • Latest Rates: one call to get XAU and USDXAU
  • Optional (later): Time-Series or OHLC for charts/analytics

See the full parameter set in the Metals-API Documentation, and confirm symbols in Metals-API Supported Symbols. If you map retail SKUs to market symbols, keep that mapping explicit in code (e.g., “MALA-22k” -> use XAU, purity 22/24, gram unit).

One cURL you can paste to verify your setup

Request the latest gold price with both XAU and USDXAU included. Replace YOUR_API_KEY with your key from Metals-API.

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

Official sample JSON (use these fields exactly as shown):

{"success":true,"timestamp":1794881220,"date":"2026-11-17","base":"USD","rates":{"XAU":0.00025874560132478,"USD":1,"USDXAU":3864.799999999962}}

Fields you’ll actually use

  • timestamp: Unix epoch seconds (UTC). Useful for cache and staleness checks.
  • date: ISO date of the rates (UTC).
  • base: The currency all rates are relative to (USD here).
  • rates.XAU: troy ounces of gold per 1 USD (oz/USD). You can invert it to get USD/oz if USDXAU is not provided.
  • rates.USDXAU: USD per troy ounce (USD/oz). Use this directly to compute per gram and 22k values.

Node.js: derive 22k per-gram price from XAU (USD/oz → USD/g → 22k)

This example uses Node 18+ fetch (or add node-fetch/undici if on an older LTS). It:

  1. Calls the Latest endpoint for XAU and USDXAU.
  2. Derives 24k per-gram price from USDXAU.
  3. Applies 22k purity (22/24).
  4. Shows where to add regional premiums/taxes if you need Malappuram retail numbers.
import assert from "node:assert";

const API_URL = "https://metals-api.com/api/latest";
const API_KEY = process.env.METALS_API_KEY || "YOUR_API_KEY";

// Constants
const TROY_OUNCE_TO_GRAM = 31.1034768;  // exact conversion for precious metals
const PURITY_22K = 22 / 24;             // 0.916666...

/**
 * Fetches the latest USDXAU and returns a breakdown:
 * - usdPerOunce24k
 * - usdPerGram24k
 * - usdPerGram22k
 * - timestamp (UTC, seconds)
 * - isoDate (UTC)
 */
async function getGold22kPerGramUSD() {
  const url = new URL(API_URL);
  url.searchParams.set("access_key", API_KEY);
  // Ask explicitly for both XAU and USDXAU so we can skip inverting when USDXAU is returned.
  url.searchParams.set("symbols", "XAU,USDXAU,USD");

  const res = await fetch(url.toString(), { timeout: 15000 });
  if (!res.ok) {
    throw new Error(`HTTP ${res.status} from Metals-API`);
  }
  const data = await res.json();

  // Structure checks
  assert(data && data.success === true, "API did not return success=true");
  assert(data.base === "USD", "This example assumes USD base");
  assert(data.rates && (data.rates.USDXAU || data.rates.XAU), "Missing XAU or USDXAU");

  // Prefer direct USDXAU if present; otherwise invert XAU (oz per USD) to USD per oz.
  const usdPerOunce24k = data.rates.USDXAU
    ? Number(data.rates.USDXAU)
    : 1 / Number(data.rates.XAU);

  const usdPerGram24k = usdPerOunce24k / TROY_OUNCE_TO_GRAM;
  const usdPerGram22k = usdPerGram24k * PURITY_22K;

  return {
    usdPerOunce24k,
    usdPerGram24k,
    usdPerGram22k,
    timestamp: Number(data.timestamp),  // seconds since epoch (UTC)
    isoDate: data.date
  };
}

// Example usage: compute and log, then add your Malappuram adjustments downstream.
getGold22kPerGramUSD()
  .then((r) => {
    console.log("24k USD/oz:", r.usdPerOunce24k.toFixed(6));
    console.log("24k USD/g :", r.usdPerGram24k.toFixed(6));
    console.log("22k USD/g :", r.usdPerGram22k.toFixed(6));

    // Optional: Apply region-specific adjustments downstream
    // const regionPremiumPct = 0.0125;  // example 1.25% shop premium (outside the API)
    // const gstPct = 0.03;             // example 3% tax (outside the API)
    // const mala22kUsdPerGramRetail = r.usdPerGram22k * (1 + regionPremiumPct) * (1 + gstPct);
    // console.log("MALA-22k USD/g (retail est.):", mala22kUsdPerGramRetail.toFixed(6));
  })
  .catch((err) => {
    console.error("Failed to get gold price:", err);
  });

Unit conversion and purity math (why your numbers are right)

  • USDXAU is already USD per troy ounce. If you didn’t get USDXAU, invert XAU: USDXAU = 1 / XAU.
  • USD per gram (24k) = USDXAU / 31.1034768
  • USD per gram (22k) = USD per gram (24k) × (22 ÷ 24)

Keep conversions in double precision and only round at the very end (e.g., at UI display). This avoids compounding rounding error across transformations (oz → g → 22k → tax/premium).

Caching, timestamps, and update cadence

  • Timestamp: The API’s timestamp value is Unix seconds (UTC). Compare it to your system time to detect staleness.
  • Update frequency: Latest rates are updated on a schedule tied to your plan. Align your polling (or background refresh job) with that cadence instead of hammering the endpoint.
  • Cache layer: Put a small TTL cache in front of your app (e.g., memory/Redis) equal to the upstream update interval to avoid duplicate requests across concurrent users.
  • Weekend/holidays: Precious metals trade nearly 24x5. On weekends/holidays you may see the last available close carry forward until the next market session opens. Surface the date/timestamp near the quote for user clarity.

Tying a regional product code (MALA-22k) to XAU

There isn’t a dedicated symbol for “Malappuram 22k” on the exchange. The typical approach is to define a mapping layer in your app:

  • Symbol used for pricing: XAU
  • Purity rule: 22/24
  • Unit rule: troy ounce → grams
  • Region adjustments: percentage premium/discount; fixed making fees; tax rule

That means any SKU like “MALA-22k” first resolves to the market symbol XAU for 24k spot and then applies your business logic to reach a local retail number. Keep this logic deterministic and versioned, and store both the raw feed (USDXAU) and the transformed result you showed to the customer for auditability.

How to turn the raw rate into a storefront or trader-facing view

While the example returned values in USD, many storefronts show INR. If you also need INR, combine the XAU rate with a USD→INR FX rate (by using the API’s currency rates if available on your plan). Then compute INR per gram with the same gram and purity math. Keep FX conversion and metal conversion steps explicit so you can test them individually.

Explore more options and symbols at the Supported Symbols page. For endpoint parameters and optional fields (including other output units, additional symbols, or streaming), refer to the API Documentation.

Accuracy, rounding and display

  • Prefer storing internal numbers as floats in base units (USD/oz for XAU). Derive USD/g and 22k on read.
  • Round only when displaying. For retail displays, 2–3 decimals per gram is common; analysts may keep 6+ decimals.
  • Document the purity factor, unit conversion, and premiums used. Save them alongside the final price for reproducibility.

Practical guardrails a beginner might miss

  • Base currency: Defaults to USD. If you change base, re-check math assumptions in your code (e.g., do not assume USDXAU exists if base ≠ USD).
  • Symbol presence: Always feature-detect fields. This guide prefers USDXAU if present, falls back to 1/XAU if not.
  • Error handling: Treat non-200s, success=false, or missing fields as hard errors. Do not silently reuse expired cache without warning signals.
  • Timezones: The date field is UTC. If you display “local date” in India Standard Time (IST), label it clearly.
  • Pre-trade vs retail: Spot is not retail. Maintain a clear separation between feed price and retail add-ons (making charges, GST, logistics, hedging spread).
  • Versioning: If you tweak purity factors or premium rules, version them so historical orders can be reconciled against what the customer saw.

Formulas at a glance

Item Formula Notes
USD per ounce (24k) USDXAU (direct) OR 1 / XAU Prefer USDXAU if provided.
USD per gram (24k) USD per ounce / 31.1034768 1 troy ounce = 31.1034768 grams.
USD per gram (22k) USD per gram (24k) × (22/24) PURITY_22K = 0.916666…

Extending this into charts, alerts and ERP syncs

If you plan charts or anomaly detection, add a background process that periodically writes the latest USDXAU into a timeseries store (e.g., Postgres with time buckets). Because the Latest endpoint is sufficient for most retail displays, you can avoid calling historical endpoints on hot paths; use them off-peak for backfills or analytics jobs.

When you introduce alerts (e.g., “notify if MALA-22k per gram moves by 1% in 15 min”), compute the 22k-per-gram series from cached USDXAU snapshots and compare the last N points. This keeps your alerting compute local and predictable.

Security, keys, and plan notes

  • Keep your access key in server-side env vars (never in front-end code).
  • Throttle calls according to your plan. Cache results at least until the next expected update window.
  • No free trial is offered. If you only need copper, note that Copper Monthly is $19.99/mo; for gold/XAU choose a plan that includes it.
  • To request market coverage or manage your plan, visit MCP.

Why XAU still anchors digital gold workflows

Gold’s spot price (XAU) remains the anchor for digital price discovery across trading tools, e-commerce, and ERP pipelines. By standardizing on troy-ounce quotes and an explicit purity factor, you can express local SKUs (like Malappuram 22k ornaments) as deterministic functions of a single, auditable market feed. That unlocks consistent discounting, hedging, and analytics without guesswork.

Troubleshooting common integration issues

  • Values look inverted: If your “per gram” number is suspiciously small, confirm you didn’t treat XAU (oz per USD) as USD per oz. Prefer USDXAU if available.
  • Decimals jump on refresh: Round at display time only. Keep internal math in floats with no premature rounding.
  • Weekend mismatches with competitors: Last official close may persist during off-hours. Display the UTC timestamp to explain staleness.
  • Unexpected symbol errors: Validate that your symbol list matches the current catalog at the Symbols page.

Next steps

FAQ

How do I convert from USD/oz to INR/gram for 22k?
First compute USD/gram (24k) from USDXAU/31.1034768, then multiply by 22/24. Convert the result using your USD→INR rate. Keep FX and metal conversions explicit and testable.

What if the Latest response doesn’t include USDXAU?
Use XAU (oz per USD) and invert it: USDXAU = 1 / XAU. The rest of the math is unchanged.

How often should I poll?
Match your plan’s update cadence (e.g., minutes-level). Cache responses for at least that long and stamp UI with the UTC timestamp from the payload.

Can I get bid/ask for tighter retail spreads?
Yes, there is a Bid/Ask endpoint. Use the bid or ask as appropriate for your quoting logic. See the Documentation for endpoint details.

Is there a specific symbol for “MALA-22k”?
No. Use XAU as the market symbol and apply the 22k purity and your Malappuram-specific add-ons in your application’s pricing layer.

Ready to ship your Node.js integration? Get your key at Metals-API Register, check available symbols at Symbols, and wire the Latest endpoint into your workflow using the steps above.