Official Libraries

We offer official libraries in multiple programming languages.

Learn More
Offical WordPress Integration

Integrate easily into WordPress with our offical WordPress plugin.

GET

Quick Start

https://api.metalpriceapi.com/v1/latest?api_key=[API_KEY]

MetalpriceAPI

MetalpriceAPI provides a simple to use JSON-based REST API for live and historical precious metals and foreign exchange (forex) rates in 145 world currencies. We provide affordable pricing, which makes our API perfect for businesses of any size including startups, online businesses, to large companies in need of live and/or historical financial data.

Our API can be deployed to power financial departments, mobile applications, and back-office systems around the world just to name a few use cases.

List of supported symbols

Video Tutorials


Definitions

Definition Description
API Key Uniquely assigned key to each API account to authenticate interactions with the API.
Symbol Three-letter currency code or metal code of a given currency.
Base Currency The currency to which exchange rates are relative to.
Quote Currency The currency an amount is converted to.

Metal Units

All metal rates are expressed in per troy ounce. We offer carat, grams, kilograms for any paid plans. Get in touch to learn more.

Live Rate Delay

Live exchange rate data is delayed based on your subscription plan.

Subscription Plan Delay
Free 60 minutes
Basic 10 minutes
Professional 60 seconds
Business 60 seconds

API Key

The MetalpriceAPI uses API keys to authenticate requests. You can view and manage your API key in the dashboard.

Please ensure to keep your API Key private as each request made with your API Key counts towards your account's plan limit.

To make an successful request, you must pass in your API Key into every request

We provide two ways to pass in your API Key for every request. Method one is to append your API Key to the request url. Method two is to pass in the API Key via the request header.

Method 1:

https://api.metalpriceapi.com/v1/latest?api_key=API_KEY

Method 2:

curl https://api.metalpriceapi.com/v1/latest \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json'

API Quota

To determine your current request quota, you can take a look at the response header after a request.

Response Headers

Key Description
X-API-CURRENT Number of requests consumed for the month.
X-API-QUOTA API quota limit for the month based on your account plan.

API Endpoints

We offer 7 customizable endpoints, all which provides you access to different kinds of data. Below you will find a short summary of all available endpoints. Detailed explaination of any of the endpoints below will be provided in API Features.

// "symbols" - get list of all supported currencies
https://api.metalpriceapi.com/v1/symbols

// "latest" - get real-time exchange rate data for all available/specific currencies
https://api.metalpriceapi.com/v1/latest

// "historical" - get historical rates for a specific day
https://api.metalpriceapi.com/v1/YYYY-MM-DD

// "convert" - convert one currency to another based on real-time or historic exchange rate data
https://api.metalpriceapi.com/v1/convert?from=USD&to=XAU&amount=100

// "timeframe" - request exchange rates for a specific period of time
https://api.metalpriceapi.com/v1/timeframe?start_date=2021-01-01&end_date=2021-05-01

// "change" - request any currency change parameters (margin, percentage)
https://api.metalpriceapi.com/v1/change?base=XAU&start_date=2021-01-01&end_date=2021-05-01

// "carat" - request gold prices by Carat
https://api.metalpriceapi.com/v1/carat

API Error Codes

If your query fails, the API will return a 3-digit error-code and a plain text "info" property.

Example Error

{
  "success": false,
  "error": {
      "code": 104,
      "info": "Your monthly usage limit has been reached. Please upgrade your subscription plan."
  }
}

Common API Errors

Error Code Description
404 User requested a non-existent API function
101 User did not supply an API Key
102 User did not supply an access key or supplied an invalid access key
103 The user's account is not active. User will be prompted to get in touch with Customer Support
104 Too May Requests
105 User has reached or exceeded his subscription plan's monthly API request allowance
201 User entered an invalid Base Currency [ latest, historical, timeframe, change ]
202 User entered an invalid from Currency [ convert ]
203 User entered invalid to currency [ convert ]
204 User entered invalid amount [ convert ]
205 User entered invalid date [ historical, convert, timeframe, change ]
206 Invalid timeframe [ timeframe, change ]
207 Timeframe exceeded 365 days [ timeframe ]
300 The user's query did not return any results [ latest, historical, convert, timeframe, change ]

CORS (Cross-Origin Resource Sharing)

MetalpriceAPI supports Access-Control (CORS) headers. This means you will be able to use our API via Cross-Origin HTTPS Requests. Learn more.


Supported Symbols

This endpoint is used to get the list of the most up-to-date supported symbols. Learn more here.

Example API Request

https://api.metalpriceapi.com/v1/symbols
?api_key=[API_KEY]

Request Parameters

Parameter Description
api_key [Required] Your API Key. More details.

Example API Response

{
  "success": true,
  "symbols": {
      "AED": "UAE Dirham",
      "AFN": "Afghan Afghani",
      "ALL": "Albanian Lek",
      ...
  }
}

Response Attributes

Attribute Description
success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.
symbols Key is supported currency, value is description of currency.

Live Rates

This endpoint will return real-time exchange rate data (delayed) depending on your subscription plan.

Example API Request

https://api.metalpriceapi.com/v1/latest
?api_key=[API_KEY]
&base=USD
&currencies=EUR,XAU,XAG

Request Parameters

Parameter Description
api_key [Required] Your API Key. More details.
base [optional] Specify a base currency. Base Currency will default to USD if this parameter is not defined.
currencies [optional] Specify a comma-separated list of currency codes to limit API responses to specified currencies. If this parameter is not defined, the API will return all supported currencies.
units [optional] Specify troy_oz or gram or kilogram. If not defined, the API will return metals in troy ounce.

Example API Response

{
  "success": true,
  "base": "USD",
  "timestamp": 1625609377,
  "rates": {
      "EUR": 0.8255334,
      "XAG": 0.03602543,
      "XAU": 0.00053853
  }
}

In the example API response, that means:
1 USD (Base) = 0.8255334 EUR (Quote)
1 USD (Base) = 0.03602543 Ounce of XAG (Quote)
1 USD (Base) = 0.00053853 Ounce of XAU (Quote)

You can also express the reciprocal:
1/0.8255334 EUR = 1.211 USD (Base) <=> €1 = $1.211
1/0.03602543 XAG = 27.758 USD (Base) <=> 1 Ounce of XAU (Silver) = $27.758
1/0.00053853 XAU = 1856.906 USD (Base) <=> 1 Ounce of XAU (Gold) = $1856.906

Response Attributes

Attribute Description
success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.
base Returns base currency used for the request.
timestamp Returns the UNIX timestamp the given exchange rates were collected.
rates Returns exchange rate data for the currencies requested.

Historical Rates

This endpoint will return historical exchange rate data. Use format YYYY-MM-DD for the base url.

Example API Request

https://api.metalpriceapi.com/v1/2021-03-24
?api_key=[API_KEY]
&base=USD
&currencies=EUR,XAU,XAG

Request Parameters

Parameter Description
api_key [Required] Your API Key. More details.
base [optional] Specify a base currency. Base Currency will default to USD if this parameter is not defined.
currencies [optional] Specify a comma-separated list of currency codes to limit API responses to specified currencies. If this parameter is not defined, the API will return all supported currencies.

Example API Response

{
  "success": true,
  "base": "USD",
  "timestamp": 1616558399,
  "rates": {
      "EUR": 0.8255334,
      "XAG": 0.03602543,
      "XAU": 0.00053853
  }
}

In the example API response, that means:
1 USD (Base) = 0.8255334 EUR (Quote)
1 USD (Base) = 0.03602543 Ounce of XAG (Quote)
1 USD (Base) = 0.00053853 Ounce of XAU (Quote)

You can also express the reciprocal:
1/0.8255334 EUR = 1.211 USD (Base) <=> €1 = $1.211
1/0.03602543 XAG = 27.758 USD (Base) <=> 1 Ounce of XAU (Silver) = $27.758
1/0.00053853 XAU = 1856.906 USD (Base) <=> 1 Ounce of XAU (Gold) = $1856.906

Response Attributes

Attribute Description
success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.
base Returns base currency used for the request.
timestamp Returns the UNIX timestamp the given exchange rates were collected.
rates Returns exchange rate data for the currencies requested.

Currency Convert

This endpoint is used to convert any amount from one currency to another.

Example API Request

https://api.metalpriceapi.com/v1/convert
?api_key=[API_KEY]
&from=USD
&to=XAU
&amount=100
&date=2021-04-23

Request Parameters

Parameter Description
api_key [Required] Your API Key. More details.
from [optional] Specify currency you would like to convert from. Base Currency will default to USD if this parameter is not defined.
to [Required] Specify currency you would like to convert to.
amount [Required] The amount to convert.
date [optional] Specify date to use historical midpoint value for conversion. Otherwise, it will use live exchange rate date with delay specified based on your subscription plan.

Example API Response

{
  "success": true,
  "query": {
      "from": "USD",
      "to": "XAU",
      "amount": 100
  },
  "info": {
      "quote": 0.0005628,
      "timestamp": 1619150400
  },
  "result": 0.05628031
}

Response Attributes

Attribute Description
success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.
query -> from Returns currency converted from used for the request.
query -> to Returns currency converted to used for the request.
query -> amount Returns amount to convert.
info -> quote Returns the exchange rate used for the conversion.
info -> timestamp Returns the UNIX timestamp the given exchange rates were collected.
result Returns conversion result.

Timeframe Query

This endpoint is used to get historical rates for a specified time period (max range: 365 days).

Example API Request

https://api.metalpriceapi.com/v1/timeframe
?api_key=[API_KEY]
&start_date=2021-04-22
&end_date=2021-04-23
&base=USD
&currencies=EUR,XAU,XAG

Request Parameters

Parameter Description
api_key [Required] Your API Key. More details.
start_date [Required] Specify the start date of your timeframe.
end_date [Required] Specify the end date of your timeframe.
base [optional] Specify a base currency. Base Currency will default to USD if this parameter is not defined.
currencies [optional] Specify a comma-separated list of currency codes to limit API responses to specified currencies. If this parameter is not defined, the API will return all supported currencies.

Example API Response

{
  "success": true,
  "base": "USD",
  "start_date": "2021-04-22",
  "end_date": "2021-04-23",
  "rates": {
      "2021-04-22": {
        "EUR": 0.83233837,
        "XAG": 0.03825732,
        "XAU": 0.00056078
      },
      "2021-04-23": {
        "EUR": 0.82657397,
        "XAG": 0.03846131,
        "XAU": 0.0005628
      },
  }

Response Attributes

Attribute Description
success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.
base Returns base currency used for the request.
start_date Returns start date of your timeframe for the request.
end_date Returns end date of your timeframe for the request.
rates Returns exchange rate data for the currencies requested.

Change Query

This endpoint is used to request the change (percentage) of one of more currencies, relative to a base currency with a specific time-frame (optional).

If you do not specify a time-frame, the API will automatically default to returning change values ranging from yesterday's EOD (End of Day) data and to the latest live available exchange rates of today.

If you specify a time-frame, the API will return change values of the specified start_date and end_date.

Example API Request

https://api.metalpriceapi.com/v1/change
?api_key=[API_KEY]
&start_date=2021-04-22
&end_date=2021-04-23
&base=USD
&currencies=XAU

Request Parameters

Parameter Description
api_key [Required] Your API Key. More details.
start_date [Required] Specify the start date of your timeframe.
end_date [Required] Specify the end date of your timeframe.
base [optional] Specify a base currency. Base Currency will default to USD if this parameter is not defined.
currencies [optional] Specify a comma-separated list of currency codes to limit API responses to specified currencies. If this parameter is not defined, the API will return all supported currencies.

Example API Response

{
  "success": true,
  "base": "USD",
  "start_date": "2021-04-20",
  "end_date": "2021-04-21",
  "rates": {
      "XAU": {
        "start_rate": 0.00059101,
        "end_rate": 0.00059256,
        "change": 0.00000155,
        "change_pct": 0.2623
      }
  }

Response Attributes

Attribute Description
success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.
base Returns base currency used for the request.
start_date Returns start date of your timeframe for the request.
end_date Returns end date of your timeframe for the request.
rates -> start_rate Returns exchange rate for the start date.
rates -> end_rate Returns exchange rate for the end date.
rates -> change Returns change (decimal number) of the given currency rate between the start and end date.
rates -> change_pct Returns percent change of the given currency rate between your start and end date. Formula used is ((end_rate - start_rate) / start_rate) * 100

Carat Query (Paid plan)

This endpoint is used to request the gold rate by Carat.

Example API Request

https://api.metalpriceapi.com/v1/carat
?api_key=[API_KEY]
&base=USD
&date=2021-04-23

Request Parameters

Parameter Description
api_key [Required] Your API Key. More details.
base [optional] Specify a base currency. Base Currency will default to USD if this parameter is not defined.
date [optional] Specify date to get Carat. If not specified, uses live rates.

Example API Response

{
  "success": true,
  "base": "USD",
  "timestamp": 1650130340,
  "data": {
        "24k": 12.69083155,
        "23k": 12.16204691,
        "22k": 11.63326226,
        "21k": 11.10447761,
        "18k": 9.51812367,
        "16k": 8.46055437,
        "14k": 7.40298507,
        "12k": 6.34541578,
        "10k": 5.28784648,
        "9k": 4.75906183,
        "8k": 4.23027718,
        "6k": 3.17270789
      }
  }

Response Attributes

Attribute Description
success Returns true or false depending if the API Request succeeded. If false, refer to API Errors.
base Returns base currency used for the request.
timestamp Returns the UNIX timestamp the given exchange rates were collected.
data Returns carat data.