Formatos de datos y unidades

Dos direcciones para cada cotización

Para cada símbolo que solicitas, rates contiene dos números. Para el oro (XAU) con base USD:

• USDXAU: el precio de una onza troy de oro en dólares estadounidenses, como 3997.89. Es el número que debes mostrar a las personas.
• XAU: el inverso, las onzas troy de oro por cada dólar estadounidense, como 0.0002501319446. Este formato se mantiene por compatibilidad con las API de estilo forex.

Las divisas siguen la misma regla. Con base USD, USDEUR es el precio de un euro en dólares y EUR es la cantidad de euros por dólar.

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "EUR": 0.8589589418,
    "USDEUR": 1.1642
  }
}

Elegir una divisa base

base establece la divisa de todos los precios de la respuesta. Por defecto es USD y acepta cualquier símbolo admitido: EUR, GBP, JPY, o incluso BTC o XAU si quieres valorar las cosas en bitcoin o en oro. Las cotizaciones cruzadas se calculan a partir de la misma instantánea, así que siempre son coherentes entre sí.

Esta solicitud devuelve EURXAU, el precio del oro en euros por onza troy:

GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR&currencies=XAU,XAG

Unidades de masa

Los precios de los metales son por onza troy (31,1035 g), salvo que indiques unit. Valores admitidos:

• troy_oz (por defecto), gram, kilogram, ounce (avoirdupois, 28,35 g), pound, metric_ton y short_ton

También se aceptan formas abreviadas como g, kg, lb y tonne. Ten en cuenta que oz significa la onza avoirdupois. Usa troy_oz, o no indiques unit, para obtener la onza troy, que es la unidad en la que se cotizan los lingotes.

unit solo se aplica a los metales preciosos e industriales. La energía se sigue cotizando por barril, MMBtu o galón, y las divisas y las criptomonedas no se ven afectadas. Cuando se usa una unidad distinta de la predeterminada, la respuesta incluye un campo unit. Para GET /api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram:

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "EUR",
  "unit": "gram",
  "rates": {
    "XAU": 0.009057444725,
    "EURXAU": 110.4064149,
    "XAG": 0.6713138244,
    "EURXAG": 1.489616277
  }
}

Metales industriales y energía

Los metales industriales (XCU cobre, ALU aluminio, ZNC zinc y HRC bobina de acero laminada en caliente) se cotizan por defecto por onza troy, como cualquier otro metal, de modo que todos los metales se pueden comparar directamente. Para obtener la unidad en la que se negocia cada mercado, pasa unit=pound para el cobre, unit=metric_ton para el aluminio y el zinc, y unit=short_ton para el acero.

Los precios de la energía son por unidad de contrato: WTI y BRENT por barril, NATURALGAS por MMBtu, y GASOLINE y HEATINGOIL por galón.

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XCU&unit=pound

Símbolos admitidos

• Metales preciosos: XAU oro, XAG plata, XPT platino, XPD paladio
• Metales industriales: XCU cobre, ALU aluminio, ZNC zinc, HRC acero
• Energía: WTI, BRENT, NATURALGAS, GASOLINE, HEATINGOIL
• Divisas: unas 55 divisas ISO 4217, entre ellas USD, EUR, GBP, JPY, CHF, CAD, AUD, CNY e INR
• Criptomonedas: BTC, ETH, SOL, XRP, BNB, ADA, DOGE, DOT, LINK, LTC, TRX, USDT, USDC

La lista completa y actualizada está en la página de símbolos y también se puede obtener con /api/v1/symbols.

Precios bid y ask

En el plan Standard y superiores, añade -BID o -ASK a un símbolo en currencies para recibir los precios de compra (bid) y de venta (ask) junto al precio medio. Están disponibles para los símbolos cotizados a partir de fuentes interbancarias, es decir, los metales preciosos y las principales divisas. Para currencies=XAU,XAU-BID,XAU-ASK:

"rates": {
  "XAU": 0.0002501319446,
  "USDXAU": 3997.89,
  "XAU-BID": 0.0002501488386,
  "USDXAU-BID": 3997.62,
  "XAU-ASK": 0.0002501150529,
  "USDXAU-ASK": 3998.16
}

Precios del oro por quilate

/carat devuelve los precios del oro en las purezas de joyería, donde la pureza es quilates ÷ 24, en cualquier divisa y unidad. Está disponible en los planes de pago. Para GET /api/v1/carat?carat=all&unit=gram (abreviado):

{
  "success": true,
  "carat": "all",
  "date": "2026-10-23",
  "base": "USD",
  "timestamp": 1792765800,
  "rates": {
    "XAU24K": { "price": 128.53515, "unit": "gram", "carat": "24", "purity": 1 },
    "XAU22K": { "price": 117.82389, "unit": "gram", "carat": "22", "purity": 0.916667 },
    "XAU18K": { "price": 96.401361, "unit": "gram", "carat": "18", "purity": 0.75 },
    "XAU14K": { "price": 74.978836, "unit": "gram", "carat": "14", "purity": 0.583333 }
  }
}

Marcas de tiempo y fechas

timestamp es la hora Unix en segundos (UTC) de los precios devueltos. date es el mismo día en formato YYYY-MM-DD (UTC). Las respuestas históricas llevan la marca de las 00:00 UTC del día solicitado y contienen los precios de cierre de ese día.

const date = new Date(data.timestamp * 1000);
console.log(date.toISOString()); // 2026-10-23T14:30:00.000Z

Precisión

Las cotizaciones son números JSON con hasta 10 dígitos significativos, suficientes para cotizaciones inversas como 0.0002501319446. Redondea solo al mostrar un valor, no antes de hacer cálculos con él.

Horario de mercado y fines de semana

Los metales al contado y las divisas cotizan las 24 horas en días laborables. Los mercados cierran el viernes a las 17:00, hora de Nueva York, y vuelven a abrir el domingo a las 17:00. Durante el fin de semana, los precios se congelan en la última cotización y la API sigue devolviendo el precio de cierre del viernes (las páginas de los símbolos muestran “Mercado cerrado”).

Las criptomonedas cotizan 24/7 y siguen actualizándose los fines de semana. Los metales industriales y la energía siguen el horario de negociación de sus bolsas de futuros.