Cómo goldprice.dev calcula el precio del oro en monedas locales

goldprice.dev y exchangerate.dev son productos hermanos operados por la misma empresa. En producción, goldprice.dev es responsable del contrato de precio del metal, mientras que exchangerate.dev suministra el componente de FX para las monedas flotantes admitidas. El límite importa: un precio local del oro contiene dos observaciones de mercado, y que un componente esté fresco no hace que el otro también lo esté.

El límite de producción

goldprice.dev parte de una observación del metal en USD. exchangerate.dev provee la observación de FX correspondiente de USD a la moneda local para las monedas flotantes admitidas. goldprice.dev es entonces responsable del contrato de conversión específico del metal, incluyendo unidades, símbolos admitidos, validación y la respuesta final.

Se trata de una integración entre productos hermanos declarada explícitamente, no un aval independiente de un cliente. Su valor como caso de estudio es operativo: la API de FX suministra un componente de datos real en producción, y el producto consumidor conserva la responsabilidad de su propio dominio.

La fórmula de conversión

El oro suele cotizarse en USD por onza troy. Una visualización local normalmente necesita un monto en moneda por gramo. Convierte primero el peso y luego aplica el tipo de cambio en USD:

const GRAMS_PER_TROY_OZ = 31.1035;

function localGoldPerGram(usdPerTroyOz, usdToLocalRate) {
  return (usdPerTroyOz / GRAMS_PER_TROY_OZ) * usdToLocalRate;
}

La constante de peso es fija. Las dos entradas de mercado no lo son: tanto la cotización del oro como el tipo de cambio tienen su propio momento de observación y sus propias reglas de frescura.

La ruta de producción de una sola llamada

Para quien la consume, el límite de producción es goldprice.dev `/v1/convert`. Combina los componentes de metal y de FX detrás de un único endpoint consciente del metal, y no requiere clave de API. Este ejemplo solicita el valor de un gramo de oro en rupias indonesias:

const params = new URLSearchParams({
  from: "XAU",
  to: "IDR",
  amount: "1",
  unit: "gram",
});

const response = await fetch(
  `https://api.goldprice.dev/v1/convert?${params}`,
);

if (!response.ok) {
  throw new Error(`goldprice.dev returned ${response.status}`);
}

const conversion = await response.json();
console.log(conversion.result, conversion.to, conversion.timestamp);

Esta ruta mantiene pequeño el contrato para quien la consume: una solicitud, un monto, una unidad de metal y una moneda de destino. Su único timestamp no evidencia de forma independiente ambos componentes de mercado, así que los consumidores que necesiten auditar la frescura del FX deben usar la ruta de dos componentes que se muestra a continuación.

La integración auditable de dos componentes

Consulta ambas API cuando necesites conservar cada timestamp de origen, cachear las entradas de forma independiente o explicar cuál componente está desactualizado. goldprice.dev spot suministra el oro en USD por onza troy; exchangerate.dev suministra el tipo de cambio de USD a la moneda local.

const GRAMS_PER_TROY_OZ = 31.1035;

async function getGoldInCurrencies(currencies) {
  const symbols = currencies.join(",");
  const [spotResponse, fxResponse] = await Promise.all([
    fetch("https://api.goldprice.dev/v1/spot/XAU-USD-SPOT"),
    fetch(`https://api.exchangerate.dev/v1/latest/USD?symbols=${symbols}`),
  ]);

  if (!spotResponse.ok || !fxResponse.ok) {
    throw new Error("A market-data request failed");
  }

  const spot = await spotResponse.json();
  const fx = await fxResponse.json();
  const usdPerGram = Number(spot.price) / GRAMS_PER_TROY_OZ;

  return {
    goldComputedAt: spot.computed_at,
    fxDataUpdatedAt: fx.data_updated_at,
    fxResponseTimestamp: fx.timestamp,
    fxSource: fx.source,
    fxMarketSession: fx.market_session,
    prices: Object.fromEntries(
      currencies.map((currency) => [
        currency,
        usdPerGram * Number(fx.rates[currency]),
      ]),
    ),
  };
}

const result = await getGoldInCurrencies(["EUR", "IDR", "JPY"]);

Por qué los servicios permanecen separados

La integración no convierte a exchangerate.dev en el motor completo de precios del oro. Sigue siendo la capa de FX. Mantener ese límite explícito evita que la frescura de la moneda, la frescura del metal y las reglas de conversión específicas del producto colapsen en un único valor ambiguo.

• goldprice.dev puede exponer una interfaz pequeña y específica del metal sin obligar a quien la consume a ensamblar la ruta común por sí mismo.
• exchangerate.dev mantiene un contrato de FX general que resulta útil fuera del dominio de los metales.
• Los consumidores sensibles a la auditoría pueden obtener y almacenar ambas observaciones de forma independiente.
• Cada servicio puede reportar fallos y frescura usando el vocabulario de sus propios datos de mercado.

Maneja explícitamente los componentes desactualizados o faltantes

Un precio combinado no debe sobrevivir si alguna de las entradas falta, es cero, no es numérica o está fuera de la ventana de frescura aceptada por tu producto. Conserva el último valor válido solo si la interfaz lo etiqueta con sus tiempos de observación originales.

• Verifica ambas respuestas HTTP antes de hacer la aritmética.
• Rechaza precios y tasas no finitos o no positivos.
• Define umbrales de frescura separados para el oro y el FX.
• Trata market_session: weekend como contexto, no como prueba de que una tasa arrastrada esté vigente.
• Registra el par de monedas y ambos tiempos de observación subyacentes junto con los errores de conversión.

Redondea para mostrar, no durante el cálculo

Conserva la precisión completa a lo largo de la multiplicación y deja que la configuración regional de visualización decida el número final de decimales. Intl.NumberFormat maneja los símbolos de moneda y la agrupación sin cambiar el valor subyacente:

function formatPrice(amount, currency, locale) {
  return new Intl.NumberFormat(locale, {
    style: "currency",
    currency,
  }).format(amount);
}

console.log(formatPrice(result.prices.IDR, "IDR", "id-ID"));
console.log(formatPrice(result.prices.JPY, "JPY", "ja-JP"));

Usa el resultado como un valor indicativo

Un valor de mercado calculado no es el precio minorista de una moneda o una barra. Las primas de distribuidor, los impuestos, la fabricación, las comisiones de pago y los spreads de FX ejecutables quedan fuera de esta fórmula. Etiqueta el resultado como indicativo, a menos que tu aplicación agregue una cotización real de un distribuidor y sus condiciones comerciales.

Qué demuestra este caso de estudio

goldprice.dev es evidencia de primera parte de que exchangerate.dev puede suministrar el componente de FX de un flujo de precios en producción. No es una prueba social independiente. La prueba útil es más acotada y reproducible: los desarrolladores pueden llamar a los mismos productos públicos, conservar ambos tiempos de observación y verificar la aritmética por sí mismos.