API Documentation

Symbols

Get the list of all supported symbols (currencies and metals).

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/symbols"

Example Response

{
  "success": true,
  "symbols": {
    "XAU": "Gold",
    "XAG": "Silver",
    "XPT": "Platinum",
    "XPD": "Palladium",
    "USD": "US Dollar",
    "EUR": "Euro",
    "GBP": "British Pound"
  }
}

Latest Rates

Get the latest rates for all supported symbols.

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG,EUR"

Example Response

{
  "success": true,
  "timestamp": 1748189445,
  "base": "USD",
  "date": "2025-05-27",
  "rates": {
    "XAU": 0.00053853,
    "USDXAU": 1856.906765,
    "XAG": 0.032,
    "USDXAG": 31.25,
    "EUR": 0.8255334,
    "USDEUR": 1.211338027
  }
}

Historical Rates

Get historical rates for a specific date.

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/2024-01-15?base=USD&currencies=XAU,XAG"

Example Response

{
  "success": true,
  "timestamp": 1705363200,
  "historical": true,
  "date": "2024-01-15",
  "base": "USD",
  "rates": {
    "XAU": 0.00053853,
    "USDXAU": 1856.906765,
    "XAG": 0.032,
    "USDXAG": 31.25
  }
}

Convert

Convert one currency to another.

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/convert?from=USD&to=XAU&amount=1000"

Example Response

{
  "success": true,
  "query": {
    "from": "USD",
    "to": "XAU",
    "amount": 1000
  },
  "info": {
    "timestamp": 1748189445,
    "rate": 0.00053853
  },
  "result": 0.53853
}

Timeframe

Get historical rates for a date range (max 365 days).

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/timeframe?start_date=2024-01-01&end_date=2024-01-07&currencies=XAU,XAG"

Example Response

{
  "success": true,
  "timeframe": true,
  "start_date": "2024-01-01",
  "end_date": "2024-01-07",
  "base": "USD",
  "rates": {
    "2024-01-01": {
      "XAU": 0.00053853,
      "USDXAU": 1856.906765,
      "XAG": 0.032,
      "USDXAG": 31.25
    },
    "2024-01-02": {
      "XAU": 0.00053853,
      "USDXAU": 1856.906765,
      "XAG": 0.032,
      "USDXAG": 31.25
    }
  }
}

Change

Calculate rate changes between two dates.

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/change?start_date=2024-01-01&end_date=2024-01-02&currencies=XAU"

Example Response

{
  "success": true,
  "change": true,
  "start_date": "2024-01-01",
  "end_date": "2024-01-02",
  "base": "USD",
  "rates": {
    "XAU": {
      "start_rate": 0.00053853,
      "end_rate": 0.00053853,
      "change": 0,
      "change_pct": 0
    }
  }
}

OHLC

Get Open, High, Low, Close prices for a specific date.

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/ohlc?date=2024-01-01&currencies=XAU"

Example Response

{
  "success": true,
  "ohlc": true,
  "date": "2024-01-01",
  "base": "USD",
  "rates": {
    "XAU": {
      "open": 0.0005277594,
      "high": 0.0005654565,
      "low": 0.0005116035,
      "close": 0.00053853
    }
  }
}

Carat

Get gold prices by carat (available for paid plans).

Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/carat?carat=24"

Example Response

{
  "success": true,
  "carat": "24",
  "date": "2025-05-27",
  "base": "USD",
  "timestamp": 1748336188,
  "rates": {
    "XAU24K": {
      "price": 1856.9,
      "unit": "troy_oz",
      "carat": "24"
    }
  }
}

Usage

Get API usage statistics for your account.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/usage"

Example Response

{
  "success": true,
  "usage": {
    "requests_made": 15,
    "requests_quota": 1000,
    "requests_remaining": 985,
    "plan": "lite"
  }
}

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const baseUrl = 'http://www.metalapi.com/api/v1';

// Get latest rates
async function getLatestRates() {
  try {
    const response = await axios.get(`${baseUrl}/latest`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      },
      params: {
        base: 'USD',
        currencies: 'XAU,XAG,EUR'
      }
    });
    
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Convert currency
async function convertCurrency() {
  try {
    const response = await axios.get(`${baseUrl}/convert`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      },
      params: {
        from: 'USD',
        to: 'XAU',
        amount: 1000
      }
    });
    
    console.log(`1000 USD = ${response.data.result} XAU`);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

getLatestRates();
convertCurrency();

Python

import requests
import json

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'http://www.metalapi.com/api/v1'

def get_latest_rates():
    """Get latest exchange rates"""
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }
    
    params = {
        'base': 'USD',
        'currencies': 'XAU,XAG,EUR'
    }
    
    response = requests.get(f'{BASE_URL}/latest', headers=headers, params=params)
    
    if response.status_code == 200:
        data = response.json()
        print(json.dumps(data, indent=2))
    else:
        print(f'Error: {response.status_code}')
        print(response.json())

def convert_currency(from_currency, to_currency, amount):
    """Convert one currency to another"""
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }
    
    params = {
        'from': from_currency,
        'to': to_currency,
        'amount': amount
    }
    
    response = requests.get(f'{BASE_URL}/convert', headers=headers, params=params)
    
    if response.status_code == 200:
        data = response.json()
        print(f'{amount} {from_currency} = {data["result"]} {to_currency}')
    else:
        print(f'Error: {response.status_code}')
        print(response.json())

# Example usage
get_latest_rates()
convert_currency('USD', 'XAU', 1000)

PHP

Error: 0
null

cURL

# Get latest rates
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG,EUR"

# Get historical rates
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/2024-01-15?base=USD&currencies=XAU,XAG"

# Convert currency
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/convert?from=USD&to=XAU&amount=1000"

# Get timeframe data
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/timeframe?start_date=2024-01-01&end_date=2024-01-07&currencies=XAU"

# Get usage statistics
curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://www.metalapi.com/api/v1/usage"

MetalAPI provides embeddable widgets that allow you to display real-time metal and currency rates directly on your website. Our widgets are fully customizable, responsive, and automatically update based on your subscription plan.

Widget Generator

Use our interactive widget generator to create customized widgets for your website. The generator provides a live preview and generates the embed code for you.

Integration Guide

Integrating MetalAPI widgets into your website is simple and requires just a few lines of code.

<script src="http://www.metalapi.com/js/widget.js"></script>

<div id="my-metal-widget"></div>

<script>
new MetalAPIWidget({
    widgetId: 'my-metal-widget',
    apiKey: 'YOUR_API_KEY',
    baseUrl: 'http://www.metalapi.com',
    symbols: ['XAU', 'XAG', 'XPT'],
    type: 'metal',
    theme: 'light',
    size: 'medium',
    showChange: true,
    showPercentage: true,
    autoRefresh: true
});
</script>

Configuration Options

Live Examples

Here are some live examples of MetalAPI widgets in different configurations:

theme: 'light', size: 'medium'

theme: 'dark', size: 'large'

theme: 'blue', size: 'small'

Advanced Usage

// Metal prices widget
const metalWidget = new MetalAPIWidget({
    widgetId: 'metals',
    apiKey: 'your-key',
    baseUrl: 'http://www.metalapi.com',
    symbols: ['XAU', 'XAG'],
    type: 'metal',
    theme: 'light'
});

// Currency rates widget
const currencyWidget = new MetalAPIWidget({
    widgetId: 'currencies',
    apiKey: 'your-key',
    baseUrl: 'http://www.metalapi.com',
    symbols: ['USD', 'EUR'],
    type: 'currency',
    theme: 'dark'
});

// Manually refresh data
widget.refresh();

// Update configuration
widget.updateConfig({
    symbols: ['XAU', 'XAG', 'XPT'],
    theme: 'dark'
});

// Destroy widget
widget.destroy();

const widget = new MetalAPIWidget({
    // ... configuration
    onDataUpdate: function(data) {
        console.log('Widget data updated:', data);
    },
    onError: function(error) {
        console.error('Widget error:', error);
    }
});