¿Con qué frecuencia se actualiza el precio?

El endpoint al contado se actualiza cada 60 segundos. Free y el acceso sin clave llevan 15 minutos de retraso; los planes de pago reciben precios en tiempo real. TTLCache sigue ese ritmo: durante 60s, spot() devuelve el Decimal guardado sin otra llamada HTTP.

¿La actualización automática cabe en el plan gratuito?

Depende del uso. Consultar cada minuto supone 1.440 llamadas/día, unas 43.000/mes, por encima de las 5.000/mes gratuitas. Usa la caché y consulta bajo demanda. Una frecuencia de 1 llamada/hora supone 720/mes y cabe en Free. Para un volumen alto continuo, consulta los planes de pago en /pricing .

¿Puedo usarlo con fines comerciales?

Todos los planes permiten el uso comercial. Los planes de pago no exigen un enlace de atribución; Free requiere un enlace visible a goldprice.dev junto a los precios.

¿Por qué usar Decimal en vez de float?

Decimal permite cálculos exactos. En coma flotante: 0.1 + 0.2 == 0.30000000000000004 . Sumar miles de operaciones así puede acumular errores de puntos básicos. La API devuelve precios como cadenas con 2 decimales, por ejemplo, "4012.75", para que puedas usar Decimal en tus cálculos.

¿Qué metales se admiten?

Se admiten oro (XAU), plata (XAG) y cobre (HG). Ningún plan ofrece platino ni paladio. Cambia el código del metal en el símbolo; por ejemplo, spot("XAG-USD-SPOT") para consultar la plata.

¿El plan gratuito es realmente gratis?

Sí. Incluye 5.000 llamadas/mes, no requiere tarjeta de crédito y no caduca. Puedes obtener tu clave gratuita desde /onboarding y usarla para consultar la API desde tu código.

¿Puede Claude escribir esto por mí?

Sí. Abre Claude Desktop con el servidor MCP de goldprice.dev instalado y pide: Crea un cliente Python para /v1/spot de goldprice.dev. Usa requests, Decimal, cachetools TTLCache de 60 segundos y tenacity para reintentar errores 429 con espera exponencial. Lee la clave de GOLDPRICE_API_KEY. MCP proporciona el esquema actualizado para usar los campos correctos desde el principio.

Precios del oro en tiempo real en Python

Para obtener precios del oro en tiempo real en Python, envía un GET a api.goldprice.dev/v1/spot/XAU-USD-SPOT con requests y tu clave en la cabecera X-API-Key. Usa cachetools.TTLCache para guardar respuestas durante 60 segundos y Decimal para los cálculos. El plan gratuito incluye 5.000 llamadas/mes, sin tarjeta de crédito. Probado en octubre de 2026 con Python 3.15 + requests 2.34.

Obtén tu clave de API de goldprice.dev

Crea una cuenta gratuita en goldprice.dev/onboarding. Tras confirmar tu correo, el panel muestra una clave que empieza por ga_live_. Guárdala en una variable de entorno:

Shell

export GOLDPRICE_API_KEY=ga_live_replace_with_your_key_here

El plan gratuito incluye 5.000 llamadas/mes y precios al contado del oro en 31 monedas. No necesitas tarjeta de crédito.

Instala las dependencias

Necesitas tres paquetes: requests para las llamadas HTTP, cachetools para la caché TTL dentro del proceso y tenacity para reintentar errores 429. Instálalos con pip o uv:

shell

# pippip install requests cachetools tenacity# or uv (recommended)uv add requests cachetools tenacity

Escribe el cliente de goldprice

Guárdalo como goldprice.py. La función spot() guarda cada símbolo en caché durante 60 segundos, reintenta hasta 3 veces ante un error 429 con espera exponencial y devuelve precios como Decimal para evitar errores de precisión de coma flotante en los cálculos posteriores.

goldprice.py

# python: goldprice.py# curl-equivalent: https://api.goldprice.dev/v1/spot/XAU-USD-SPOTimport osfrom decimal import Decimalfrom typing import TypedDictimport requestsfrom cachetools import TTLCache, cachedfrom tenacity import (    retry,    retry_if_exception_type,    stop_after_attempt,    wait_exponential,)API_BASE = "https://api.goldprice.dev"API_KEY = os.environ["GOLDPRICE_API_KEY"]TIMEOUT = 5  # secondsclass SpotResponse(TypedDict):    symbol: str    quote_currency: str    price: Decimal    bid: Decimal | None  # only on plans that include bid and ask    ask: Decimal | None    is_stale: bool    computed_at: strclass RateLimited(Exception):    """Raised on HTTP 429 so tenacity retries with backoff."""@cached(cache=TTLCache(maxsize=128, ttl=60))@retry(    retry=retry_if_exception_type(RateLimited),    wait=wait_exponential(multiplier=1, min=2, max=30),    stop=stop_after_attempt(3),    reraise=True,)def spot(symbol: str = "XAU-USD-SPOT") -> SpotResponse:    """Fetch live spot price. Cached 60s per symbol, retries 3x on 429."""    resp = requests.get(        f"{API_BASE}/v1/spot/{symbol}",        headers={"X-API-Key": API_KEY},        timeout=TIMEOUT,    )    if resp.status_code == 429:        raise RateLimited(resp.text)    resp.raise_for_status()    data = resp.json()    return {        "symbol": data["symbol"],        "quote_currency": data["quote_currency"],        "price": Decimal(data["price"]),        "bid": Decimal(data["bid"]) if data.get("bid") else None,        "ask": Decimal(data["ask"]) if data.get("ask") else None,        "is_stale": data["is_stale"],        "computed_at": data["computed_at"],    }if __name__ == "__main__":    r = spot("XAU-USD-SPOT")    print(f"{r['symbol']}-{r['quote_currency']}: {r['price']} (computed {r['computed_at']})")

Ejecútalo

Ejecuta el archivo desde la terminal donde exportaste GOLDPRICE_API_KEY. La primera llamada consulta la API; durante 60 segundos, las siguientes usan la caché. Cada proceso nuevo empieza con la caché vacía, ya que solo existe dentro del proceso. Usa Redis si necesitas compartirla entre procesos.

shell

python goldprice.py# XAU-USD: 4012.75 (computed 2026-10-23T07:00:18.221118+00:00)

Cambia la moneda o el metal

Los símbolos siguen el formato METAL-CURRENCY-SPOT. Pasa a spot() cualquier símbolo de las 31 monedas disponibles. TTLCache guarda cada símbolo por separado. Un panel que consulta 5 símbolos cada 60s consume 5 llamadas/minuto sin caché y 0 si las respuestas están en caché.

goldprice.py · varias monedas

# USD spot, defaultspot("XAU-USD-SPOT")spot("XAU-INR-SPOT")spot("XAU-EUR-SPOT")# Silver in USDspot("XAG-USD-SPOT")

Resultado esperado

JSON

{  "symbol": "XAU",  "quote_currency": "USD",  "unit": "troy_ounce",  "contract_type": "spot",  "price": "4012.75",  "is_stale": false,  "computed_at": "2026-10-23T07:00:18.221118+00:00"}

La salida estándar muestra una línea: symbol, quote_currency, price como Decimal y la marca temporal computed_at en formato ISO 8601. Tu código posterior utiliza la respuesta TypedDict.

Errores comunes

Código	Qué ves	Solución
401	`requests.exceptions.HTTPError: 401 Client Error`	Falta la clave o no es válida. Comprueba `GOLDPRICE_API_KEY`: `echo $GOLDPRICE_API_KEY`. Si está vacía, expórtala desde tu panel. El cliente detecta la variable ausente al importar el módulo, así que el error aparece con el primer `import goldprice`.
429	Fallan tres reintentos de `RateLimited` con espera creciente y se propaga la excepción	Alcanzaste el límite por minuto. La caché de 60 segundos evita esto en consultas regulares. Si consultas muchos símbolos distintos a la vez, aumenta `TTLCache.maxsize` o espacia las llamadas. Para un volumen alto continuo, consulta los planes de pago en /pricing.
N/A	Se acumulan errores de coma flotante al sumar muchos precios	Usa siempre `Decimal` en los cálculos, nunca `float`. El cliente devuelve precios como `Decimal`. Para serializar a JSON, usa `str(price)` en lugar de convertir a float y conserva así la precisión durante la transmisión.

Más opciones

Comparte la caché entre procesos: sustituye TTLCache por una caché en Redis para que los procesos usen el mismo precio en memoria
Añade una función bars() para /v1/bars?symbol=XAU-USD-SPOT&interval=1d&from=...&to=... que convierta los datos a un DataFrame de pandas para probar estrategias
Cambia requests por httpx.AsyncClient si tu servicio es asíncrono; la estructura de respuesta es idéntica
Integra el cliente en un endpoint de FastAPI para dar acceso interno a servicios escritos en otros lenguajes
Expón métricas de Prometheus sobre aciertos de caché, latencia p50/p95 y cantidad de reintentos por errores 429