API Documentation Overview

A one-page tour of the MetalAPI REST API: base URL, authentication, parameters, response format, errors, rate limits and code examples.

API reference 10 min read

Base URL

All requests go to https://metalapi.com/api/v1/ over HTTPS and use GET. Responses are JSON with a success flag.

This page is a quick tour. The complete reference with every parameter is in the API documentation.

Authentication

Send your API key as a query parameter, a Bearer token or an X-API-Key header. Keys look like mk_live_ followed by 32 characters. Keep them secret; see Authentication.

http

# Query parameter
GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY

# Authorization header
GET https://metalapi.com/api/v1/latest
Authorization: Bearer YOUR_API_KEY

# X-API-Key header
GET https://metalapi.com/api/v1/latest
X-API-Key: YOUR_API_KEY

Endpoints

/latest: current prices
/{YYYY-MM-DD}, /yesterday or /historical?date=: closing prices of a past day
/convert?from=&to=&amount=: convert any amount, optionally at a past date
/timeframe?start_date=&end_date= (alias /timeseries): daily prices for a date range
/change?start_date=&end_date=: change between two days
/ohlc?date=: open, high, low and close of a day
/carat?carat=24 or carat=all: gold prices by karat (paid plans)
/symbols: supported symbols (free, no quota)
/usage: your quota (free, no quota)
/stream: realtime Server-Sent Events (Pro plan and above)

Parameters and examples for each one are in Available endpoints.

Request parameters

api_key: your key, unless you send it in a header
base: the currency of the returned prices, USD by default
currencies or symbols: comma-separated symbols to return. All symbols by default.
unit: mass unit for metals. One of troy_oz (default), gram, kilogram, ounce, pound, metric_ton or short_ton.

http

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

Response format

Successful responses include success: true, the data, and a rate_limit block. Each symbol appears twice: XAU (troy ounces per one unit of the base currency) and USDXAU (the base-currency price of one troy ounce). See Data formats & units.

json

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

Errors

Errors return an HTTP error status and a success: false body with a numeric code, a type and a message. The full list is in Error handling.

json

{
  "success": false,
  "error": {
    "code": 102,
    "type": "invalid_api_key",
    "info": "User did not supply an access key or supplied an invalid access key"
  }
}

Rate limiting

Each plan has a monthly quota, which resets on the 1st at 00:00 UTC, and a per-minute limit. Every authenticated response includes:

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Used for the monthly quota
X-RateLimit-Reset and X-RateLimit-Reset-Date for when the quota resets
X-RateLimit-Plan with your plan name
X-RateLimit-Minute-Limit and X-RateLimit-Minute-Remaining for the per-minute limit

The same values are in the rate_limit JSON block. See Rate limits & plans.

Supported symbols

Precious metals: XAU, XAG, XPT, XPD
Industrial metals: XCU, ALU, ZNC, HRC
Energy: WTI, BRENT, NATURALGAS, GASOLINE, HEATINGOIL
Currencies: around 55, including USD, EUR, GBP, JPY, CHF, CAD, AUD and CNY
Crypto: 13 coins, including BTC, ETH, SOL, USDT and USDC

Browse them all on the symbols page.

Node.js example

Using the built-in fetch (Node.js 18+):

javascript

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

PHP example

Using PHP with cURL:

php

<?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";

Python example

Using the requests library:

python

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")

Example request

Converting 1,000 US dollars into troy ounces of gold:

bash

curl "https://metalapi.com/api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000"

Example response

result is the converted amount and info.rate the rate that was applied:

json

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

Available EndpointsEvery MetalAPI endpoint and its parameters: latest, historical, convert, timeframe, change, OHLC, carat, symbols, usage and stream.9 min read Error HandlingMetalAPI error codes, their HTTP status codes, and how to handle and retry failed requests.6 min read Data Formats & UnitsHow rates are expressed, choosing a base currency and mass unit, bid/ask and karat prices, timestamps and market hours.8 min read

Ready to start building?

Create a free account to get your API key, or explore every endpoint in the API reference.

Get your free API key API documentation

API Documentation Overview

A one-page tour of the MetalAPI REST API: base URL, authentication, parameters, response format, errors, rate limits and code examples.

API reference 10 min read

Base URL

All requests go to https://metalapi.com/api/v1/ over HTTPS and use GET. Responses are JSON with a success flag.

This page is a quick tour. The complete reference with every parameter is in the API documentation.

Authentication

Send your API key as a query parameter, a Bearer token or an X-API-Key header. Keys look like mk_live_ followed by 32 characters. Keep them secret; see Authentication.

http

# Query parameter
GET https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY

# Authorization header
GET https://metalapi.com/api/v1/latest
Authorization: Bearer YOUR_API_KEY

# X-API-Key header
GET https://metalapi.com/api/v1/latest
X-API-Key: YOUR_API_KEY

Endpoints

/latest: current prices
/{YYYY-MM-DD}, /yesterday or /historical?date=: closing prices of a past day
/convert?from=&to=&amount=: convert any amount, optionally at a past date
/timeframe?start_date=&end_date= (alias /timeseries): daily prices for a date range
/change?start_date=&end_date=: change between two days
/ohlc?date=: open, high, low and close of a day
/carat?carat=24 or carat=all: gold prices by karat (paid plans)
/symbols: supported symbols (free, no quota)
/usage: your quota (free, no quota)
/stream: realtime Server-Sent Events (Pro plan and above)

Parameters and examples for each one are in Available endpoints.

Request parameters

api_key: your key, unless you send it in a header
base: the currency of the returned prices, USD by default
currencies or symbols: comma-separated symbols to return. All symbols by default.
unit: mass unit for metals. One of troy_oz (default), gram, kilogram, ounce, pound, metric_ton or short_ton.

http

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

Response format

json

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

Errors

Errors return an HTTP error status and a success: false body with a numeric code, a type and a message. The full list is in Error handling.

json

{
  "success": false,
  "error": {
    "code": 102,
    "type": "invalid_api_key",
    "info": "User did not supply an access key or supplied an invalid access key"
  }
}

Rate limiting

Each plan has a monthly quota, which resets on the 1st at 00:00 UTC, and a per-minute limit. Every authenticated response includes:

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Used for the monthly quota
X-RateLimit-Reset and X-RateLimit-Reset-Date for when the quota resets
X-RateLimit-Plan with your plan name
X-RateLimit-Minute-Limit and X-RateLimit-Minute-Remaining for the per-minute limit

The same values are in the rate_limit JSON block. See Rate limits & plans.

Supported symbols

Precious metals: XAU, XAG, XPT, XPD
Industrial metals: XCU, ALU, ZNC, HRC
Energy: WTI, BRENT, NATURALGAS, GASOLINE, HEATINGOIL
Currencies: around 55, including USD, EUR, GBP, JPY, CHF, CAD, AUD and CNY
Crypto: 13 coins, including BTC, ETH, SOL, USDT and USDC

Browse them all on the symbols page.

Node.js example

Using the built-in fetch (Node.js 18+):

javascript

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

PHP example

Using PHP with cURL:

php

<?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";

Python example

Using the requests library:

python

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")

Example request

Converting 1,000 US dollars into troy ounces of gold:

bash

curl "https://metalapi.com/api/v1/convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000"

Example response

result is the converted amount and info.rate the rate that was applied:

json

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

Ready to start building?

Create a free account to get your API key, or explore every endpoint in the API reference.

Get your free API key API documentation

Base URL

Authentication

Endpoints

Request parameters

Response format

Errors

Rate limiting

Supported symbols

Node.js example

PHP example

Python example

Example request

Example response

Related guides

Ready to start building?

Base URL

Authentication

Endpoints

Request parameters

Response format

Errors

Rate limiting

Supported symbols

Node.js example

PHP example

Python example

Example request

Example response

Related guides

Ready to start building?