How to get live gold prices in Python

# pip
pip install requests cachetools tenacity

# or uv (recommended)
uv add requests cachetools tenacity

# python: goldprice.py
# curl-equivalent: https://api.goldprice.dev/v1/spot/XAU-USD-SPOT
import os
from decimal import Decimal
from typing import TypedDict

import requests
from cachetools import TTLCache, cached
from 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  # seconds


class SpotResponse(TypedDict):
    symbol: str
    quote_currency: str
    price: Decimal
    bid: Decimal
    ask: Decimal
    is_stale: bool
    computed_at: str


class 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"]),
        "ask": Decimal(data["ask"]),
        "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']})")

python goldprice.py
# XAU-USD: 4726.01 (computed 2026-04-27T04:49:01.706844+00:00)

# USD spot — default
spot("XAU-USD-SPOT")

# INR — Indian gold market (largest retail gold-search globally)
spot("XAU-INR-SPOT")

# EUR — European pricing surfaces
spot("XAU-EUR-SPOT")

# Silver in USD
spot("XAG-USD-SPOT")