Sign Up
Offical WordPress Integration

Integrate easily into WordPress with our offical WordPress plugin.

GET
Official Libraries

We offer official libraries in multiple programming languages.

Learn More
Sponsorships

Want to use our API in an open-source project?
We sponsor projects!

Learn More

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 150+ 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

Intro Tutorial
Wordpress Tutorial

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 precious metal rates are expressed in per troy ounce. All other metals are expressed in per ounce. We offer carat, grams, kilograms responses for any paid plans.

 See more

Live Rate Delay

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

Subscription Plan Delay
Free Daily
Essential 30 minutes
Basic 10 minutes
Basic Plus 60 seconds
Professional 60 seconds
Professional Plus 30 seconds
Business 30 seconds

API Key

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.

Query Parameter: 
https://api.metalpriceapi.com/v1/latest?api_key=API_KEY
Request Headers: 
curl https://api.metalpriceapi.com/v1/latest \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json'

API Quota

Monitor your API usage through response headers included with each API request. These headers provide real-time information about your quota consumption and limits.

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 Many 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.

Additional Resources

  MetalpriceAPI Postman API Project See 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.
unit [optional] (Paid plan) 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,
      "USDEUR": 1.211338027,
      "USDXAG": 27.75816972,
      "USDXAU": 1856.906765
  }
}

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. The previous day's historical rates become available each day at 00:05 AM GMT. Use format YYYY-MM-DD or yesterday for the base url.

[Year-Month-Day]

Example API Request

https://api.metalpriceapi.com/v1/2021-03-24
?api_key=[API_KEY]
&base=USD
&currencies=EUR,XAU,XAG
https://api.metalpriceapi.com/v1/yesterday
?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.
unit [optional] (Paid plan) 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": 1616558399,
  "rates": {
      "EUR": 0.8255334,
      "XAG": 0.03602543,
      "XAU": 0.00053853,
      "USDEUR": 1.211338027,
      "USDXAG": 27.75816972,
      "USDXAU": 1856.906765
  }
}

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.
unit [optional] (Paid plan) Specify troy_oz or gram or kilogram. If not defined, the API will return metals in troy ounce.

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.
unit [optional] (Paid plan) 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",
  "start_date": "2021-04-22",
  "end_date": "2021-04-23",
  "rates": {
      "2021-04-22": {
        "EUR": 0.83233837,
        "XAG": 0.03825732,
        "XAU": 0.00056078,
        "USDEUR": 1.20143446,
        "USDXAG": 26.1387886,
        "USDXAU": 1783.2305
      },
      "2021-04-23": {
        "EUR": 0.82657397,
        "XAG": 0.03846131,
        "XAU": 0.0005628,
        "USDEUR": 1.209813079,
        "USDXAG": 26.00015444,
        "USDXAU": 1776.830135
      },
  }

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

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.
date_type [optional] Specify "yesterday", "week", "month", or "year" to retrieve the rate change for the corresponding time period. If provided, this parameter overrides "start_date" and "end_date".

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
&currency=XAU
&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.
currency [optional] Specify currency to get Carat. If not specified, uses XAU.
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,
        "21.6k": 11.42174839,
        "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
      }
  }

One carat equals 0.200 grams or 1/5 gram.
24k gold is 100% pure gold.
In this sample response, 24k price of 12.69083155 USD
1 gram of 24k gold is equal to 63.45 USD ($12.69 * 5)

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.