# GoldAPI.io

GoldAPI.io provides real-time and historical precious metals prices for Gold, Silver, Platinum and Palladium.

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

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

- RapidAPI: https://www.goldapi.io/rapidapi
- Postman: https://www.goldapi.io/postman
- Zapier: https://www.goldapi.io/zapier
- 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
- RapidAPI: https://www.goldapi.io/rapidapi
- Postman: https://www.goldapi.io/postman
- Zapier: https://www.goldapi.io/zapier
- MCP: https://www.goldapi.io/mcp