# Metals-API

> Real-time and historical precious metals and currency JSON API: gold, silver, platinum, palladium, and more.

Metals-API is a REST API for precious-metals market data. Use it to fetch live prices, historical closes, time series, fluctuations, conversions, OHLC, and intraday candles. Authenticate every REST request with the query parameter `access_key`. Get a key at https://metals-api.com/register.

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

## Key pages

- [Homepage](https://metals-api.com): Product overview and signup
- [API documentation](https://metals-api.com/documentation): Public endpoint docs
- [MCP for AI agents](https://metals-api.com/mcp): Connect Claude, Cursor, ChatGPT, and other MCP clients
- [Pricing](https://metals-api.com/pricing): Plans and trial
- [Postman collection](https://metals-api.com/Metals-API.com.postman_collection.json): Importable request collection
- [Supported symbols](https://metals-api.com/symbols): List of available metal and currency symbols

## Base URL

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

REST requires `?access_key=YOUR_ACCESS_KEY` on every request.

## Authentication

REST (query parameter `access_key`):

```
GET /latest?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU
```

MCP: do not put the key in the URL — Claude Desktop and claude.ai reject tokens in the query string. Pass `api_key` on every tool call. The worker maps `api_key` → REST `access_key`.

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

Keys are created after signup. Keep the key secret — never expose it in client-side JavaScript or public repos. Rotate it from the account area if compromised.

## MCP (AI agents)

Metals-API exposes the same data via Model Context Protocol:

- Setup page: https://metals-api.com/mcp
- MCP endpoint: `https://metals-api.mcp.metals-api.com/mcp` (no key in the URL)
- Auth: `api_key` on every tool call (not REST `access_key`). Claude Desktop and claude.ai reject tokens in the query string.
- Discovery: https://metals-api.com/.well-known/mcp.json
- Tools: `metals.symbols`, `metals.latest`, `metals.historical`, `metals.convert`, `metals.time_series`, `metals.fluctuation`, `metals.ohlc`, `metals.intraday`

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

## Endpoints

- `GET /symbols` — Supported metal and currency symbols. MCP: `metals.symbols`
- `GET /latest` — Real-time metal rates (`base`, `symbols`). MCP: `metals.latest`
- `GET /{YYYY-MM-DD}` — Historical closing rates for a past date. MCP: `metals.historical`
- `GET /convert` — Convert an amount between symbols (`from`, `to`, `amount`, optional `date`). MCP: `metals.convert`
- `GET /timeseries` — Daily rates between `start_date` and `end_date`. MCP: `metals.time_series`
- `GET /fluctuation` — Absolute and percent change between two dates. MCP: `metals.fluctuation`
- `GET /open-high-low-close/{YYYY-MM-DD}` — OHLC prices for a trading day. MCP: `metals.ohlc`
- `GET /intraday` — Intraday candles (`symbol`, `base`, `date`, `interval`). MCP: `metals.intraday`

Example:

```
GET /latest?access_key=YOUR_ACCESS_KEY&base=USD&symbols=XAU,XAG,XPT
```

Full parameter lists: https://metals-api.com/documentation

## Optional

- [llms-full.txt](https://metals-api.com/llms-full.txt): Detailed API schemas and response formats
- [MCP setup page](https://metals-api.com/mcp)
- [MCP discovery JSON](https://metals-api.com/.well-known/mcp.json)
- [MCP server card](https://metals-api.com/.well-known/mcp/server-card.json)
- [MCP server](https://metals-api.mcp.metals-api.com/mcp)
- [robots.txt](https://metals-api.com/robots.txt)
- [Sitemap](https://metals-api.com/sitemap)