Goldpreis-API: Der vollständige Leitfaden für Entwickler

Was eine Goldpreis-API Ihnen liefert

Eine Goldpreis-API liefert den aktuellen und historischen Goldpreis als strukturierte Daten, meist als JSON über HTTPS. Ihre Software kann ihn so nutzen, ohne Webseiten auszulesen oder Zahlen von Hand zu kopieren. In MetalAPI hat Gold das Symbol XAU, den ISO-4217-Code für eine Feinunze Gold. Sein Live-Preis ist der Spotpreis: der Mittelwert zwischen Geld- und Briefkursen im Interbankenhandel.

Die meisten Integrationen sind keine Handelssysteme. Typische Einsatzzwecke:

• Onlineshops und Juweliere, die die Preise ihrer Goldprodukte an die Marktbewegungen anpassen.
• Rechner für Altgold, Karatschmuck oder Aufgelder auf Barren und Münzen.
• Portfolio-Tracker und Finanz-Apps, die Bestände in einer Landeswährung bewerten.
• Buchhaltungs- und ERP-Systeme, die Lagerbestände zu einem täglichen Schlusskurs neu bewerten.
• Dashboards, Newsletter und interne Berichte, die einen Chart des letzten Jahres brauchen.

Dieselbe API umfasst Silber (XAG), Platin (XPT) und Palladium (XPD), vier Industriemetalle, fünf Energiekontrakte, 57 Währungen und 13 Kryptowährungen: insgesamt 83 Symbole, die alle auf der Symbolseite aufgeführt sind. Dieser Leitfaden konzentriert sich auf Gold, aber alles darin gilt auch für die anderen Symbole.

API-Schlüssel erhalten

Erstellen Sie ein kostenloses Konto. Der Free-Tarif erfordert keine Kreditkarte und umfasst 100 Anfragen pro Monat mit täglicher Preisaktualisierung, genug, um eine Integration zu entwickeln und zu testen. Kostenpflichtige Tarife bieten aktuellere Preise, mehr Anfragen und zusätzliche Endpunkte; die Tariftabelle weiter unten fasst sie zusammen.

Öffnen Sie im Dashboard API keys und erstellen Sie einen Schlüssel. Schlüssel beginnen mit mk_live_. Der vollständige Schlüssel wird nur einmal angezeigt, weil nur ein Hash davon gespeichert wird. Legen Sie ihn daher sofort in einer Umgebungsvariablen oder einem Secrets-Manager ab:

export METALAPI_KEY="mk_live_your_key_here"

Die API akzeptiert den Schlüssel auf drei gleichwertige Arten: als Query-Parameter api_key, im Header Authorization: Bearer oder im Header X-API-Key. Verwenden Sie in der Produktion bevorzugt einen Header, denn vollständige URLs landen leicht in Zugriffsprotokollen, Proxys und Error-Trackern. Die Anleitung zur Authentifizierung erklärt außerdem domainbeschränkte Schlüssel für Aufrufe aus dem Browser.

# 1. Query-Parameter
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

# 2. Authorization-Header
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "Authorization: Bearer $METALAPI_KEY"

# 3. X-API-Key-Header
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

Die erste Anfrage mit curl, JavaScript und Python

Jeder Endpunkt ist eine einfache GET-Anfrage unter https://metalapi.com/api/v1/. Der Endpunkt /latest liefert aktuelle Preise. base legt die Währung fest, in der die Preise angegeben werden (Standard: USD), und currencies beschränkt die Antwort auf die Symbole, die Sie brauchen. Eine Anfrage kann viele Symbole zurückgeben und zählt trotzdem als eine einzige Anfrage.

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

Eine erfolgreiche Antwort sieht so aus. Die Zahlen sind die Beispielwerte, die in der gesamten MetalAPI-Dokumentation verwendet werden, keine Live-Preise:

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319,
    "USDXAU": 3997.89,
    "XAG": 0.0185392857,
    "USDXAG": 53.94
  },
  "rate_limit": {
    "limit": 10000,
    "remaining": 9876,
    "reset": 1793491200,
    "used": 124,
    "plan": "Standard",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

Derselbe Aufruf aus Node.js 18 oder neuer, wo fetch bereits integriert ist. Speichern Sie ihn als gold.mjs, damit await auf oberster Ebene funktioniert, und führen Sie node gold.mjs aus:

const params = new URLSearchParams({ base: "USD", currencies: "XAU,XAG" });
const res = await fetch(`https://metalapi.com/api/v1/latest?${params}`, {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();

if (!data.success) {
  throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
}

const gold = data.rates[`${data.base}XAU`];
const asOf = new Date(data.timestamp * 1000).toISOString();
console.log(`Gold: ${gold} ${data.base} per troy ounce (data from ${asOf})`);

Und aus Python mit der Bibliothek requests:

import os

import requests

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": "XAU,XAG"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

base = data["base"]
print(f"Gold:   {data['rates'][base + 'XAU']} {base} per troy ounce")
print(f"Silver: {data['rates'][base + 'XAG']} {base} per troy ounce")

Beide Snippets bilden den Kursschlüssel aus data.base, statt ihn fest einzutragen. Diese kleine Gewohnheit hält den Code korrekt, wenn Sie später die Basiswährung wechseln, und sie führt zum wichtigsten Teil dieses Leitfadens.

Das Kursformat richtig lesen

Jedes Symbol erscheint in rates zweimal, und die beiden Zahlen sind Kehrwerte voneinander:

Die allgemeine Regel: rates.<BASE><SYMBOL> ist der Preis einer Einheit des Symbols in der Basiswährung. Der einfache Schlüssel rates.<SYMBOL> ist der Kehrwert, also Einheiten des Symbols pro Einheit der Basiswährung. Die Kehrwertform bleibt aus Gründen der Kompatibilität mit Forex-APIs und älteren MetalAPI-Integrationen erhalten.

Wenn Sie aus einer älteren Integration bereits Kehrwerte gespeichert haben, müssen Sie diese nicht erneut herunterladen: Preis = 1 ÷ Kehrwert. Mit dem Beispiel oben ergibt 1 ÷ 0,0002501319 wieder 3.997,89, abgesehen von Rundungsdifferenzen in den letzten Stellen.

Für Währungen gilt dieselbe Regel. Mit der Basis USD ist USDEUR der Preis eines Euro in Dollar und EUR die Anzahl Euro pro Dollar. Die Anleitung zu Datenformaten enthält weitere Beispiele, darunter die Schlüssel für Geld- und Briefkurse, die ab dem Standard-Tarif verfügbar sind.

Basiswährungen und Einheiten

Um Gold in einer anderen Währung zu bepreisen, ändern Sie base. Der Kursschlüssel ändert sich mit: base=EUR liefert EURXAU, und base=INR liefert INRXAU. Kreuzkurse stammen aus einem einzigen Snapshot, Gold in Euro und der Euro in Dollar sind also immer untereinander konsistent.

Metallpreise gelten standardmäßig pro Feinunze. Mit dem Parameter unit erhalten Sie sie pro anderer Gewichtseinheit:

Diese Anfrage liefert Gold und Silber in Euro pro Gramm. Wenn unit nicht der Standardwert ist, wiederholt die Antwort ihn in einem Feld unit auf oberster Ebene:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

unit wirkt sich nur auf Edel- und Industriemetalle aus. Energie, Währungen und Krypto bleiben davon unberührt. Details zu Feinunzen, Gramm, Tolas und Rundung finden Sie in Feinunze, Gramm und Kilogramm. Wenn Sie Schmuck verkaufen, behandelt Goldpreise nach Karat erklärt Preise für 22 und 18 Karat sowie den Endpunkt /carat.

Historische Goldpreise

Vergangene Preise verwenden dieselben Parameter und dasselbe Antwortformat. Die Historie beginnt für Metalle und Energie im Jahr 2000, für Währungen am 4. Januar 1999 und für Krypto im Jahr 2014. Vier Endpunkte decken die meisten Anforderungen ab:

• /YYYY-MM-DD (oder /historical?date=YYYY-MM-DD oder /yesterday): Schlusskurse eines Tages. Für Wochenenden und Feiertage wird der Schlusskurs des letzten Handelstags geliefert.
• /timeframe (Alias /timeseries): Tagesschlusskurse zwischen start_date und end_date, bis zu 30 Tage pro Anfrage im Free-Tarif und 365 Tage in kostenpflichtigen Tarifen.
• /change: Anfangskurs, Endkurs sowie absolute und prozentuale Veränderung zwischen zwei Daten.
• /ohlc: Eröffnungs-, Höchst-, Tiefst- und Schlusskurs eines Tages.

# Gold und Silber zum Schlusskurs vom 15. Januar 2024
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Tägliche Goldschlusskurse in Euro für September 2026
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

Schlusskurse vergangener Tage ändern sich nicht. Speichern Sie sie daher einmal, statt sie erneut abzufragen. Historische Gold- und Silberpreise per API zeigt, wie Sie 25 Jahre Daten abschnittsweise abrufen, lokal speichern und als Chart darstellen. Die Anleitung zu historischen Daten enthält eine JavaScript-Hilfsfunktion für lange Zeiträume.

Fehler, Kontingente und Tariflimits

Eine fehlgeschlagene Anfrage liefert einen HTTP-Fehlerstatus und einen Body mit success: false. Das error-Objekt enthält einen numerischen code, einen maschinenlesbaren type und eine für Menschen lesbare info. Verzweigen Sie anhand von code oder type, niemals anhand des info-Texts. Fehler wegen Anfragelimit (104), Kontingent (105), Tarifbeschränkung (106) und Zeitraum (207) enthalten zusätzlich eine upgrade_url:

{
  "success": false,
  "error": {
    "code": 106,
    "type": "plan_restriction",
    "info": "The carat endpoint requires a paid subscription plan",
    "upgrade_url": "https://metalapi.com/dashboard/billing"
  }
}

Die Codes, denen Sie am wahrscheinlichsten begegnen:

Jede authentifizierte Antwort meldet Ihr Kontingent, sowohl in X-RateLimit-*-Headern als auch im Objekt rate_limit im Body. /usage und /symbols werden nie auf das Kontingent angerechnet, Ihr Monitoring kann sie also beliebig aufrufen. Anfragen, die mit 104, 106, 107 oder einem Serverfehler abgelehnt werden, werden nicht berechnet, Validierungsfehler dagegen schon. Die Anleitung zur Fehlerbehandlung listet alle Codes auf und enthält eine Hilfsfunktion für Wiederholungen.

Die Tarife unterscheiden sich vor allem im Anfragevolumen und darin, wie aktuell die Preise sind:

Bei jährlicher Abrechnung sparen Sie bis zu 25 %. Die aktuellen Details finden Sie immer auf der Preisseite.

Caching und Tipps für den Produktivbetrieb

/latest häufiger abzufragen, als Ihr Tarif aktualisiert wird, liefert dieselben Zahlen und verbraucht Kontingent ohne Nutzen. Cachen Sie die aktuellen Preise mindestens für die Dauer des Aktualisierungsintervalls Ihres Tarifs und vergangene Tage dauerhaft. Diese Python-Hilfsfunktion cacht die aktuellen Preise und liefert weiter die letzte gültige Antwort aus, wenn die API nicht erreichbar ist:

import os
import time

import requests

TTL_SECONDS = 600  # Standard-Tarif: Preise werden alle 10 Minuten aktualisiert
session = requests.Session()
session.headers["X-API-Key"] = os.environ["METALAPI_KEY"]
_cache = {"at": 0.0, "data": None}


def latest_prices():
    now = time.monotonic()
    if _cache["data"] and now - _cache["at"] < TTL_SECONDS:
        return _cache["data"]
    try:
        r = session.get(
            "https://metalapi.com/api/v1/latest",
            params={"currencies": "XAU,XAG,XPT,XPD"},
            timeout=10,
        )
        data = r.json()
    except (requests.RequestException, ValueError):
        data = None
    if data and data.get("success"):
        _cache.update(at=now, data=data)
        return data
    if _cache["data"]:
        return _cache["data"]  # letzte gültige Preise; deren Zeitstempel anzeigen
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

Einige weitere Gewohnheiten halten eine Integration günstig und zuverlässig:

• Alle Symbole in einem Aufruf abfragen. currencies=XAU,XAG,XPT,XPD kostet eine Anfrage, vier einzelne Aufrufe kosten vier.
• Den Schlüssel auf dem Server halten. Muss ein Browser die API aufrufen, verwenden Sie einen domainbeschränkten Schlüssel. Um Preise ohne eigenen Code auf einer Website anzuzeigen, hält ein einbettbares Widget den Schlüssel vollständig aus der Seite heraus.
• Den Zeitstempel anzeigen. timestamp ist der Zeitpunkt der Daten, nicht Ihrer Anfrage. Zeigen Sie ihn neben dem Preis an, besonders wenn Sie einen zwischengespeicherten Wert ausliefern oder der Markt am Wochenende geschlossen ist.
• Das Polling planen. Eine Abfrage alle 10 Minuten verbraucht etwa 4.500 Anfragen im Monat, eine Abfrage pro Minute etwa 45.000. Ab dem Pro-Tarif können Sie stattdessen den Echtzeit-Stream nutzen, und ab Advanced erhalten Sie Preisalarme per Webhook.
• Timeouts und gezielte Wiederholungen verwenden. Setzen Sie ein Timeout von etwa 10 Sekunden, wiederholen Sie 104 nach Retry-After und 5xx-Fehler mit Backoff, und wiederholen Sie Validierungsfehler nie.
• Symbole vorab prüfen. Laden Sie /symbols einmal beim Start (der Aufruf ist kostenlos) und lehnen Sie unbekannte Codes ab, bevor sie eine Anfrage kosten.

Wenn Sie mit KI-Assistenten arbeiten, stellt der MetalAPI-MCP-Server unter https://metalapi.com/mcp dieselben Daten als Tools bereit. Claude, ChatGPT, Cursor oder VS Code können so Goldpreise und Historie im Rahmen Ihres Tarifs abrufen; siehe KI & MCP. Die Referenz für alle Endpunkte und Parameter ist die API-Dokumentation.