Referencia de la API del oro: endpoints y ejemplos

Todos los endpoints necesitan una clave de API: si falta o es incorrecta devuelve 401, y al superar el límite devuelve 429. Cada endpoint lista sus códigos abajo, y todos se explican en Errores

GETFree /api/v1/price/{symbol}/{currency}/{karat} El precio de un metal en una moneda, por unidad y por gramo. GETFree /api/v1/karat El precio del gramo en cada quilate de oro, en una sola solicitud. GETFree /api/v1/convert Entre metales, monedas y unidades de peso. GETFree /api/v1/symbols Los metales que puedes pedir. GETFree /api/v1/rates Los tipos de hoy frente al dólar. GETBasic /api/v1/history/{symbol} Los cierres diarios de un metal en un periodo. GETPro /api/v1/ohlc/{symbol} Apertura, máximo, mínimo y cierre de cada día.

Autenticación

Cada solicitud necesita tu clave en esta cabecera. Para una prueba rápida también puedes enviarla como ?api_key=. Una clave solo funciona en el sitio donde se registró su cuenta. Los navegadores pueden llamar a la API directamente, pero entonces los visitantes ven la clave.

Header

X-API-Key: YOUR_API_KEY

Cuando alcanzas un límite

Free incluye 100 solicitudes por hora, Basic 2,000 y Pro no tiene límite. El recuento cubre todas las claves de tu cuenta, también las solicitudes rechazadas por el plan, y se reinicia cada hora en punto. Las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (tiempo Unix) muestran dónde estás; Pro solo recibe X-RateLimit-Limit: unlimited. Al superar el límite recibes 429 con una cabecera Retry-After en segundos. Límites del plan gratuito

Precio en directo

GET/api/v1/price/{symbol}/{currency}/{karat}Clave de API · Free o superior

El precio en directo de un metal en cualquier moneda, por su unidad y por gramo. Para el oro puedes elegir los quilates.

Parámetros de ruta

symbolstringobligatorio: El metal: XAU, XAG, XPT, XPD o HG.
currencystring: Código de moneda, USD por defecto. Cualquier código de /rates.
karatint: Solo oro: 24, 22, 21, 18 o 14, 24 por defecto. Cambia el precio por gramo.

Parámetros de consulta

currencystring: El mismo valor como parámetro de consulta. Si se envían ambos, gana la ruta.
karatint: El mismo valor como parámetro de consulta. Si se envían ambos, gana la ruta.

Campos de respuesta

price: El precio por unidad. Los quilates no lo cambian. El oro en EGP sigue el mercado local de Egipto.
gram: El precio de un gramo, con los quilates de la respuesta en el oro. En EGP son libras enteras, salvo por debajo de 10 libras.
gramBuy, gramSell: Solo oro en EGP: precios estimados de compra y venta del gramo.
karat: Solo oro: los quilates del precio por gramo.
prevClose, chPercent: Solo Pro: el último cierre en la moneda pedida y el cambio desde él en %. null si no hay cierre.
updatedAt: La hora de esta respuesta.

Códigos de respuesta

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable400 unknown_karat400 karat_only_for_gold404 unknown_symbol429 rate_limit_exceeded

Esquema de respuesta

{
  "symbol": string,
  "name": string,
  "currency": string,
  "unit": string,        // "oz" | "lb"
  "price": number,
  "gram": number,
  "gramBuy"?: number,    // gold in EGP
  "gramSell"?: number,   // gold in EGP
  "karat"?: number,      // gold
  "prevClose"?: number | null,  // Pro
  "chPercent"?: number | null,  // Pro
  "updatedAt": string    // ISO-8601
}

RespuestaEjemplo

{
    "symbol": "XAU",
    "name": "Gold",
    "currency": "USD",
    "unit": "oz",
    "price": 4072.1,
    "gram": 130.921,
    "karat": 24,
    "updatedAt": "2026-11-07T02:39:49+02:00"
}

Precios por quilate

GET/api/v1/karatClave de API · Free o superior

El precio en vivo del gramo de oro en cada quilate (24, 22, 21, 18 y 14) en una sola solicitud. Para un solo quilate, usa /price.

Parámetros de consulta

currencystring: Código de moneda, USD por defecto. Cualquier código de /rates.

Campos de respuesta

karats[].karat: El quilate y su pureza: 24 = 100%, 22 = 91.66%, 21 = 87.5%, 18 = 75%, 14 = 58.33%.
karats[].gram: El precio de un gramo, con los quilates de la respuesta en el oro. En EGP son libras enteras, salvo por debajo de 10 libras.
karats[].gramBuy, gramSell: Solo oro en EGP: precios estimados de compra y venta del gramo.
updatedAt: La hora de esta respuesta.

Códigos de respuesta

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

Esquema de respuesta

{
  "currency": string,
  "karats": [
    {
      "karat": number,
      "gram": number,
      "gramBuy"?: number,   // EGP
      "gramSell"?: number   // EGP
    }
  ],
  "updatedAt": string    // ISO-8601
}

RespuestaEjemplo

{
    "currency": "USD",
    "karats": [
        {
            "karat": 24,
            "gram": 130.921
        },
        {
            "karat": 22,
            "gram": 120.0022
        },
        {
            "karat": 21,
            "gram": 114.5558
        },
        {
            "karat": 18,
            "gram": 98.1907
        },
        {
            "karat": 14,
            "gram": 76.3662
        }
    ],
    "updatedAt": "2026-11-07T02:39:49+02:00"
}

Conversión

GET/api/v1/convertClave de API · Free o superior

Convierte entre un metal y una moneda, dos metales o dos monedas, al precio en vivo. Para el oro puedes elegir el quilate.

Parámetros de consulta

fromstringobligatorio: Lo que conviertes: un metal (XAU, XAG, XPT, XPD, HG) o un código de moneda de /rates.
tostringobligatorio: A qué conviertes, con las mismas opciones que from.
amountnumber: La cantidad, 1 por defecto. Debe ser mayor que 0.
unitstring: La unidad del metal: gram, tola, oz, tael, kilo, lb. Por defecto, la unidad propia del metal (oz, o lb para el cobre).
karatint: Cuando un lado es oro: 24, 22, 21, 18, 14. 24 por defecto.

Campos de respuesta

unit: La unidad del metal. No aparece si ambos lados son monedas.
karat: El quilate usado. Solo cuando un lado es oro.
rate: El valor de una unidad de from, expresado en to.
result: La cantidad multiplicada por rate.
updatedAt: La hora de esta respuesta.

Códigos de respuesta

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 from_and_to_required400 invalid_amount400 unknown_unit400 unknown_karat400 karat_only_for_gold400 unknown_currency_or_unavailable429 rate_limit_exceeded503 prices_unavailable

Esquema de respuesta

{
  "from": string,
  "to": string,
  "amount": number,
  "unit"?: string,     // metal side
  "karat"?: number,    // gold side
  "rate": number,
  "result": number,
  "updatedAt": string  // ISO-8601
}

RespuestaEjemplo

{
    "from": "XAU",
    "to": "USD",
    "amount": 1,
    "unit": "gram",
    "karat": 24,
    "rate": 130.921,
    "result": 130.92,
    "updatedAt": "2026-11-07T02:39:49+02:00"
}

Símbolos

GET/api/v1/symbolsClave de API · Free o superior

Los metales que conoce la API, con sus nombres y unidades.

Campos de respuesta

symbol: El símbolo del metal.
name: El nombre del metal.
unit: La unidad del precio: oz o lb.

Códigos de respuesta

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

Esquema de respuesta

{
  "symbols": [
    { "symbol": string, "name": string, "unit": string }
  ],
  "_server_time": string  // ISO-8601
}

RespuestaEjemplo

{
    "symbols": [
        {
            "symbol": "XAU",
            "name": "Gold",
            "unit": "oz"
        },
        {
            "symbol": "XAG",
            "name": "Silver",
            "unit": "oz"
        },
        {
            "symbol": "XPT",
            "name": "Platinum",
            "unit": "oz"
        },
        {
            "symbol": "XPD",
            "name": "Palladium",
            "unit": "oz"
        },
        {
            "symbol": "HG",
            "name": "Copper",
            "unit": "lb"
        }
    ],
    "_server_time": "2026-11-07T02:39:49+02:00"
}

Tipos de cambio

GET/api/v1/ratesClave de API · Free o superior

Los tipos de cambio de hoy frente al dólar estadounidense, primero las monedas más usadas.

Campos de respuesta

base: La moneda base: USD.
rates: El tipo de cada moneda frente a un dólar.

Códigos de respuesta

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified429 rate_limit_exceeded

Esquema de respuesta

{
  "base": "USD",
  "rates": { [currency: string]: number },
  "_server_time": string  // ISO-8601
}

RespuestaEjemplo

{
    "base": "USD",
    "rates": {
        "USD": 1,
        "EUR": 0.89048,
        "GBP": 0.742915,
        "INR": 94.537031,
        "CNY": 6.682525,
        "JPY": 157.835475
    },
    "_server_time": "2026-11-07T02:39:49+02:00"
}

Historial diario

GET/api/v1/history/{symbol}Clave de API · Basic o superior

Los cierres diarios de un metal, del más antiguo al más reciente, hasta donde llega el archivo y terminando con el día en curso, así que puede haber una fila más que days. Cada día usa su propio tipo de cambio, y el oro en EGP usa además la prima del mercado local de ese día. Se omite el día sin tipo guardado.

Parámetros de ruta

symbolstringobligatorio: El metal: XAU, XAG, XPT, XPD o HG.

Parámetros de consulta

currencystring: Código de moneda, USD por defecto. Solo las monedas con datos diarios, listadas en Monedas.
rangestring: 1W, 1M, 3M, 6M, 1Y o ALL (10 años). Gana sobre days, y cualquier otro valor se ignora.
daysint: Número de días, 365 por defecto. Se mantiene entre 1 y 3650.

Campos de respuesta

days: Los días usados, tras aplicar range y el límite de 1 a 3650.
count: Cuántas filas se devolvieron.
history[].date, close: El día y su precio de cierre por unidad. El cierre de hoy cambia hasta que termina el día.

Códigos de respuesta

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_basic404 unknown_symbol429 rate_limit_exceeded

Esquema de respuesta

{
  "symbol": string,
  "currency": string,
  "days": number,
  "count": number,
  "history": [
    { "date": string, "close": number }  // YYYY-MM-DD, oldest first
  ],
  "_server_time": string  // ISO-8601
}

RespuestaEjemplo

{
    "symbol": "XAU",
    "currency": "USD",
    "days": 1,
    "count": 2,
    "history": [
        {
            "date": "2026-11-06",
            "close": 4072
        },
        {
            "date": "2026-11-07",
            "close": 4072.1001
        }
    ],
    "_server_time": "2026-11-07T02:39:49+02:00"
}

Velas diarias

GET/api/v1/ohlc/{symbol}Clave de API · Pro o superior

Una vela por día, de la más antigua a la más reciente, terminando con el día en curso. Cada día usa su propio tipo de cambio, y el oro en EGP usa además la prima del mercado local de ese día. Se omite el día sin tipo guardado.

Parámetros de ruta

symbolstringobligatorio: El metal: XAU, XAG, XPT, XPD o HG.

Parámetros de consulta

currencystring: Código de moneda, USD por defecto. Solo las monedas con datos diarios, listadas en Monedas.
startunix: Primer día, en tiempo Unix en segundos. Por defecto, desde el primer día guardado.
endunix: Último día, en tiempo Unix en segundos. Por defecto, hasta hoy.

Campos de respuesta

count: Cuántas filas se devolvieron.
candles[].date, open, high, low, close: El día y sus precios por unidad.
candles[].sealed: true si el día es definitivo, false mientras puede cambiar.

Códigos de respuesta

200 OK401 api_key_required401 invalid_api_key403 key_disabled403 account_suspended403 email_not_verified400 unknown_currency403 feature_requires_pro404 unknown_symbol429 rate_limit_exceeded

Esquema de respuesta

{
  "symbol": string,
  "currency": string,
  "count": number,
  "candles": [
    {
      "date": string,  // YYYY-MM-DD
      "open": number,
      "high": number,
      "low": number,
      "close": number,
      "sealed": boolean
    }
  ],
  "_server_time": string  // ISO-8601
}

RespuestaEjemplo

{
    "symbol": "XAU",
    "currency": "USD",
    "count": 2,
    "candles": [
        {
            "date": "2026-11-06",
            "open": 4090.3,
            "high": 4106.7998,
            "low": 4032.5,
            "close": 4072,
            "sealed": true
        },
        {
            "date": "2026-11-07",
            "open": 4072.3999,
            "high": 4072.3999,
            "low": 4072.1001,
            "close": 4072.1001,
            "sealed": false
        }
    ],
    "_server_time": "2026-11-07T02:39:49+02:00"
}

Monedas

/price, /karat, /convert y /rates funcionan con 166 monedas, y /rates las lista. /history y /ohlc funcionan con las 47 de abajo, porque cada día guarda sus tipos. Cualquier otro código en estos dos devuelve 400 unknown_currency.

USDEGPSARAEDKWDQARBHDOMRJODIQDLBPSDGYERLYDTNDDZDMADEURGBPTRYINRIDRCNYVNDPKRJPYCADAUDSGDHKDKRWTHBPHPMXNBRLZARCHFNZDILSMYRPLNCZKSEKNOKDKKHUFRON

Errores

Los errores son JSON con un campo error, y algunos añaden los campos de la tabla. Una solicitud se comprueba en este orden: clave, límite por hora, plan y parámetros.

Estado	error	Cuándo	También devuelve
400	`unknown_currency_or_unavailable`	Moneda desconocida, o el precio no está disponible ahora	`symbol, currency`
400	`unknown_currency`	En /history o /ohlc: una moneda sin datos diarios	`currency, allowed`
400	`unknown_karat`	Quilates distintos de 24, 22, 21, 18 o 14	`karat, allowed`
400	`karat_only_for_gold`	Quilates con un metal que no es oro	`symbol`
400	`from_and_to_required`	Falta from o to
400	`invalid_amount`	amount no es un número mayor que 0	`amount`
400	`unknown_unit`	Una unidad distinta de gram, tola, oz, tael, kilo, lb	`unit, allowed`
401	`api_key_required`	La solicitud no tiene clave
401	`invalid_api_key`	La clave no es válida
403	`feature_requires_basic`	El plan no incluye este endpoint
403	`feature_requires_pro`	El plan no incluye este endpoint
403	`key_disabled`	La clave está desactivada
403	`account_suspended`	La cuenta está suspendida
403	`email_not_verified`	El correo de la cuenta aún no está confirmado
403	`Forbidden`	La dirección /api o /api/v1 sola. Su respuesta tiene los campos status y message en lugar de error.
404	`unknown_symbol`	Metal desconocido	`symbol`
404	`not_found`	No existe ese endpoint o la ruta tiene partes de más. Historial y velas solo aceptan currency como parámetro de consulta.
429	`rate_limit_exceeded`	Se superaron las solicitudes por hora del plan
503	`prices_unavailable`	El precio de un metal no está disponible ahora