Formats de données et unités

Deux sens pour chaque taux

Pour chaque symbole demandé, rates contient deux valeurs. Pour l'or (XAU) avec la base USD :

• USDXAU : le prix d'une once troy d'or en dollars américains, par exemple 3997.89. C'est la valeur à présenter à vos utilisateurs.
• XAU : l'inverse, c'est-à-dire le nombre d'onces troy d'or pour un dollar américain, par exemple 0.0002501319446. Ce format est conservé pour la compatibilité avec les API de type forex.

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 pour un dollar.

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89,
    "EUR": 0.8589589418,
    "USDEUR": 1.1642
  }
}

Choisir une devise de base

base définit la devise de tous les prix de la réponse. Sa valeur par défaut est USD et elle accepte n'importe quel symbole pris en charge : EUR, GBP, JPY, voire BTC ou XAU si vous voulez valoriser des actifs en bitcoin ou en or. Les taux croisés sont calculés à partir du même instantané : ils sont donc toujours cohérents entre eux.

Cette requête renvoie EURXAU, le prix de l'or en euros par once troy :

GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR&currencies=XAU,XAG

Unités de masse

Les prix des métaux sont exprimés par once troy (31,1035 g), sauf si vous passez unit. Valeurs prises en charge :

• troy_oz (par défaut), gram, kilogram, ounce (avoirdupois, 28,35 g), pound, metric_ton et short_ton

Les formes abrégées comme g, kg, lb et tonne sont également acceptées. Attention : oz désigne l'once avoirdupois. Utilisez troy_oz, ou omettez unit, pour obtenir l'once troy dans laquelle les lingots sont cotés.

unit s'applique uniquement aux métaux précieux et industriels. L'énergie reste exprimée par baril, MMBtu ou gallon, et les devises et cryptos ne sont pas concernées. Lorsqu'une unité autre que celle par défaut est utilisée, la réponse inclut un champ unit. Pour GET /api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram :

{
  "success": true,
  "timestamp": 1792765800,
  "date": "2026-10-23",
  "base": "EUR",
  "unit": "gram",
  "rates": {
    "XAU": 0.009057444725,
    "EURXAU": 110.4064149,
    "XAG": 0.6713138244,
    "EURXAG": 1.489616277
  }
}

Métaux industriels et énergie

Les métaux industriels (XCU cuivre, ALU aluminium, ZNC zinc et HRC acier laminé à chaud) sont cotés par défaut à l'once troy, comme tous les autres métaux, ce qui permet de comparer directement tous les métaux entre eux. Pour obtenir l'unité dans laquelle chaque marché se négocie, passez unit=pound pour le cuivre, unit=metric_ton pour l'aluminium et le zinc, et unit=short_ton pour l'acier.

Les prix de l'énergie sont exprimés par unité de contrat : WTI et BRENT par baril, NATURALGAS par MMBtu, et GASOLINE et HEATINGOIL par gallon.

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XCU&unit=pound

Symboles pris en charge

• Métaux précieux : XAU or, XAG argent, XPT platine, XPD palladium
• Métaux industriels : XCU cuivre, ALU aluminium, ZNC zinc, HRC acier
• Énergie : WTI, BRENT, NATURALGAS, GASOLINE, HEATINGOIL
• Devises : environ 55 devises ISO 4217, dont USD, EUR, GBP, JPY, CHF, CAD, AUD, CNY et INR
• Cryptos : BTC, ETH, SOL, XRP, BNB, ADA, DOGE, DOT, LINK, LTC, TRX, USDT, USDC

La liste complète et à jour figure sur la page des symboles et est disponible via /api/v1/symbols.

Prix bid et ask

À partir du plan Standard, ajoutez -BID ou -ASK à un symbole dans currencies pour recevoir les prix acheteur (bid) et vendeur (ask) en plus du prix moyen. Ils sont disponibles pour les symboles cotés à partir de flux interbancaires, c'est-à-dire les métaux précieux et les principales devises. Pour currencies=XAU,XAU-BID,XAU-ASK :

"rates": {
  "XAU": 0.0002501319446,
  "USDXAU": 3997.89,
  "XAU-BID": 0.0002501488386,
  "USDXAU-BID": 3997.62,
  "XAU-ASK": 0.0002501150529,
  "USDXAU-ASK": 3998.16
}

Prix de l'or par carat

/carat renvoie les prix de l'or aux titres utilisés en bijouterie, le titre valant carat ÷ 24, dans n'importe quelle devise et unité. Il est disponible sur les plans payants. Pour GET /api/v1/carat?carat=all&unit=gram (extrait) :

{
  "success": true,
  "carat": "all",
  "date": "2026-10-23",
  "base": "USD",
  "timestamp": 1792765800,
  "rates": {
    "XAU24K": { "price": 128.53515, "unit": "gram", "carat": "24", "purity": 1 },
    "XAU22K": { "price": 117.82389, "unit": "gram", "carat": "22", "purity": 0.916667 },
    "XAU18K": { "price": 96.401361, "unit": "gram", "carat": "18", "purity": 0.75 },
    "XAU14K": { "price": 74.978836, "unit": "gram", "carat": "14", "purity": 0.583333 }
  }
}

Horodatages et dates

timestamp est l'heure Unix en secondes (UTC) des prix renvoyés. date est le même jour au format YYYY-MM-DD, en UTC. Les réponses historiques sont horodatées à 00:00 UTC du jour demandé et contiennent les prix de clôture de ce jour.

const date = new Date(data.timestamp * 1000);
console.log(date.toISOString()); // 2026-10-23T14:30:00.000Z

Précision

Les taux sont des nombres JSON comportant jusqu'à 10 chiffres significatifs, ce qui suffit pour des taux inverses comme 0.0002501319446. N'arrondissez qu'au moment d'afficher une valeur, pas avant de l'utiliser dans un calcul.

Horaires des marchés et week-ends

Les métaux au comptant et les devises se négocient 24 heures sur 24 en semaine. Les marchés ferment le vendredi à 17:00, heure de New York, et rouvrent le dimanche à 17:00. Pendant le week-end, les prix restent figés sur la dernière cotation et l'API continue de renvoyer le prix de clôture du vendredi (les pages des symboles affichent « Marché fermé »).

Les cryptos se négocient 24 h/24, 7 j/7 et continuent d'être mises à jour le week-end. Les métaux industriels et l'énergie suivent les horaires de négociation de leurs bourses de contrats à terme.