Metals-API

Quickstart Tool

No time for long documentation articles? We've got you covered - in the Dashboard section of your control panel you will be able to access our Quickstart tool and test all API endpoints at the click of a button.

Getting Started

Definitions

API Key

Your API Key is the unique key that is passed into the API base URL's access_key parameter in order to authenticate with the Metals-API.

Base URL:

https://metals-api.com/api/

Append your API Key: Here is how to authenticate with the Metals-API:

https://metals-api.com/api/latest?access_key=API_KEY

API Response

Exchange rates delivered by the Metals-API are by default relative to USD. All data is returned in standard JSON format and can be parsed easily using any programming language.

When fetching metal rates with USD selected as the base currency (utilizing the 'base' parameter, defaulting to USD if not specified), it is necessary to apply 1/value to the API response.

For instance, to ascertain the gold rate in USD from the API response value, execute 1/0.0004831705, yielding 2069.6627795 USD.

Furthermore, when USD serves as the base, the API response will include the USD Price without requiring additional conversion. This can be identified, for example, as USDXAU. (ONLY APPLIES FOR LATEST ENDPOINT).

Additionally, it's important to note that if you opt for a different base currency, such as EUR, the 1/value division is not necessary. The price is already converted.

{
    "success": true,
    "timestamp": 1519296206,
    "base": "EUR",
    "date": "2018-09-10",
    "rates": {
        "AUD": 1.566015,
        "CAD": 1.560132,
        "CHF": 1.154727,
        "CNY": 7.827874,
        "GBP": 0.882047,
        "JPY": 132.360679,
        "USD": 1.23396,
        [...]
    }
}      

As illustrated above, the API's response - when queried for real-time exchange rates - always contains a timestamp object containing a standard UNIX time stamp indicating the time the given exchange rate data was collected, a base object containing the three-letter currency code or metal code of the base currency, a date object containing the date the given exchange rate data was collected, and a rates object containing the actual exchange rate data.

Further below, in the Endpoints section, the API response structure will be discussed in detail.

Available Endpoints

The Metals-API comes with 15 API endpoints, each providing a different functionality. Please note that depending on your subscription plan, certain API endpoints may or may not be available.

• Supported Symbols EndpointReturns all available currencies and metals supported by the API.
• Latest rates endpointReturns real-time exchange rate data for all available or a specific set of currencies. (The number of symbols per API request depends on the acquired plan).
• Convert endpointAllows for conversion of any amount from one currency to another.
• Historical rates endpointReturns historical exchange rate data for a specific set of currencies. (The number of symbols per API request depends on the acquired plan).
• Bid And Ask EndpointReturns real-time Bid and Ask prices for Gold, Silver, Palladium, and Platinum. (The number of symbols per API request depends on the acquired plan).
• Time-Series data endpointReturns daily historical exchange rate data between two specified dates for all available or a specific set of currencies. (The date limits per API request depend on the acquired plan).
• Fluctuation data endpointReturns fluctuation data between two specified dates for all available or a specific set of currencies. (The date limits per API request depend on the acquired plan).
• Intraday data endpointReturns intraday exchange rate data for a specific symbol on a given date. (The number of candles per API request depends on the acquired plan).
• Carat data endpointReturns gold by carat data for a specific base currency.
• Lowest/Highest price endpointReturn the lowest and highest price
• Metals Price IndiaReturns the latest gold price in India using the Metals-API's dedicated Gold Price India endpoint.
• Historical rates LBMA endpointReturns historical exchange rate data for a specific set of currencies.
• Open/High/Low/Close price endpointReturn the open, high, low, and close price
• Historical LME endpointReturns historical exchange rate data for a specific set of currencies.

SSL Connection

All paid subscription plans available on Metals-API come with 256-bit SSL encryption. To connect to the API via SSL, simply use the https protocol instead of standard http.

JSONP Callbacks

The Metals-API comes with support for JSONP Callbacks. This feature enables you to specify a function name, pass it into the API's callback GET parameter and cause the API to return your requested API response wrapped inside that function.

Example Call:

https://metals-api.com/api/latest?access_key=API_KEY&callback=MY_FUNCTION

In the example call above we are requesting the API to use the callback name MY_FUNCTION.

Example Response: Your API response will be wrapped inside your preferred callback function.

({
    "success": true,
    "timestamp": 1519296206,
    "base": "EUR",
    "date": "2018-09-10",
    "rates": {
        "AUD": 1.566015,
        "CAD": 1.560132,
        "CHF": 1.154727,
        "CNY": 7.827874,
        "GBP": 0.882047,
        "JPY": 132.360679,
        "USD": 1.23396,
        [...]
    }
})  

Access-Control / CORS

Metals-API also supports Cross-Origin Resource Sharing (CORS) and Access-Control Headers. This will enable you to use the Metals-API via Cross-Origin HTTP Requests.

Learn more about CORS »

HTTP ETags

HTTP ETags are a way of reducing the load on your back-end by requesting new Metals-API data only if rates have changed since the last API response.

What are ETags?

An ETag is a part of the HTTP protocol and one of the several mechanisms used for cache validation. The ETag is an identifier assigned to a data resource in a server, and if that resource is ever updated at the server, the ETag is changed.

Whenever a resource is requested (via its URL), the data and ETag are retrieved and stored in the Web cache, and the ETag is sent along with subsequent requests. If the ETag at the server has not changed, a "Not Modified" message is returned, and the cached data is used. (Definition by pcmag.com)

ETags - Quickstart Guide

Your initial request to the Metals-API will create an ETag object containing a unique ETag key and a Date object containing the exact date and time at which the data was last modified. This data must be cached along with the entire API response in order for ETags to work.

ETag: "202567a75aef2e66a3ebf2366bff048f"  
Date: Mon, 12 Apr 2018 11:30:01 GMT

Once you make another API request, make sure to include the If-None-Match HTTP header and set it to your previously generated ETag value. Moreover, you will need to add the If-Modified-Since HTTP header to your API request containing the date and time data from your last request. Additionally, you can include other optional headers for enhanced functionality:

If-None-Match: "1872ade88f3013edeb33decd74a4f947"  
If-Modified-Since: Fri, 10 Apr 2015 12:10:04 GMT
Cache-Control: max-age=3600
Accept-Encoding: gzip, deflate
User-Agent: YourApp/1.0

Depending on whether or not your result set has updated since your last API request, the API will return either:

• the results from your initial API request along with a 304 – Not Modified HTTP header indicating that no change has occured. In this case, the size of the API response will be as small as 0.2kb;
• or new results with an entirely new set of ETag and Date objects indicating that new data has been accessed. In this case, the size of your API response will be normal.

Potential Errors

Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.

Example Error: The following error is returned if your monthly API request volume has been exceeded.

{
    "success": false,
    "error": {
        "code": 429,
        "info": "Your monthly API request volume has been reached. Please upgrade your plan."
    }
}      

Other Errors:

Endpoints

Supported Symbols Endpoint

The Metals-API comes with a constantly updated endpoint returning all available currencies. To access this list, make a request to the API's symbols endpoint.

API Request:

https://metals-api.com/api/symbols?access_key=API_KEY

Run in Postman

Request Parameters:

API Response:

{
    "AAAU": {
    "id": "AAAU",
    "name": "Goldman Sachs Physical Gold ETF"
    },
    "ADA": {
    "id": "ADA",
    "name": "Cardano"
    },
    "AED": {
    "id": "AED",
    "name": "United Arab Emirates Dirham"
    },
    "AFN": {
    "id": "AFN",
    "name": "Afghan Afghani"
    },
    "AHME-22k": {
    "id": "AHME-22k",
    "name": "Ahmedabad Gold 22k",
    "unit": "per gram"
    },
    [...]
}  

Response Objects:

Latest Rates Endpoint

Depending on your subscription plan, the API's latest endpoint will return real-time exchange rate data updated every 60 minutes, every 10 minutes or every 60 seconds.

For LBMA prices (e.g. LBXAUAM), it should be noted that the rates correspond to the previous day's closing price.

For LME symbols (e.g. LME-XCU), the rates correspond to the official closing price of the day, not an intraday quote.

For LME 3M symbols (e.g. ALU3M), the rates correspond to the previous day's closing price.

API Request:

https://metals-api.com/api/latest?access_key=API_KEY&base=USD&symbols=XAU,XAG,XPD

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "timestamp": 1519296206,
    "base": "USD",
    "date": "2018-09-10",
    "rates": {
        "USD": 1,
        "XAG":  0.041405839732253,
        "XAU":  0.0004831705,
        "XPD": 0.00084781687155574,
        "USDXAG": 24.151182694673185,
        "USDXAU": 2069.6627794950227,
        "USDXPD": 1179.5000000000057,
    }
}      

Response Objects:

Quote unit and market unit

quote_unit is the unit stored on the symbol (currency_symbols.unit), not a blanket troy ounce. quote_price is the price of one of those units in the request base (the USDALU figure when base is USD; ALU remains the inverse). With another base, a symbol that starts with X (such as XCU) is already that direct price, so quote_price uses rates.XCU and does not invert it. market_unit is the LME convention, metric_ton (per metric ton). market_price converts the stored quote into that market unit:

market_price = quote_price × conversion_factor

One metric ton is 32150.7 troy ounces, or 35274 avoirdupois ounces. A quote of about 0.09996 USD per troy ounce is about 3213.78 USD per metric ton. A symbol already stored per tonne has conversion_factor 1 and market_price equal to quote_price. Passing unit=ton uses that same factor, so the converted rate and market_price match. For an avoirdupois ounce quote of 0.366875, both are 12941.14875 USD per metric ton. rates without the unit parameter are not rewritten. Historical endpoints are unchanged.

The allowlist is explicit: NI, ZNC, ALU, LEAD, TIN, XCU, LME-ALU, LME-XCU, LME-LEAD, LME-NI, LME-TIN, LME-ZNC. Symbols outside that list, including LME-ALUA (already USD per tonne) and LBMA precious metals, do not receive unit or units. XCU is per ounce, not per troy ounce.

Example for an LME-style symbol:

{
    "success": true,
    "base": "USD",
    "rates": {
        "ALU": 10.003,
        "USDALU": 0.09996
    },
    "unit": {
        "ALU": "per troy ounce"
    },
    "units": {
        "ALU": {
            "name": "Aluminum",
            "category": "base_metal",
            "quote_unit": "troy_ounce",
            "quote_unit_label": "per troy ounce",
            "quote_price": 0.09996,
            "market_unit": "metric_ton",
            "market_unit_label": "per metric ton",
            "market_price": 3213.783972,
            "conversion_factor": 32150.7
        }
    }
}

Historical Rates Endpoint

Historical rates are available for most currencies dating back to 2019. You can query the Metals-API for historical rates by appending a date ( YYYY-MM-DD) to the base URL.

For all symbols in this endpoint, the prices provided correspond to the closing price of that day.

Note: For LME symbols, the prices correspond to the closing price of the same day. LBMA symbols return that date's fixing. A weekend or UK holiday with no fixing returns the previous one.

We also offer specific historical endpoints for LBMA and LME, where older data is available.

API Request:

https://metals-api.com/api/2013-12-24?access_key=API_KEY&base=EUR&symbols=XAU,XAG,XPD

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "historical": true,
    "date": "2013-12-24",
    "timestamp": 1387929599,
    "base": "GBP",
    "rates": {
        "XAG": 21.9522920446423,
        "XAU": 1871.0803462620966,
        "XPD": 1067.2276441391284
    }
}      

Response Objects:

Bid And Ask Endpoint

Depending on your subscription plan, the API's Bid and Askendpoint is a powerful API feature that enables you to retrieve real-time Bid and Ask prices for a selection of precious metals, including Gold, Silver, Palladium, and Platinum.

To obtain the symbols required for the endpoint, you can refer to the symbols list provided at Symbols List.

API Request:

https://metals-api.com/api/latest?access_key=API_KEY&base=USD&symbols=XAU-BID,XAU-ASK

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "date": "2013-12-24",
    "timestamp": 1387929599,
    "base": "USD",
    "rates": {
        "USD": 1,
        "XAU-ASK": 0.00050474459,
        "XAU-BID": 0.00050499949,
        "USDXAU-ASK": 1981.19999999,
        "USDXAU-BID": 1980.19999999
    }
}      

Response Objects:

Specify Symbols

To reduce bandwidth you can limit the number of output currencies to a specific set of your choice on most API endpoints. To do so, simply append the Metals-API's symbols parameter to your API request and set it to one or more comma-separated currency codes or metal codes.

Example:

https://metals-api.com/api/latest?access_key=API_KEY&symbols=XAU,XAG,XPD

The API's response for the request above will be limited to the currencies USD, CAD and JPY.

Changing base currency

Provided changing base currency is supported on your subscription plan, you can change the currency to which your output currency rates are relative to by appending the base parameter to your API request URL and setting it to the three-letter code of your preferred base currency.

Example:

https://metals-api.com/api/latest?access_key=API_KEY&base=USD

Please note: The default base currency is USD. You can use any currency as base currency. If you need additional base currencies please contact us

Convert Endpoint

The Metals-API comes with a separate currency conversion endpoint, which can be used to convert any amount from one currency to another. In order to convert currencies, please use the API's convert endpoint, append the from and to parameters and set them to your preferred base and target currency codes or metal codes.

It is also possible to convert currencies using historical exchange rate data. To do this, please also use the API's date parameter and set it to your preferred date. (format YYYY-MM-DD)

API Request:

https://metals-api.com/api/convert?access_key=API_KEY&from=GBP&to=JPY&amount=25

Run in Postman

Request Parameters:

API Response:

{
"success": true,
"query": {
"from": "GBP",
"to": "JPY",
"amount": 25
},
"info": {
"timestamp": 1519328414,
"rate": 148.972231
},
"historical": "",
"date": "2018-02-22",
"result": 3724.305775
}

Response Objects:

Time-Series Endpoint

The Metals-API timeseries endpoint allows you to query the API for daily historical rates between two dates of your choice. (The date limits per API request depend on the acquired plan).

This endpoint has a limitation depending on the acquired plan, allowing only one symbol per request. If you need to query more than 30 days or more than one symbol, you should send another API call.

For LME symbols, the prices provided in this endpoint correspond to the first known price of the previous day (not the requested day). For example, a request for 2024-11-13 will return the price from 2024-11-12.

LBMA symbols return that date's fixing. A weekend or UK holiday with no fixing returns the previous one.

For other symbols, the prices correspond to the first known price of the requested day.

You cannot use the current date for the "end_date" parameter. We recommend using a day prior to the current date to get a successful response. To get the latest price, you will need to use the latest endpoint.

We also offer specific historical endpoints for LBMA and LME, where older data is available.

API Request:

https://metals-api.com/api/timeseries?access_key=API_KEY&start_date=2023-05-01&end_date=2023-05-25&symbols=XAU

https://metals-api.com/api/timeseries?access_key=API_KEY&type=last_day&symbols=XAU

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "timeseries": true,
    "start_date": "2012-05-01",
    "end_date": "2012-05-03",
    "base": "EUR",
    "rates": {
        "2023-05-01": {
            "USD": 1,
            "XAU": 0.00050331446219218
        },
        "2023-05-01": {
            "USD": 1,
            "XAU": 0.00050469932538839
        },
        "2023-05-02": {
            "USD": 1,
            "XAU": 0.00049603398443199
        },
        "2023-05-03": {
            "USD": 1,
            "XAU": 0.00048723596263295
        },
        [...]
    }
}      

Response Objects:

Fluctuation Endpoint

Using the Metals-API's fluctuation endpoint you will be able to retrieve information about how currencies fluctuate on a day-to-day basis. (The date limits per API request depends on the acquired plan). To use this feature, simply append a `start_date` and `end_date` or choose the `type` parameter to retrieve the rate change for a predefined time period, and choose the symbol you would like to query the API for.

API Request:

https://metals-api.com/api/fluctuation?access_key=API_KEY&start_date=2023-12-01&end_date=2015-12-15&symbols=XAU

https://metals-api.com/api/fluctuation?access_key=API_KEY&type=last_day&symbols=XAU

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "fluctuation": true,
    "start_date": "2018-02-25",
    "end_date": "2018-02-26",
    "base": "EUR",
    "rates": {
        "USD": {
            "start_rate": 1,
            "end_rate": 1,
            "change": 0,
            "change_pct": 0
        },
        "XAU": {
            "start_rate": 0.0004900901501473,
            "end_rate": 0.0004950722517565,
            "change": 4.9821016092000585,
            "change_pct": 1.0165684023036687
        },
        [...]
    }
}      

Response Objects:

Intraday Endpoint

The Metals-API intraday endpoint allows you to query intraday exchange rate data for a single symbol on a specific date. Data is returned as time-based candles at the requested interval. (The number of candles per API request depends on the acquired plan).

Only one symbol can be requested per API call. The symbol and base parameters must be different. Intraday data is not available for future dates.

If you request an interval smaller than the symbol's update rate, consecutive candles may repeat the same price until new data is available.

API Request:

https://metals-api.com/api/intraday?access_key=API_KEY&symbol=XAU&base=USD&date=2025-07-25&interval=1h

Run in Postman

Request Parameters:

API Response:

{
    "rates": {
        "2025-07-25T00:00:00Z": {
            "XAU": 0.00050331446219218
        },
        "2025-07-25T01:00:00Z": {
            "XAU": 0.00050469932538839
        },
        [...]
    },
    "meta": {
        "update_rate": "60m"
    },
    "message": "If you request an interval smaller than the update rate, consecutive candles may repeat the same price until new data is available."
}      

Response Objects:

Carat Endpoint

Using the Metals-API's carat endpoint you will be able to retrieve information about Gold rates by Carat. To use this feature, simply append a base to choose which currencies (symbols) you would like to query the API for.

API Request:

https://metals-api.com/api/carat?access_key=API_KEY

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "timestamp": 1712175937,
    "base": "USD",
    "rates": {
        "24K": 73.71,
        "23K": 70.62,
        "22K": 67.6,
        "21K": 64.5,
        "18K": 55.29,
        "14K": 42.98,
        "12K": 36.86,
        "10K": 30.74,
        "9K": 27.64,
        "8K": 24.55
    },
    "unit": "per Gram"
}      

Response Objects:

Lowest/Highest Price Endpoint

Metals-API lowest-highest/YYYY-MM-DD endpoint allows you to query the API to get the lowest and highest price.

This endpoint has a limitation of one symbol per request.

API Request:

https://metals-api.com/api/lowest-highest/YYYY-MM-DD?access_key=API_KEY&base=USD&symbols=XAU

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "timestamp": 1641842149,
    "date": "2022-01-01",
    "base": "USD",
    "symbol": "XAU",
    "rates": {
        "low": 0.0005470547,
        "high": 0.00054754153
    },
    "unit": "per ounce"
}      

Response Objects:

Metals Price India

Formerly Gold Price India

Retrieve the latest gold price in India using the Metals-API's dedicated Gold Price India endpoint. This API provides real-time data for specific gold symbols.

This endpoint works exclusively in INR (Indian Rupee). Currency conversion is not supported. The base parameter is not accepted. All prices are always returned in INR.

List of Symbols: Metals-API Symbols.

API Request:

https://metals-api.com/api/gold-price-india?access_key=API_KEY&symbols=VIJA-22k,SALE-22k,VISA-24k

Note: The base parameter is not supported in this endpoint.

Run in Postman

Request Parameters:

This endpoint does not support the base parameter.

API Response:

{
    "success": true,
    "timestamp": 61326132,
    "base": "INR",
    "date": "2024-02-08",
    "rates": {
        "VIJA-22k": 5840,
        "SALE-22k": 5840,
        "VISA-24k": 6132
    },
    "unit": "per gram"
}      

Response Objects:

Historical Rates LBMA

Historical rates are accessible through the Metals-API endpoint for LBMA symbols, dating back to 1968 for Gold, 2010 for Silver, and since 1990 for Palladium & Platinum LBMA.

To query historical rates, simply append a date (formatted as YYYY-MM-DD) to the base URL in the Historical Rates LBMA endpoint.

Please note that the prices provided correspond to the closing price of the respective day and are available in USD, GBP, and EUR

List of Symbols: Metals-API Symbols.

API Request:

https://metals-api.com/api/historical-lbma/1968-12-31?access_key=API_KEY&symbols=LBXAUAM

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "timestamp": -31622400,
    "base": "USD",
    "date": "1968-12-31",
    "rates": {
        "LBXAUAM": 41.95
    },
    "unit": "per ounce"
}      

Response Objects:

Open/High/Low/Close (OHLC) Price Endpoint

Metals-API open-high-low-close/YYYY-MM-DD endpoint allows you to query the API to get the open, high, low, and close price.

Note: The open and close values are based on the start and end of the UTC day, not on traditional trading hours. If you're querying data for the current day, keep in mind that the high and close prices may change as the day progresses.

This endpoint has a limitation of one symbol per request.

API Request:

https://metals-api.com/api/open-high-low-close/YYYY-MM-DD?access_key=API_KEY&base=XAU&symbols=USD

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "timestamp": 1653931700,
    "date": "2022-05-20",
    "base": "XAU",
    "symbol": "USD",
    "rates": {
        "open": 1841.1889341969709,
        "high": 1851.6666851833336,
        "low": 1816.419890887657,
        "close": 1844.828964194302
    },
    "unit": "per ounce"
}      

Response Objects:

Historical LME Endpoint

Metals-API historical-lme Historical rates are accessible through the Metals-API endpoint for LME symbols, dating back to 2008. This endpoint allows you to query historical rates by appending a date (formatted as YYYY-MM-DD) to the base URL in the Historical Rates LME endpoint.

Please note that the prices provided correspond to the closing price of the respective day.

Rates here stay in the symbol's stored unit (troy ounce for the symbols below). They are not rewritten to metric tons. On /latest, these symbols also include units: quote_unit comes from the stored unit and market_unit is the LME convention (metric ton). LME-ALUA is not in that list.

List of Symbols :

Price Types :

API Request:

https://metals-api.com/api/historical-lme/YYYY-MM-DD?access_key=API_KEY&symbols=LME-ALU&price_type=CS

Run in Postman

Request Parameters:

API Response:

{
    "success": true,
    "timestamp": 1208995200,
    "base": "USD",
    "date": "2008-04-24",
    "rate": {
        "LME-ALU": 0.07730948678   
    },
    "unit": "per troy ounce",
    "price_type": "CS"
}

Response Objects:

AI Agents & MCP

MCP Server

Metals-API runs a hosted Model Context Protocol (MCP) server, so AI assistants and agents can use live and historical metals data directly. MCP is the open standard that Claude, ChatGPT, Cursor and other AI tools use to connect to external services. Once connected, you ask a question in plain language. The assistant chooses the right Metals-API tool, calls it with your API Key and answers with current data instead of what it remembers from training.

1. You ask: "How much has gold moved against silver this month?"
2. The assistant calls a tool, for example metals.fluctuation with symbols: "XAU,XAG".
3. The MCP server queries Metals-API with your API Key and returns the data.
4. The assistant answers with the figures it received.

MCP Endpoint:

https://metals-api.mcp.metals-api.com/mcp

Connect Your AI Assistant

Claude (claude.ai and Claude Desktop):

1. Open Settings → Connectors and choose Add custom connector.
2. Enter a name, for example Metals-API, and paste the MCP endpoint as the Remote server URL.
3. Start a chat and ask about metal prices. Claude asks for your API Key the first time a tool needs it.

Cursor, Windsurf and other MCP clients: add Metals-API as a remote server. For example, in Cursor's mcp.json:

{
  "mcpServers": {
    "metals-api": {
      "url": "https://metals-api.mcp.metals-api.com/mcp"
    }
  }
}

ChatGPT and the OpenAI API: send your chat request to our OpenAI-compatible proxy, https://metals-api.mcp.metals-api.com/v1/chat/completions, and it adds live Metals-API data to the conversation before OpenAI answers. Your OpenAI key goes in the Authorization header and your Metals-API key in the tool parameters.

Your own agent: any MCP SDK connects to the endpoint above. The protocol is plain JSON-RPC over HTTP, so you can also call it directly. First initialize and keep the Mcp-Session-Id response header, then call a tool:

curl -X POST "https://metals-api.mcp.metals-api.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"metals.latest","arguments":{"api_key":"API_KEY","symbols":"XAU,XAG","base":"USD"}}}'

Step-by-step guides with screenshots, the OpenAI proxy parameters and a complete Python client are on the MCP Server page.

MCP Tools

Each tool maps to a REST endpoint and accepts the same values, so everything in this documentation applies to MCP too. Dates use YYYY-MM-DD and symbols is a comma-separated list such as XAU,XAG.

Questions to try:

• "What is the price of gold per ounce in EUR right now?"
• "Chart silver's daily closing price over the last 30 days."
• "How much did platinum change between January 1 and today, in percent?"
• "Convert 5 ounces of silver to GBP at yesterday's price."

Resources for AI Agents

Agents that discover services on their own can read these machine-readable files on https://metals-api.com. They describe the API, the MCP server and how to authenticate.

Sample Code

The Metals-API can be integrated with any programming language that supports HTTP requests. Below you will find code examples for various popular programming languages.

• PHP (cURL)Example code for PHP using cURL.
• PythonExample code for Python using the requests module.
• JavaScriptExample code for JavaScript using jQuery.ajax.
• Node.jsExample code for Node.js using fetch and axios.
• GoExample code for Go using net/http package.
• RubyExample code for Ruby using net/http and json.
• JavaExample code for Java using HttpClient (Java 11+).
• C#Example code for C# using .NET HttpClient.
• RustExample code for Rust using reqwest.
• KotlinExample code for Kotlin using ktor-client.
• SwiftExample code for Swift using URLSession.

PHP (cURL)

Real-time rates: Find below a simple PHP example for getting exchange rate data via the Metals-API's latest endpoint.

// set API Endpoint and API key 
$endpoint = 'latest';
$access_key = 'API_KEY';

// Initialize CURL:
$ch = curl_init('https://metals-api.com/api/'.$endpoint.'?access_key='.$access_key.'');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Store the data:
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response:
$exchangeRates = json_decode($json, true);

// Access the exchange rate values, e.g. GBP:
echo $exchangeRates['rates']['GBP'];

Convert currencies: Here is how to convert currencies using PHP cURL.

// set API Endpoint, access key, required parameters
$endpoint = 'convert';
$access_key = 'API_KEY';

$from = 'USD';
$to = 'EUR';
$amount = 10;

// initialize CURL:
$ch = curl_init('https://metals-api.com/api/'.$endpoint.'?access_key='.$access_key.'&from='.$from.'&to='.$to.'&amount='.$amount.'');   
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// get the JSON data:
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response:
$conversionResult = json_decode($json, true);

// access the conversion result
echo $conversionResult['result'];

Python (using Request module)

import requests

base_currency = 'USD'
symbol = 'XAU' 
endpoint = 'latest'
access_key = 'API_KEY'

resp = requests.get(
    'https://metals-api.com/api/'+endpoint+'?access_key='+access_key+'&base='+base_currency+'&symbols='+symbol)
if resp.status_code != 200:
    # This means something went wrong.
    raise ApiError('GET /'+endpoint+'/ {}'.format(resp.status_code))
print(resp.json())

JavaScript (jQuery.ajax)

Real-time rates: Find below a simple jQuery.ajax example for getting exchange rate data via the Metals-API's latest endpoint.

// set endpoint and your access key
endpoint = 'latest'
access_key = 'API_KEY';

// get the most recent exchange rates via the "latest" endpoint:
$.ajax({
url: 'https://metals-api.com/api/' + endpoint + '?access_key=' + access_key,   
dataType: 'jsonp',
success: function(json) {

// exchange rata data is stored in json.rates
alert(json.rates.GBP);

// base currency is stored in json.base
alert(json.base);

// timestamp can be accessed in json.timestamp
alert(json.timestamp);

}
});

Convert currencies: Here is how to convert currencies using jQuery.ajax.

// set endpoint and your API key
endpoint = 'convert';
access_key = 'API_KEY';

// define from currency, to currency, and amount
from = 'EUR';
to = 'GBP';
amount = '10';

// execute the conversion using the "convert" endpoint:
$.ajax({
url: 'https://metals-api.com/api/' + endpoint + '?access_key=' + access_key +'&from=' + from + '&to=' + to + '&amount=' + amount,   
dataType: 'jsonp',
success: function(json) {

// access the conversion result in json.result
alert(json.result);

}
});

Node.js (fetch / axios)

Real-time rates using fetch: Find below a simple Node.js example using the native fetch API for getting exchange rate data via the Metals-API's latest endpoint.

// Using native fetch (Node.js 18+)
const endpoint = 'latest';
const access_key = 'API_KEY';
const base = 'USD';
const symbols = 'XAU,XAG';

const url = 'https://metals-api.com/api/' + endpoint + '?access_key=' + access_key + '&base=' + base + '&symbols=' + symbols;

const response = await fetch(url);
const data = await response.json();

console.log(data.rates);

Real-time rates using axios: Here is how to get exchange rate data using axios.

// Using axios (npm install axios)
const axios = require('axios');

const endpoint = 'latest';
const access_key = 'API_KEY';

axios.get('https://metals-api.com/api/' + endpoint, {
    params: {
        access_key: access_key,
        base: 'USD',
        symbols: 'XAU,XAG'
    }
})
.then(response => {
    console.log(response.data.rates);
})
.catch(error => {
    console.error(error);
});

Convert currencies: Here is how to convert currencies using axios.

// Convert currencies using axios
const axios = require('axios');

const access_key = 'API_KEY';

axios.get('https://metals-api.com/api/convert', {
    params: {
        access_key: access_key,
        from: 'USD',
        to: 'EUR',
        amount: 10
    }
})
.then(response => {
    console.log(response.data.result);
});

Go

Real-time rates: Find below a simple Go example for getting exchange rate data via the Metals-API's latest endpoint.

// Using Go net/http package
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
)

type ExchangeRates struct {
    Success   bool              `json:"success"`
    Timestamp int64             `json:"timestamp"`
    Base      string            `json:"base"`
    Date      string            `json:"date"`
    Rates     map[string]float64 `json:"rates"`
}

func main() {
    accessKey := "API_KEY"
    base := "USD"
    symbols := "XAU,XAG"
    
    baseURL := "https://metals-api.com/api/latest"
    params := url.Values{}
    params.Add("access_key", accessKey)
    params.Add("base", base)
    params.Add("symbols", symbols)
    
    reqURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())
    
    resp, err := http.Get(reqURL)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    
    var exchangeRates ExchangeRates
    json.Unmarshal(body, &exchangeRates)
    
    fmt.Println(exchangeRates.Rates)
}

Ruby

Real-time rates: Find below a simple Ruby example for getting exchange rate data via the Metals-API's latest endpoint.

# Using Ruby net/http and json
require 'net/http'
require 'json'
require 'uri'

access_key = 'API_KEY'
base = 'USD'
symbols = 'XAU,XAG'

uri = URI('https://metals-api.com/api/latest')
params = { access_key: access_key, base: base, symbols: symbols }
uri.query = URI.encode_www_form(params)

response = Net::HTTP.get_response(uri)
data = JSON.parse(response.body)

puts data['rates']

Convert currencies: Here is how to convert currencies using Ruby.

# Convert currencies
require 'net/http'
require 'json'
require 'uri'

access_key = 'API_KEY'

uri = URI('https://metals-api.com/api/convert')
params = { access_key: access_key, from: 'USD', to: 'EUR', amount: 10 }
uri.query = URI.encode_www_form(params)

response = Net::HTTP.get_response(uri)
data = JSON.parse(response.body)

puts data['result']

Java (HttpClient)

Real-time rates: Find below a simple Java example using HttpClient (Java 11+) for getting exchange rate data via the Metals-API's latest endpoint.

// Using Java HttpClient (Java 11+)
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class MetalsAPI {
    public static void main(String[] args) throws Exception {
        String accessKey = "API_KEY";
        String base = "USD";
        String symbols = "XAU,XAG";
        
        String url = "https://metals-api.com/api/latest?access_key=" + URLEncoder.encode(accessKey, StandardCharsets.UTF_8)
                + "&base=" + URLEncoder.encode(base, StandardCharsets.UTF_8)
                + "&symbols=" + URLEncoder.encode(symbols, StandardCharsets.UTF_8);
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .build();
        
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        Gson gson = new Gson();
        JsonObject jsonObject = gson.fromJson(response.body(), JsonObject.class);
        
        System.out.println(jsonObject.get("rates"));
    }
}

C# (.NET HttpClient)

Real-time rates: Find below a simple C# example using HttpClient for getting exchange rate data via the Metals-API's latest endpoint.

// Using C# HttpClient and System.Text.Json
using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string accessKey = "API_KEY";
        string baseCurrency = "USD";
        string symbols = "XAU,XAG";
        
        string url = $"https://metals-api.com/api/latest?access_key={accessKey}&base={baseCurrency}&symbols={symbols}";
        
        using HttpClient client = new HttpClient();
        HttpResponseMessage response = await client.GetAsync(url);
        response.EnsureSuccessStatusCode();
        
        string responseBody = await response.Content.ReadAsStringAsync();
        JsonDocument doc = JsonDocument.Parse(responseBody);
        
        Console.WriteLine(doc.RootElement.GetProperty("rates"));
    }
}

Convert currencies: Here is how to convert currencies using C#.

// Convert currencies
using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string accessKey = "API_KEY";
        string url = $"https://metals-api.com/api/convert?access_key={accessKey}&from=USD&to=EUR&amount=10";
        
        using HttpClient client = new HttpClient();
        HttpResponseMessage response = await client.GetAsync(url);
        string responseBody = await response.Content.ReadAsStringAsync();
        JsonDocument doc = JsonDocument.Parse(responseBody);
        
        Console.WriteLine(doc.RootElement.GetProperty("result"));
    }
}

Rust

Real-time rates: Find below a simple Rust example using reqwest for getting exchange rate data via the Metals-API's latest endpoint.

// Using Rust reqwest and serde_json (add to Cargo.toml: reqwest = { version = "0.11", features = ["json"] }, serde_json = "1.0")
use reqwest;
use serde_json::Value;

[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let access_key = "API_KEY";
    let base = "USD";
    let symbols = "XAU,XAG";
    
    let url = format!("https://metals-api.com/api/latest?access_key={}&base={}&symbols={}", access_key, base, symbols);
    
    let response = reqwest::get(&url).await?;
    let json: Value = response.json().await?;
    
    println!("{:?}", json["rates"]);
    
    Ok(())
}

Kotlin

Real-time rates: Find below a simple Kotlin example using ktor-client for getting exchange rate data via the Metals-API's latest endpoint.

// Using Kotlin ktor-client (add to build.gradle.kts: implementation("io.ktor:ktor-client-core:2.3.0"), implementation("io.ktor:ktor-client-cio:2.3.0"))
import io.ktor.client.*
import io.ktor.client.call.body.*
import io.ktor.client.request.*
import kotlinx.serialization.json.*
import kotlinx.coroutines.*

suspend fun main() {
    val client = HttpClient(CIO)
    val accessKey = "API_KEY"
    val base = "USD"
    val symbols = "XAU,XAG"
    
    val url = "https://metals-api.com/api/latest?access_key=$accessKey&base=$base&symbols=$symbols"
    val response = client.get(url)
    val json = Json{ ignoreUnknownKeys = true }.decodeFromString<Map<String, JsonElement>>(response.bodyAsText())
    
    println(json["rates"])
    
    client.close()
}

Swift

Real-time rates: Find below a simple Swift example using URLSession for getting exchange rate data via the Metals-API's latest endpoint.

// Using Swift URLSession and Codable
import Foundation

struct ExchangeRates: Codable {
    let success: Bool
    let timestamp: Int
    let base: String
    let date: String
    let rates: [String: Double]
}

func getExchangeRates() async throws -> ExchangeRates {
    let accessKey = "API_KEY"
    let base = "USD"
    let symbols = "XAU,XAG"
    
    let urlString = "https://metals-api.com/api/latest?access_key=\(accessKey)&base=\(base)&symbols=\(symbols)"
    guard let url = URL(string: urlString) else {
        throw NSError(domain: "Invalid URL", code: 0)
    }
    
    let (data, _) = try await URLSession.shared.data(from: url)
    let exchangeRates = try JSONDecoder().decode(ExchangeRates.self, from: data)
    
    return exchangeRates
}

// Usage
Task {
    do {
        let rates = try await getExchangeRates()
        print(rates.rates)
    } catch {
        print("Error: \(error)")
    }
}