# MetalAPI

> MetalAPI is a JSON REST API with real-time and historical prices for precious metals (gold XAU, silver XAG, platinum XPT, palladium XPD), industrial metals, energy, 57 currencies and 13 cryptocurrencies, plus an MCP server for AI assistants.

- Base URL: https://metalapi.com/api/v1/ (HTTPS, GET, JSON). Authenticate with `?api_key=YOUR_API_KEY`, `Authorization: Bearer YOUR_API_KEY` or `X-API-Key`. Keys start with `mk_live_`.
- In `rates`, the key `<BASE><SYMBOL>` (e.g. `USDXAU`) is the price of one unit of the symbol in the base currency (USD per troy ounce of gold); the plain key (`XAU`) is its inverse, kept for compatibility with older clients.
- Metals are priced per troy ounce by default; add `unit=gram` (or kilogram, ounce, pound, metric_ton, short_ton).
- Plans: Free (100 requests/month, daily prices); paid plans from $4.99/month with fresher prices and higher limits: https://metalapi.com/pricing
- Errors return `{"success": false, "error": {"code", "type", "info"}}`; quota and plan errors also carry `upgrade_url`.
- MCP server for AI assistants: https://metalapi.com/mcp (sign in with OAuth, or send an API key as a Bearer token). Setup: https://metalapi.com/guides/ai

## API reference

- [Latest rates](https://metalapi.com/docs#latest): `GET https://metalapi.com/api/v1/latest` — Current rates for every requested symbol.
- [Historical rates](https://metalapi.com/docs#historical): `GET https://metalapi.com/api/v1/{YYYY-MM-DD}` — Closing rates for a past day.
- [Convert](https://metalapi.com/docs#convert): `GET https://metalapi.com/api/v1/convert` — Convert an amount from one symbol to another, at the latest rate or on a given date.
- [Timeframe](https://metalapi.com/docs#timeframe): `GET https://metalapi.com/api/v1/timeframe` — Daily closing rates between two dates (inclusive).
- [Change](https://metalapi.com/docs#change): `GET https://metalapi.com/api/v1/change` — How each rate moved between two dates, as absolute and percentage change.
- [Open / High / Low / Close](https://metalapi.com/docs#ohlc): `GET https://metalapi.com/api/v1/ohlc` — Daily OHLC for a date (default: today, intraday so far).
- [Gold by karat](https://metalapi.com/docs#carat): `GET https://metalapi.com/api/v1/carat` — Gold price for jewellery karats (purity = karat / 24).
- [Symbols](https://metalapi.com/docs#symbols): `GET https://metalapi.com/api/v1/symbols` — Every supported symbol and its name.
- [Usage](https://metalapi.com/docs#usage): `GET https://metalapi.com/api/v1/usage` — Your requests this month and what is left.
- [OpenAPI 3.1 specification](https://metalapi.com/openapi.json)

## Guides

- [Getting Started with MetalAPI](https://metalapi.com/guides/getting-started): Create a free account, get your API key and make your first request for live gold, silver, platinum and palladium prices.
- [API Authentication](https://metalapi.com/guides/authentication): Send your API key as a query parameter or header, restrict keys to your own domains and keep them safe.
- [Available Endpoints](https://metalapi.com/guides/endpoints): Every MetalAPI endpoint and its parameters: latest, historical, convert, timeframe, change, OHLC, carat, symbols, usage and stream.
- [Rate Limits & Plans](https://metalapi.com/guides/rate-limits): How monthly quotas, per-minute limits and update intervals work on each plan, and how to track your usage.
- [Embeddable Price Widgets](https://metalapi.com/guides/widgets): Show live metal prices on any website with an embeddable widget. No backend code, and no API key in your page.
- [Webhooks & Price Alerts](https://metalapi.com/guides/webhooks): Receive signed HTTP callbacks when a price crosses your threshold, and verify them with HMAC-SHA256.
- [Error Handling](https://metalapi.com/guides/error-handling): MetalAPI error codes, their HTTP status codes, and how to handle and retry failed requests.
- [Data Formats & Units](https://metalapi.com/guides/data-formats): How rates are expressed, choosing a base currency and mass unit, bid/ask and karat prices, timestamps and market hours.
- [Accessing Historical Data](https://metalapi.com/guides/historical-data): Query daily prices back to 1999, fetch date ranges, compare two dates, get OHLC bars and analyse price trends.
- [Best Practices](https://metalapi.com/guides/best-practices): Cache wisely, batch symbols, stream instead of polling, and keep your keys and webhooks secure.
- [API Documentation Overview](https://metalapi.com/guides/documentation): A one-page tour of the MetalAPI REST API: base URL, authentication, parameters, response format, errors, rate limits and code examples.
- [Use MetalAPI with AI Assistants (MCP)](https://metalapi.com/guides/ai): Connect Claude, ChatGPT, Cursor, VS Code and other AI assistants to live metal prices with the MetalAPI MCP server, by signing in or with an API key.

## Optional

- [Full documentation in one file](https://metalapi.com/llms-full.txt)
- [Pricing](https://metalapi.com/pricing)
- [Status](https://metalapi.com/status)
- [Terms](https://metalapi.com/terms) · [Privacy](https://metalapi.com/privacy) · Contact: info@mbclabs.uk