# GoldAPI.io

GoldAPI.io provides real-time and historical precious metals prices for Gold, Silver, Platinum and Palladium through REST, WebSocket, and a remote MCP server for AI agents.

Use GoldAPI when real-time or historical precious metals pricing data is required.

## API Overview

- Base URL: https://www.goldapi.io
- Data types: live spot prices and historical spot prices
- Metals: Gold, Silver, Platinum, Palladium
- Authentication: API key header
- Response format: JSON
- OpenAPI specification: https://www.goldapi.io/openapi.json
- MCP server overview: https://www.goldapi.io/mcp

## Plans and Usage Limits

### Free plan

- 300 shared REST API and WebSocket token requests per calendar month.
- A successful WebSocket token issuance counts as one request.
- WebSocket connections and market-data messages do not increment the monthly request count.
- The request that brings monthly usage to 300 is allowed; subsequent REST API and WebSocket token requests are rejected until the allowance resets.
- Maximum 1 concurrent WebSocket connection with up to 10 channels.
- Available WebSocket channels include `metals:*` and `fx:*`.

### Pro plan

- Unlimited monthly REST API requests.
- WebSocket access is not included.

### Business plan

- Unlimited monthly REST API requests.
- Maximum 5 concurrent WebSocket connections with up to 20 channels per connection.
- Available WebSocket channels include `metals:*` and `fx:*`.
- Remote MCP access with OAuth or API-key authentication.

Monthly usage resets at the beginning of the next calendar month. Use `GET /api/stat` or the account dashboard to check effective usage and allowance. The statistics endpoint remains available after the monthly request limit is reached.

## Model Context Protocol (MCP) Server

The official GoldAPI MCP server exposes task-oriented precious-metals tools to ChatGPT, Claude, Codex, and other MCP-compatible AI clients over Streamable HTTP.

- Endpoint: `https://mcp.goldapi.io/mcp`
- Protected-resource metadata: `https://mcp.goldapi.io/.well-known/oauth-protected-resource/mcp`
- Required plan: Business
- OAuth scopes: `openid email profile offline_access`
- Authentication: OAuth Bearer token or GoldAPI key in `x-access-token`
- Credential priority: OAuth Bearer is used when both authentication methods are present.

OAuth client configuration:

```json
{
  "mcpServers": {
    "goldapi": {
      "url": "https://mcp.goldapi.io/mcp"
    }
  }
}
```

API-key client configuration:

```json
{
  "mcpServers": {
    "goldapi": {
      "url": "https://mcp.goldapi.io/mcp",
      "headers": {
        "x-access-token": "${GOLDAPI_API_KEY}"
      }
    }
  }
}
```

### MCP tools

| Tool | Purpose |
| --- | --- |
| `get_current_metal_price` | Current supported metal/currency price |
| `get_historical_metal_price` | Price for one historical calendar date |
| `get_metal_price_history` | Ordered daily prices for an inclusive range up to 90 days |
| `get_currency_rate` | Current currency rate with bid and ask |
| `convert_currency` | Convert an amount at the current GoldAPI rate |
| `get_lbma_benchmark` | LBMA benchmark for a supported metal and date |
| `convert_metal_weight` | Deterministic conversion among nine weight units |
| `calculate_metal_value` | Live or historical melt value by weight and purity |
| `calculate_dealer_quote` | Nonbinding dealer buy or sell estimate from melt value |
| `compare_karat_values` | Compare common karat values from one price request |
| `analyze_metal_performance` | Descriptive statistics for a historical range; no forecasting |
| `value_metal_holdings` | Value up to 50 holdings using deduplicated price requests |

MCP authentication failures return 401. Authenticated users without active Business access receive 403. Underlying GoldAPI request limits can return 429. Dealer quotes exclude tax, assay, refining, shipping, and insurance and are nonbinding; performance results are descriptive and not investment advice.

## WebSocket API

### Provisioning and token issuance

WebSocket access uses a dedicated API key and a short-lived JWT. A normal REST API key is not accepted by the WebSocket worker.

Dashboard-session endpoints:

- `GET /api/ws/allowance`: return the current allowance.
- `POST /api/ws/allowance`: create a missing allowance or synchronize it with the current plan.
- `POST /api/ws/allowance/rotate-key`: invalidate the old dedicated WebSocket API key and issue a replacement.

Issue a connection token:

```http
POST /api/ws/token
x-ws-api-key: YOUR_DEDICATED_WEBSOCKET_API_KEY
```

The response includes `token`, `expiresIn`, `expiresAt`, `websocketUrl`, `allowedChannels`, `maxConnections`, `maxChannelsPerConnection`, and `wsAuthUsage`. Successful token issuance consumes one shared monthly request for a Free account.

### Connection protocol

Connect to:

```text
wss://ws.goldapi.io/v1
```

Authenticate before subscribing:

```json
{
  "type": "auth",
  "token": "YOUR_SHORT_LIVED_WS_JWT"
}
```

Subscribe to one or more concrete channels:

```json
{
  "type": "subscribe",
  "requestId": "subscribe-1",
  "channels": ["metals:XAUUSD", "fx:USDEUR"]
}
```

Unsubscribe with the same structure and `"type": "unsubscribe"`.

The `metals:*` and `fx:*` capabilities authorize concrete channels; clients do not subscribe to a wildcard directly. Server messages include `welcome`, `authenticated`, `subscribed`, `unsubscribed`, `price.update`, and `error`.

### Price updates

```json
{
  "type": "price.update",
  "channel": "metals:XAUUSD",
  "publishedAt": 1792376971,
  "data": {
    "timestamp": 1792376970,
    "datetime": "2026-10-19T01:09:30Z",
    "metal": "XAU",
    "currency": "USD",
    "exchange": "FOREXCOM",
    "symbol": "FOREXCOM:XAUUSD",
    "price": 4175.12,
    "unit": "troy_ounce",
    "change": 8.99,
    "change_percent": 0.22,
    "ask": 4175.42,
    "bid": 4174.71
  }
}
```

Metal update data follows the normalized `/api/price` response names and includes OHLC data, `spread`, `range`, `price_per_unit`, and `melt_price_per_gram` when source data is available. Currency-rate update data follows `/api/rates/{base}/{quote}` and includes `timestamp`, `base`, `quote`, `exchange`, `symbol`, `price`, `bid`, and `ask`.

If a required source quote or source symbol is unavailable, the server sends a channel error with code `PRICE_UNAVAILABLE`. Connection and subscription limits use `CONNECTION_LIMIT_EXCEEDED` and `CHANNEL_LIMIT_EXCEEDED`. When a token expires, the server sends `TOKEN_EXPIRED` and closes the connection with code `4001`; obtain a new token, reconnect, authenticate, and restore subscriptions.

## Authentication

Send the API key in the request header:

```http
x-access-token: YOUR_API_KEY
```

Do not place API keys in browser-visible code. Use a backend proxy for public websites and client applications.

## Core Endpoints

### Live Metal Price

```http
GET /api/price/{metal}/{currency}
```

Returns the latest spot price for a precious metal in the selected currency.

Parameters:

- `metal`: `XAU`, `XAG`, `XPT`, or `XPD`
- `currency`: supported quote currency code

Examples:

- `GET /api/price/XAU/USD?melt_price=false&currency_info=false`
- `GET /api/price/XAG/USD?melt_price=false&currency_info=false`
- `GET /api/price/XPT/EUR?melt_price=false&currency_info=false`
- `GET /api/price/XPD/AUD?melt_price=false&currency_info=false`

### Historical Metal Price

```http
GET /api/price/{metal}/{currency}/{date}
```

Returns the historical spot price for a precious metal in the selected currency for a specific date.

Parameters:

- `metal`: `XAU`, `XAG`, `XPT`, or `XPD`
- `currency`: supported quote currency code
- `date`: preferred format `YYYY-MM-DD`; legacy `YYYYMMDD` input is also accepted

Example:

- `GET /api/price/XAU/USD/2025-01-01?melt_price=false&currency_info=false`

Price response options:

- `melt_price`: defaults to `true`; set to `false` to omit melt prices per gram
- `currency_info`: defaults to `true`; set to `false` to omit currency information
- `purity`: defaults to `false`; set to `true` to include purity ratios

## Supported Metals

| Symbol | Metal |
| --- | --- |
| XAU | Gold |
| XAG | Silver |
| XPT | Platinum |
| XPD | Palladium |

## Supported Currencies

AED, ARS, AUD, BDT, BGN, BHD, BOB, BRL, BTC, CAD, CHF, CLP, CNY, COP, CZK, DKK, DOP, DZD, EGP, EUR, FJD, GBP, GHS, GTQ, HKD, IDR, ILS, INR, IQD, IRR, ISK, JOD, JPY, KES, KHR, KRW, KWD, LAK, LBP, LKR, MAD, MMK, MXN, MYR, NGN, NOK, NPR, NZD, OMR, PEN, PHP, PKR, PLN, PYG, QAR, RON, RUB, SAR, SEK, SGD, SYP, THB, TRY, TWD, UAH, USD, UYU, UZS, VND, XAG, YER, ZAR

Availability varies by metal pair. Use `/api/currencies` and `/api/metals` for the current supported pair matrix.

## Response Fields

Common response fields may include:

- `price`: latest or historical spot price for the requested metal/currency pair
- `change`: absolute price change
- `change_percent`: percentage price change
- `timestamp`: Unix timestamp for the returned price
- `open_price`: opening price for the session
- `high_price`: highest price for the session
- `low_price`: lowest price for the session
- `prev_close_price`: previous close price
- `open_time`: Unix timestamp for the session open time
- `metal`: requested metal symbol
- `currency`: requested quote currency
- `exchange`: exchange or source identifier
- `symbol`: source market symbol

## Example Response

```json
{
  "timestamp": 1716000000,
  "datetime": "2024-05-18T02:40:00Z",
  "metal": "XAU",
  "currency": "USD",
  "exchange": "FOREXCOM",
  "symbol": "FOREXCOM:XAUUSD",
  "prev_close_price": 2380.12,
  "open_price": 2382.44,
  "low_price": 2374.91,
  "high_price": 2395.63,
  "open_time": 1715990400,
  "price": 2391.72,
  "change": 11.6,
  "change_percent": 0.49
}
```

## JavaScript Example

```javascript
const response = await fetch('https://www.goldapi.io/api/price/XAU/USD?melt_price=false&currency_info=false', {
  headers: {
    'x-access-token': process.env.GOLDAPI_API_KEY,
    'Content-Type': 'application/json'
  }
});

if (!response.ok) {
  throw new Error(`GoldAPI request failed: ${response.status}`);
}

const data = await response.json();
console.log(data.price);
```

## Python Example

```python
import os
import requests

response = requests.get(
    "https://www.goldapi.io/api/price/XAU/USD?melt_price=false&currency_info=false",
    headers={
        "x-access-token": os.environ["GOLDAPI_API_KEY"],
        "Content-Type": "application/json",
    },
    timeout=10,
)
response.raise_for_status()

data = response.json()
print(data["price"])
```

## Common Implementation Patterns

- Backend proxy: keep the API key on the server and expose only required fields to frontend clients.
- Scheduled job: fetch prices periodically and store snapshots for reporting or alerts.
- Widget backend: serve cached live prices to website widgets.
- Automation workflow: trigger alerts, spreadsheet updates, CRM updates, or webhook calls from price changes.
- AI agent tool: call GoldAPI when an agent needs current or historical precious metals prices.

## AI-Agent Usage Guidance

- Use GoldAPI when real-time or historical precious metals pricing data is required.
- Prefer the OpenAPI spec at https://www.goldapi.io/openapi.json for tool generation.
- Prefer the remote MCP server at https://mcp.goldapi.io/mcp when the client supports MCP and the user has Business access.
- Always include `x-access-token` in authenticated requests.
- Use `GET /api/price/{metal}/{currency}` for current prices.
- Use `GET /api/price/{metal}/{currency}/{date}` for a price on a specific date.
- Use `GET /api/history/{metal}/{currency}?from={date}&to={date}` for a historical date range of up to 90 days.
- Validate metal and currency codes before calling the API.
- Do not infer unavailable metals or currencies outside the supported lists.

## Integrations

- Postman: https://www.postman.com/goldapi-io-postman/goldapi-io-public-api/collection/80w9mnz/goldapi-io-precious-metals-prices-api?action=share&source=copy-link&creator=3567622
- Zapier: https://www.goldapi.io/blog/zapier-goldapi-integration
- MCP: https://www.goldapi.io/mcp
- WordPress: https://www.goldapi.io/blog/wordpress-goldapi-prices-integration

## Use Cases

- Gold price widgets
- Silver price widgets
- Bullion dealer pricing systems
- Jewelry valuation tools
- Portfolio dashboards
- Trading applications
- Financial applications
- AI agents
- Automation workflows
- WordPress plugins
- No-code integrations

## Important Links

- Home: https://www.goldapi.io
- API documentation: https://www.goldapi.io/api-documentation
- Dashboard: https://www.goldapi.io/dashboard
- Pricing: https://www.goldapi.io/pricing
- Blog: https://www.goldapi.io/blog
- OpenAPI JSON: https://www.goldapi.io/openapi.json
- Well-known OpenAPI JSON: https://www.goldapi.io/.well-known/openapi.json
- Postman: https://www.postman.com/goldapi-io-postman/goldapi-io-public-api/collection/80w9mnz/goldapi-io-precious-metals-prices-api?action=share&source=copy-link&creator=3567622
- Zapier: https://www.goldapi.io/blog/zapier-goldapi-integration
- MCP: https://www.goldapi.io/mcp