API Documentation Overview

Base URL

All API requests should be made to:

https://metalapi.com/api/v1/

All requests must include your API key either as a query parameter or in the Authorization header.

Authentication

MetalAPI uses API keys to authenticate requests. You can view and manage your API keys in your Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

# 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

Latest Rates Endpoint

Returns real-time exchange rate data updated every 60 seconds.

GET /latest?api_key=YOUR_API_KEY

Request Parameters

**api_key** (required): Your API key
**base** (optional): Base currency (default: USD)
**symbols** (optional): Comma-separated list of symbols to filter

Example with parameters:

GET /latest?api_key=YOUR_API_KEY&base=EUR&symbols=XAU,XAG,USD,GBP

Response Format

Successful response:

{
  "success": true,
  "timestamp": 1749752411,
  "base": "USD",
  "rates": {
    "EUR": 0.825533,
    "XAG": 0.036025,
    "XAU": 0.000539,
    "USDEUR": 1.211338,
    "USDXAG": 27.758170,
    "USDXAU": 1856.906765
  },
  "rate_limit": {
    "limit": 10000,
    "remaining": 9876,
    "reset": 1751328000,
    "used": 124,
    "plan": "Basic",
    "reset_date": "2025-07-01T00:00:00.000000Z"
  }
}

Historical Rates Endpoint

Returns historical exchange rate data for a specific date.

GET /historical/{date}?api_key=YOUR_API_KEY

# Example
GET /historical/2025-01-15?api_key=YOUR_API_KEY&symbols=XAU,XAG

Convert Endpoint

Convert any amount from one currency to another using real-time exchange rates.

GET /convert?api_key=YOUR_API_KEY&from=USD&to=XAU&amount=1000

# Response
{
  "success": true,
  "query": {
    "from": "USD",
    "to": "XAU",
    "amount": 1000
  },
  "info": {
    "timestamp": 1749752411,
    "rate": 0.000539
  },
  "result": 0.539
}

Time Series Endpoint

Returns daily historical exchange rate data between two specified dates.

GET /timeseries?api_key=YOUR_API_KEY&start_date=2025-01-01&end_date=2025-01-31&symbols=XAU

Symbols Endpoint

Returns all available currency and metal symbols.

GET /symbols?api_key=YOUR_API_KEY

# Response
{
  "success": true,
  "symbols": {
    "XAU": {
      "description": "Gold",
      "code": "XAU"
    },
    "XAG": {
      "description": "Silver",
      "code": "XAG"
    },
    "EUR": {
      "description": "Euro",
      "code": "EUR"
    }
  }
}

Error Handling

MetalAPI uses conventional HTTP response codes to indicate the success or failure of an API request.

# Invalid API key
{
  "success": false,
  "error": {
    "code": 101,
    "info": "You have not supplied a valid API key."
  }
}

# Rate limit exceeded
{
  "success": false,
  "error": {
    "code": 104,
    "info": "Your monthly API request volume has been reached. Please upgrade your plan."
  }
}

Rate Limiting

API rate limits are enforced based on your subscription plan. Rate limit information is included in every API response:

**Headers:**
- X-RateLimit-Limit: Your plan's monthly limit
- X-RateLimit-Remaining: Requests remaining this month
- X-RateLimit-Reset: Unix timestamp when limit resets

**Response Body:**
Rate limit info is also included in the JSON response under the "rate_limit" key.

Supported Symbols

**Precious Metals:**
- XAU: Gold
- XAG: Silver
- XPT: Platinum
- XPD: Palladium
- XRH: Rhodium

**Major Currencies:**
- USD: US Dollar
- EUR: Euro
- GBP: British Pound
- JPY: Japanese Yen
- CHF: Swiss Franc
- CAD: Canadian Dollar
- AUD: Australian Dollar
- CNY: Chinese Yuan

And 150+ more currencies worldwide.

Widget API

Access widget data programmatically:

GET /widget/data/{widget_id}

# Response
{
  "success": true,
  "data": {
    "rates": {
      "XAU": 1856.90,
      "XAG": 27.75
    },
    "base": "USD",
    "timestamp": 1749752411
  }
}

Code Examples

Complete examples in multiple programming languages:

// Node.js example
const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://metalapi.com/api/v1';

async function getLatestRates() {
  try {
    const response = await axios.get(`${BASE_URL}/latest`, {
      params: {
        api_key: API_KEY,
        symbols: 'XAU,XAG,EUR'
      }
    });
    
    console.log('Gold price:', response.data.rates.XAU);
    console.log('Silver price:', response.data.rates.XAG);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

getLatestRates();

PHP Example

Using PHP with cURL to fetch metal rates:

<?php
$apiKey = 'YOUR_API_KEY';
$symbols = 'XAU,XAG,USD,EUR';

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://metalapi.com/api/v1/latest?api_key={$apiKey}&symbols={$symbols}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  $data = json_decode($response, true);
  echo "Gold Price: $" . $data['rates']['XAU'] . "\n";
  echo "Silver Price: $" . $data['rates']['XAG'] . "\n";
}
?>

Python Example

Using Python requests library:

import requests
import json

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

def get_metal_rates(symbols=None):
    """Fetch latest metal rates from MetalAPI"""
    
    params = {
        'api_key': API_KEY
    }
    
    if symbols:
        params['symbols'] = symbols
    
    try:
        response = requests.get(f'{BASE_URL}/latest', params=params)
        response.raise_for_status()
        
        data = response.json()
        
        if data['success']:
            return data['rates']
        else:
            print(f"Error: {data['error']['info']}")
            return None
            
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

# Example usage
rates = get_metal_rates('XAU,XAG,XPT')
if rates:
    print(f"Gold: ${rates['XAU']}")
    print(f"Silver: ${rates['XAG']}")
    print(f"Platinum: ${rates['XPT']}")

Example Request

Complete example request for currency conversion:

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

Example Response

The API returns the following response format:

{
  "success": true,
  "query": {
    "from": "USD",
    "to": "XAU",
    "amount": 1000
  },
  "info": {
    "timestamp": 1748189445,
    "rate": 0.00053853
  },
  "result": 0.53853,
  "rate_limit": {
    "limit": 10000,
    "remaining": 9995,
    "reset": 1748736000,
    "used": 5,
    "plan": "Standard",
    "reset_date": "2025-06-01T00:00:00.000000Z"
  }
}