Descripción general de la documentación de la API
Un recorrido en una página por la API REST de MetalAPI: URL base, autenticación, parámetros, formato de respuesta, errores, límites y ejemplos de código.
URL base
Todas las solicitudes van a https://metalapi.com/api/v1/ mediante HTTPS y usan GET. Las respuestas son JSON con un indicador success.
Esta página es un recorrido rápido. La referencia completa con todos los parámetros está en la documentación de la API.
Autenticación
Envía tu clave API como parámetro de consulta, como token Bearer o en una cabecera X-API-Key. Las claves tienen el formato mk_live_ seguido de 32 caracteres. Mantenlas en secreto; consulta Autenticación.
# Parámetro de consulta
GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY
# Cabecera Authorization
GET https://metalapi.com/api/v1/latest
Authorization: Bearer YOUR_API_KEY
# Cabecera X-API-Key
GET https://metalapi.com/api/v1/latest
X-API-Key: YOUR_API_KEYEndpoints
/latest: precios actuales/{YYYY-MM-DD},/yesterdayo/historical?date=: precios de cierre de un día pasado/convert?from=&to=&amount=: convierte cualquier importe, opcionalmente a unadatepasada/timeframe?start_date=&end_date=(alias/timeseries): precios diarios de un rango de fechas/change?start_date=&end_date=: variación entre dos días/ohlc?date=: apertura, máximo, mínimo y cierre de un día/carat?carat=24ocarat=all: precios del oro por quilate (planes de pago)/symbols: símbolos admitidos (gratuito, no consume cuota)/usage: tu cuota (gratuito, no consume cuota)/stream: Server-Sent Events en tiempo real (plan Pro y superiores)
Encontrarás los parámetros y ejemplos de cada uno en Endpoints disponibles.
Parámetros de la solicitud
api_key: tu clave, salvo que la envíes en una cabecerabase: la divisa de los precios devueltos,USDpor defectocurrenciesosymbols: símbolos separados por comas que se devolverán. Todos los símbolos por defecto.unit: unidad de masa de los metales. Uno detroy_oz(por defecto),gram,kilogram,ounce,pound,metric_tonoshort_ton.
GET /api/v1/latest?api_key=YOUR_API_KEY&base=EUR¤cies=XAU,XAG,USD,GBP&unit=gramFormato de respuesta
Las respuestas correctas incluyen success: true, los datos y un bloque rate_limit. Cada símbolo aparece dos veces: XAU (onzas troy por cada unidad de la divisa base) y USDXAU (el precio de una onza troy en la divisa base). Consulta Formatos de datos y unidades.
{
"success": true,
"timestamp": 1792765800,
"date": "2026-10-23",
"base": "USD",
"rates": {
"EUR": 0.8589589418,
"USDEUR": 1.1642,
"XAG": 0.01853911754,
"USDXAG": 53.94,
"XAU": 0.0002501319446,
"USDXAU": 3997.89
},
"rate_limit": {
"limit": 10000,
"remaining": 9876,
"reset": 1793491200,
"used": 124,
"plan": "Standard",
"reset_date": "2026-11-01T00:00:00.000Z"
}
}Errores
Los errores devuelven un código de estado HTTP de error y un cuerpo success: false con un código numérico, un tipo y un mensaje. La lista completa está en Manejo de errores.
{
"success": false,
"error": {
"code": 102,
"type": "invalid_api_key",
"info": "User did not supply an access key or supplied an invalid access key"
}
}Límites de solicitudes
Cada plan tiene una cuota mensual, que se restablece el día 1 a las 00:00 UTC, y un límite por minuto. Cada respuesta autenticada incluye:
X-RateLimit-Limit,X-RateLimit-RemainingyX-RateLimit-Usedpara la cuota mensualX-RateLimit-ResetyX-RateLimit-Reset-Datepara saber cuándo se restablece la cuotaX-RateLimit-Plancon el nombre de tu planX-RateLimit-Minute-LimityX-RateLimit-Minute-Remainingpara el límite por minuto
Los mismos valores están en el bloque JSON rate_limit. Consulta Límites de solicitudes y planes.
Símbolos admitidos
- Metales preciosos:
XAU,XAG,XPT,XPD - Metales industriales:
XCU,ALU,ZNC,HRC - Energía:
WTI,BRENT,NATURALGAS,GASOLINE,HEATINGOIL - Divisas: unas 55, entre ellas
USD,EUR,GBP,JPY,CHF,CAD,AUDyCNY - Criptomonedas: 13 monedas, entre ellas
BTC,ETH,SOL,USDTyUSDC
Consúltalos todos en la página de símbolos.
Ejemplo en Node.js
Con el fetch integrado (Node.js 18+):
const API_KEY = process.env.METALAPI_KEY;
const BASE_URL = "https://metalapi.com/api/v1";
async function getLatestRates(currencies = "XAU,XAG,EUR") {
const res = await fetch(`${BASE_URL}/latest?currencies=${currencies}`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.error.code}: ${data.error.info}`);
return data.rates;
}
const rates = await getLatestRates();
console.log("Gold (USD/oz):", rates.USDXAU);
console.log("Silver (USD/oz):", rates.USDXAG);Ejemplo en PHP
Con PHP y cURL:
<?php
$apiKey = getenv('METALAPI_KEY');
$curl = curl_init('https://metalapi.com/api/v1/latest?currencies=XAU,XAG');
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ["X-API-Key: {$apiKey}"],
]);
$response = curl_exec($curl);
$error = curl_error($curl);
curl_close($curl);
if ($error) {
exit("cURL error: {$error}\n");
}
$data = json_decode($response, true);
if (!$data['success']) {
exit("API error {$data['error']['code']}: {$data['error']['info']}\n");
}
echo "Gold (USD/oz): " . $data['rates']['USDXAU'] . "\n";
echo "Silver (USD/oz): " . $data['rates']['USDXAG'] . "\n";Ejemplo en Python
Con la biblioteca requests:
import os
import requests
API_KEY = os.environ["METALAPI_KEY"]
BASE_URL = "https://metalapi.com/api/v1"
def get_metal_rates(currencies="XAU,XAG,XPT"):
"""Fetch the latest metal prices from MetalAPI."""
response = requests.get(
f"{BASE_URL}/latest",
params={"currencies": currencies},
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = response.json()
if not data["success"]:
raise RuntimeError(f"{data['error']['code']}: {data['error']['info']}")
return data["rates"]
rates = get_metal_rates()
print(f"Gold: {rates['USDXAU']} USD/oz")
print(f"Silver: {rates['USDXAG']} USD/oz")
print(f"Platinum: {rates['USDXPT']} USD/oz")Ejemplo de solicitud
Conversión de 1000 dólares estadounidenses a onzas troy de oro:
curl "https://metalapi.com/api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000"Ejemplo de respuesta
result es el importe convertido e info.rate, la cotización que se aplicó:
{
"success": true,
"query": { "from": "USD", "to": "XAU", "amount": 1000 },
"info": { "timestamp": 1792765800, "rate": 0.0002501319446, "quote": 0.0002501319446 },
"date": "2026-10-23",
"result": 0.2501319446,
"rate_limit": {
"limit": 10000,
"remaining": 9876,
"reset": 1793491200,
"used": 124,
"plan": "Standard",
"reset_date": "2026-11-01T00:00:00.000Z"
}
}Guías relacionadas
¿Listo para empezar a desarrollar?
Crea una cuenta gratuita para obtener tu clave API o explora todos los endpoints en la referencia de la API.