API du cours de l'or : le guide complet pour les développeurs

Ce que vous apporte une API du cours de l'or

Une API du cours de l'or renvoie le prix actuel et historique de l'or sous forme de données structurées, généralement du JSON via HTTPS, pour que votre logiciel puisse l'utiliser sans scraper de pages web ni recopier des chiffres à la main. Dans MetalAPI, l'or a pour symbole XAU, le code ISO 4217 d'une once troy d'or. Son prix en direct est le prix spot : le point médian entre les cotations bid et ask interbancaires.

La plupart des intégrations ne sont pas des systèmes de trading. Les usages typiques ressemblent à ceci :

• Boutiques en ligne et bijoutiers qui ajustent le prix de leurs produits en or au fil du marché.
• Calculateurs pour l'or de récupération, les bijoux selon leur carat ou les primes sur l'or d'investissement.
• Suivis de portefeuille et applications de finances personnelles qui valorisent des avoirs en devise locale.
• Systèmes comptables et ERP qui réévaluent les stocks à un cours de clôture quotidien.
• Tableaux de bord, newsletters et rapports internes qui ont besoin d'un graphique sur la dernière année.

La même API couvre l'argent (XAG), le platine (XPT) et le palladium (XPD), quatre métaux industriels, cinq contrats énergétiques, 57 devises et 13 cryptomonnaies : 83 symboles au total, tous listés sur la page des symboles. Ce guide se concentre sur l'or, mais tout ce qu'il contient s'applique aussi aux autres symboles.

Obtenir une clé API

Créez un compte gratuit. Le plan Free ne demande pas de carte bancaire et inclut 100 requêtes par mois avec des prix mis à jour quotidiennement, ce qui suffit pour construire et tester une intégration. Les plans payants ajoutent des prix plus frais, davantage de requêtes et des endpoints supplémentaires ; le tableau des plans plus bas les résume.

Dans le tableau de bord, ouvrez API keys et créez une clé. Les clés commencent par mk_live_. La clé complète n'est affichée qu'une seule fois, car seul un hash en est conservé : placez-la donc directement dans une variable d'environnement ou un gestionnaire de secrets :

export METALAPI_KEY="mk_live_your_key_here"

L'API accepte la clé de trois manières équivalentes : un paramètre de requête api_key, un en-tête Authorization: Bearer ou un en-tête X-API-Key. En production, préférez un en-tête, car les URL complètes finissent souvent dans les journaux d'accès, les proxys et les outils de suivi d'erreurs. Le guide d'authentification explique aussi les clés restreintes par domaine pour les appels depuis le navigateur.

# 1. Paramètre de requête
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

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

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

Votre première requête en curl, JavaScript et Python

Chaque endpoint est une simple requête GET sous https://metalapi.com/api/v1/. L'endpoint /latest renvoie les prix actuels. base définit la devise dans laquelle les prix sont exprimés (USD par défaut) et currencies limite la réponse aux symboles dont vous avez besoin. Une requête peut renvoyer de nombreux symboles et ne compte pourtant que pour une seule requête.

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

Une réponse réussie ressemble à ceci. Les valeurs sont celles des exemples de la documentation MetalAPI, pas des prix en direct :

{
  "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"
  }
}

Voici le même appel depuis Node.js 18 ou plus récent, qui intègre fetch. Enregistrez-le sous gold.mjs pour que le await de premier niveau fonctionne, puis exécutez node gold.mjs :

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})`);

Et depuis Python avec la bibliothèque 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")

Les deux extraits construisent la clé du taux à partir de data.base au lieu de la coder en dur. Cette petite habitude garde le code correct quand vous changez plus tard de devise de base, et elle nous amène au point le plus important de ce guide.

Bien lire le format des taux

Chaque symbole apparaît deux fois dans rates, et les deux nombres sont l'inverse l'un de l'autre :

La règle générale : rates.<BASE><SYMBOL> est le prix d'une unité du symbole dans la devise de base. La clé simple rates.<SYMBOL> en est l'inverse, soit le nombre d'unités du symbole pour une unité de la devise de base. La forme inverse est conservée pour la compatibilité avec les API de type forex et les anciennes intégrations de MetalAPI.

Si vous stockez déjà des valeurs inverses issues d'une ancienne intégration, inutile de les télécharger à nouveau : prix = 1 ÷ inverse. Avec l'exemple ci-dessus, 1 ÷ 0,0002501319 redonne 3 997,89, aux derniers chiffres d'arrondi près.

Les devises suivent la même règle. Avec la base USD, USDEUR est le prix d'un euro en dollars et EUR le nombre d'euros par dollar. Le guide des formats de données donne d'autres exemples, notamment les clés bid et ask disponibles à partir du plan Standard.

Devises de base et unités

Pour coter l'or dans une autre devise, changez base. La clé du taux change avec elle : base=EUR renvoie EURXAU, et base=INR renvoie INRXAU. Les taux croisés proviennent d'un même instantané : l'or en euros et l'euro en dollars sont donc toujours cohérents entre eux.

Les prix des métaux sont exprimés par once troy par défaut. Le paramètre unit les renvoie pour une autre unité de masse :

Cette requête renvoie l'or et l'argent en euros par gramme. Lorsque unit n'est pas la valeur par défaut, la réponse le répète dans un champ unit de premier niveau :

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

unit ne concerne que les métaux précieux et industriels. L'énergie, les devises et les cryptos ne sont pas affectées. Pour tout savoir sur les onces troy, les grammes, les tolas et les arrondis, lisez Onces troy, grammes et kilogrammes. Si vous vendez des bijoux, Les prix de l'or par carat expliqués couvre les prix 22K et 18K ainsi que l'endpoint /carat.

Cours historiques de l'or

Les prix passés utilisent les mêmes paramètres et le même format de réponse. L'historique commence en 2000 pour les métaux et l'énergie, le 4 janvier 1999 pour les devises et en 2014 pour les cryptos. Quatre endpoints couvrent la plupart des besoins :

• /YYYY-MM-DD (ou /historical?date=YYYY-MM-DD, ou /yesterday) : les cours de clôture d'un jour. Pour les week-ends et jours fériés, c'est la clôture du dernier jour de cotation qui est renvoyée.
• /timeframe (alias /timeseries) : les clôtures quotidiennes entre start_date et end_date, jusqu'à 30 jours par requête sur Free et 365 jours sur les plans payants.
• /change : taux de départ, taux de fin, variation absolue et en pourcentage entre deux dates.
• /ohlc : ouverture, plus haut, plus bas et clôture d'un jour.

# Or et argent à la clôture du 15 janvier 2024
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Clôtures quotidiennes de l'or en euros pour septembre 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"

Les cours de clôture des jours passés ne changent pas : stockez-les une fois au lieu de les redemander. Cours historiques de l'or et de l'argent par API explique comment paginer 25 ans de données, les stocker localement et les représenter en graphique. Le guide des données historiques propose un utilitaire JavaScript pour les longues périodes.

Erreurs, quotas et limites des plans

Une requête en échec renvoie un statut d'erreur HTTP et un corps avec success: false. L'objet error contient un code numérique, un type lisible par une machine et un info lisible par un humain. Basez votre logique sur code ou type, jamais sur le texte de info. Les erreurs de limite de débit (104), de quota (105), de restriction de plan (106) et de période (207) incluent aussi une 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"
  }
}

Les codes que vous rencontrerez le plus probablement :

Chaque réponse authentifiée indique votre quota, à la fois dans les en-têtes X-RateLimit-* et dans l'objet rate_limit du corps. /usage et /symbols ne sont jamais décomptés du quota : votre supervision peut donc les appeler librement. Les requêtes rejetées avec 104, 106, 107 ou une erreur serveur ne sont pas facturées, mais les erreurs de validation le sont. Le guide de gestion des erreurs liste tous les codes et inclut un utilitaire de nouvelles tentatives.

Les plans diffèrent surtout par le volume de requêtes et la fraîcheur des prix :

La facturation annuelle permet d'économiser jusqu'à 25 %. La page des tarifs présente toujours les informations à jour.

Cache et conseils pour la production

Demander /latest plus souvent que la fréquence de mise à jour de votre plan renvoie les mêmes chiffres et consomme du quota pour rien. Mettez en cache les derniers prix pendant au moins l'intervalle de mise à jour de votre plan, et les jours passés de façon permanente. Cet utilitaire Python met en cache les derniers prix et continue de servir la dernière réponse valide si l'API est injoignable :

import os
import time

import requests

TTL_SECONDS = 600  # Plan Standard : prix mis à jour toutes les 10 minutes
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"]  # derniers prix valides ; affichez leur horodatage
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

Quelques habitudes de plus pour garder une intégration économique et fiable :

• Demandez tous les symboles en un seul appel. currencies=XAU,XAG,XPT,XPD coûte une requête ; quatre appels séparés en coûtent quatre.
• Gardez la clé sur le serveur. Si un navigateur doit appeler l'API, utilisez une clé restreinte par domaine. Pour afficher des prix sur un site web sans écrire de code, un widget intégrable tient complètement la clé hors de la page.
• Affichez l'horodatage. timestamp est l'heure des données, pas celle de votre requête. Affichez-le à côté du prix, surtout lorsque vous servez une valeur en cache ou que le marché est fermé pour le week-end.
• Budgétez votre polling. Interroger l'API toutes les 10 minutes consomme environ 4 500 requêtes par mois, et toutes les minutes environ 45 000. À partir du plan Pro, vous pouvez utiliser le flux en temps réel à la place, et à partir d'Advanced recevoir des alertes de prix par webhook.
• Utilisez des timeouts et des nouvelles tentatives ciblées. Fixez un timeout d'environ 10 secondes, réessayez les erreurs 104 après Retry-After et les erreurs 5xx avec backoff, et ne réessayez jamais les erreurs de validation.
• Validez les symboles en amont. Chargez /symbols une fois au démarrage (c'est gratuit) et rejetez les codes inconnus avant qu'ils ne vous coûtent une requête.

Si vous travaillez avec des assistants IA, le serveur MCP de MetalAPI à l'adresse https://metalapi.com/mcp expose les mêmes données sous forme d'outils : Claude, ChatGPT, Cursor ou VS Code peuvent ainsi consulter le cours de l'or et son historique dans les limites de votre plan ; consultez IA & MCP. Pour chaque endpoint et paramètre, la documentation de l'API fait référence.