MetalpriceAPI

https://metalpriceapi.com/documentation
Admin
MetalpriceAPI provides a simple JSON-based REST API for live and historical precious metals and...
Tokens:12,575
Snippets:78
Trust Score:7.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Change API Response Example

Source: https://metalpriceapi.com/documentation

This JSON structure illustrates the response for a currency change query, detailing start and end rates, and the calculated change and percentage change.

```json
{
  "success": true,
  "base": "USD",
  "start_date": "2021-04-20",
  "end_date": "2021-04-21",
  "rates": {
      "XAU": {
        "start_rate": 0.00059101,
        "end_rate": 0.00059256,
        "change": 0.00000155,
        "change_pct": 0.2623
      }
  }
}
```

--------------------------------

### API Endpoint Examples

Source: https://metalpriceapi.com/documentation

Examples of different API endpoints for fetching currency symbols, latest rates, historical data, hourly data, OHLC prices, currency conversions, timeframes, changes, carat prices, and usage status.

```bash
// "symbols" - get list of all supported currencies
https://api.metalpriceapi.com/v1/symbols
```

```bash
// "latest" - get real-time rate data for all available/specific currencies
https://api.metalpriceapi.com/v1/latest
```

```bash
// "historical" - get historical rates for a specific day
https://api.metalpriceapi.com/v1/YYYY-MM-DD
```

```bash
// "hourly" - get hourly rate data for a currency over a date range
https://api.metalpriceapi.com/v1/hourly?currency=XAU&start_date=2025-11-03&end_date=2025-11-03
```

```bash
// "ohlc" - get open, high, low, and close prices for a currency pair
https://api.metalpriceapi.com/v1/ohlc?base=XAU¤cy=USD&date=2025-01-28
```

```bash
// "convert" - convert one currency to another based on real-time or historic rate data
https://api.metalpriceapi.com/v1/convert?from=USD&to=XAU&amount=100
```

```bash
// "timeframe" - request rates for a specific period of time
https://api.metalpriceapi.com/v1/timeframe?start_date=2021-01-01&end_date=2021-05-01
```

```bash
// "change" - request any currency change parameters (margin, percentage)
https://api.metalpriceapi.com/v1/change?base=XAU&start_date=2021-01-01&end_date=2021-05-01
```

```bash
// "carat" - request gold prices by Carat
https://api.metalpriceapi.com/v1/carat
```

```bash
// "usage" - check your API usage and quota for the current month
https://api.metalpriceapi.com/v1/usage
```

--------------------------------

### API Usage Response Example

Source: https://metalpriceapi.com/documentation

This is an example of the JSON response when checking API usage. It indicates success, the user's plan, requests used, total quota, and remaining quota for the current month.

```json
{
  "success": true,
  "result": {
      "plan": "Business",
      "used": 12,
      "total": 100,
      "remaining": 88
  }
}
```

--------------------------------

### Example API Response Structure

Source: https://metalpriceapi.com/documentation

This is an example of the JSON response structure for historical rates, including success status, base currency, timestamp, and the requested rates.

```json
{
  "success": true,
  "base": "USD",
  "timestamp": 1616558399,
  "rates": {
      "EUR": 0.8255334,
      "XAG": 0.03602543,
      "XAU": 0.00053853,
      "USDEUR": 1.211338027,
      "USDXAG": 27.75816972,
      "USDXAU": 1856.906765
  }
}
```

--------------------------------

### Example API Response for Symbols

Source: https://metalpriceapi.com/documentation

This is an example of the JSON response when requesting supported symbols. It includes a success status and a 'symbols' object containing currency codes and their descriptions.

```json
{
  "success": true,
  "symbols": {
      "AED": "UAE Dirham",
      "AFN": "Afghan Afghani",
      "ALL": "Albanian Lek",
      ...
  }
}
```

--------------------------------

### Timeframe API Response Example

Source: https://metalpriceapi.com/documentation

This is an example of the JSON response structure for a successful timeframe query, showing rates for specified dates and currencies.

```json
{
  "success": true,
  "base": "USD",
  "start_date": "2021-04-22",
  "end_date": "2021-04-23",
  "rates": {
      "2021-04-22": {
        "EUR": 0.83233837,
        "XAG": 0.03825732,
        "XAU": 0.00056078,
        "USDEUR": 1.20143446,
        "USDXAG": 26.1387886,
        "USDXAU": 1783.2305
      },
      "2021-04-23": {
        "EUR": 0.82657397,
        "XAG": 0.03846131,
        "XAU": 0.0005628,
        "USDEUR": 1.209813079,
        "USDXAG": 26.00015444,
        "USDXAU": 1776.830135
      }
  }
}
```

--------------------------------

### Carat API Response Example

Source: https://metalpriceapi.com/documentation

This is an example of the JSON response when requesting gold prices by carat. It includes success status, base currency, timestamp, and a 'data' object containing prices for different carats.

```json
{
  "success": true,
  "base": "USD",
  "timestamp": 1650130340,
  "data": {
        "24k": 12.69083155,
        "23k": 12.16204691,
        "22k": 11.63326226,
        "21.6k": 11.42174839,
        "21k": 11.10447761,
        "18k": 9.51812367,
        "16k": 8.46055437,
        "14k": 7.40298507,
        "12k": 6.34541578,
        "10k": 5.28784648,
        "9k": 4.75906183,
        "8k": 4.23027718,
        "6k": 3.17270789
      }
  }
```

--------------------------------

### Example Usage with Regional Endpoints

Source: https://metalpriceapi.com/documentation

Demonstrates how to use the US and EU regional API endpoints for fetching the latest rates. Ensure you include your API key in the request.

```bash
// US endpoint
https://api.metalpriceapi.com/v1/latest?api_key=API_KEY
```

```bash
// EU endpoint
https://api-eu.metalpriceapi.com/v1/latest?api_key=API_KEY
```

--------------------------------

### Get List of Supported Currencies

Source: https://metalpriceapi.com/documentation

Retrieves a list of all supported currency symbols available through the API.

```APIDOC
## GET /symbols

### Description
Get a list of all supported currency symbols.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/symbols
```

--------------------------------

### Get Historical Rates for a Timeframe

Source: https://metalpriceapi.com/documentation

Use this endpoint to fetch historical exchange rates for a given period. Specify start and end dates, base currency, and optionally filter by currencies or units.

```http
https://api.metalpriceapi.com/v1/timeframe
?api_key=[API_KEY]
&start_date=2021-04-22
&end_date=2021-04-23
&base=USD
&currencies=EUR,XAU,XAGCopy
```

--------------------------------

### Example API Response for Live Rates

Source: https://metalpriceapi.com/documentation

This JSON response provides live exchange rates. It includes the success status, base currency, timestamp, and a 'rates' object containing the requested currency exchange rates.

```json
{
  "success": true,
  "base": "USD",
  "timestamp": 1625609377,
  "rates": {
      "EUR": 0.8255334,
      "XAG": 0.03602543,
      "XAU": 0.00053853,
      "USDEUR": 1.211338027,
      "USDXAG": 27.75816972,
      "USDXAU": 1856.906765
  }
}
```

--------------------------------

### Get Currency Change Parameters

Source: https://metalpriceapi.com/documentation

Requests any currency change parameters, such as margin and percentage, over a specified period.

```APIDOC
## GET /change

### Description
Request any currency change parameters (margin, percentage).

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/change

### Query Parameters
- **api_key** (string) - Required - Your API access key.
- **base** (string) - Required - The base currency (e.g., XAU).
- **start_date** (string) - Required - The start date of the period (YYYY-MM-DD).
- **end_date** (string) - Required - The end date of the period (YYYY-MM-DD).
```

--------------------------------

### Get Latest Exchange Rates

Source: https://metalpriceapi.com/documentation

Fetches real-time exchange rate data for all available currencies or specific ones.

```APIDOC
## GET /latest

### Description
Get real-time rate data for all available or specific currencies.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/latest

### Query Parameters
- **api_key** (string) - Required - Your API access key.
- **base** (string) - Optional - The base currency to convert from (e.g., USD).
```

--------------------------------

### Hourly Rates API Response Example

Source: https://metalpriceapi.com/documentation

The API response includes success status, base currency, date range, and an array of hourly rates with timestamps and exchange values.

```json
{
  "success": true,
  "base": "USD",
  "start_date": "2025-11-03",
  "end_date": "2025-11-03",
  "rates": [
    {
      "timestamp": 1762128000,
      "rates": {
        "XAU": 0.0002512844,
        "USDXAU": 3979.5546400811
      }
    },
    {
      "timestamp": 1762131600,
      "rates": {
        "XAU": 0.0002519176,
        "USDXAU": 3969.5519487324
      }
    },
    ...
  ]
}
```

--------------------------------

### Example API Error Response

Source: https://metalpriceapi.com/documentation

Illustrates a typical JSON response when an API query fails. It includes a 'success' flag, an 'error' object with a 'code', and an 'info' message detailing the issue.

```json
{
  "success": false,
  "error": {
      "code": 104,
      "info": "Your monthly usage limit has been reached. Please upgrade your subscription plan."
  }
}
```

--------------------------------

### Get Live Exchange Rates

Source: https://metalpriceapi.com/documentation

Fetch real-time exchange rate data. You can specify a base currency and a comma-separated list of target currencies. The 'math' parameter allows for basic calculations on the rates.

```http
https://api.metalpriceapi.com/v1/latest
?api_key=[API_KEY]
&base=USD
&currencies=EUR,XAU,XAGCopy
```

```http
https://api.metalpriceapi.com/v1/latest
?api_key=[API_KEY]
&base=USD
&currencies=XAU,XAG
&math=add(multiply(value,1.1),10)Copy
```

--------------------------------

### Get Open, High, Low, Close (OHLC) Prices

Source: https://metalpriceapi.com/documentation

Retrieves the open, high, low, and close prices for a specified currency pair on a given date.

```APIDOC
## GET /ohlc

### Description
Get open, high, low, and close prices for a currency pair.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/ohlc

### Query Parameters
- **api_key** (string) - Required - Your API access key.
- **base** (string) - Required - The base currency (e.g., XAU).
- **currency** (string) - Required - The target currency (e.g., USD).
- **date** (string) - Required - The date for which to retrieve OHLC data (YYYY-MM-DD).
```

--------------------------------

### Get Supported Symbols

Source: https://metalpriceapi.com/documentation

Use this endpoint to retrieve a list of all currency symbols supported by the API. Requests to this endpoint do not count towards your API quota.

```http
https://api.metalpriceapi.com/v1/symbols
?api_key=[API_KEY]Copy
```

--------------------------------

### Get Hourly Exchange Rates

Source: https://metalpriceapi.com/documentation

Fetches hourly exchange rate data for a specified currency over a date range.

```APIDOC
## GET /hourly

### Description
Get hourly rate data for a currency over a date range.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/hourly

### Query Parameters
- **api_key** (string) - Required - Your API access key.
- **currency** (string) - Required - The currency for which to retrieve hourly data (e.g., XAU).
- **start_date** (string) - Required - The start date for the hourly data (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the hourly data (YYYY-MM-DD).
```

--------------------------------

### Get Historical Exchange Rates

Source: https://metalpriceapi.com/documentation

Retrieves historical exchange rate data for a specific day.

```APIDOC
## GET /historical

### Description
Get historical rates for a specific day.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/YYYY-MM-DD

### Parameters
#### Path Parameters
- **YYYY-MM-DD** (string) - Required - The date for which to retrieve historical rates (e.g., 2023-10-27).

#### Query Parameters
- **api_key** (string) - Required - Your API access key.
- **base** (string) - Optional - The base currency to convert from (e.g., USD).
```

--------------------------------

### Get Gold Prices by Carat

Source: https://metalpriceapi.com/documentation

Retrieves gold prices categorized by Carat.

```APIDOC
## GET /carat

### Description
Request gold prices by Carat.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/carat

### Query Parameters
- **api_key** (string) - Required - Your API access key.
```

--------------------------------

### Get Timeframe Rates

Source: https://metalpriceapi.com/documentation

Requests exchange rates for a specific period of time.

```APIDOC
## GET /timeframe

### Description
Request rates for a specific period of time.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/timeframe

### Query Parameters
- **api_key** (string) - Required - Your API access key.
- **start_date** (string) - Required - The start date of the period (YYYY-MM-DD).
- **end_date** (string) - Required - The end date of the period (YYYY-MM-DD).
- **base** (string) - Optional - The base currency (e.g., USD).
```

--------------------------------

### Get Yesterday's Historical Rates

Source: https://metalpriceapi.com/documentation

Retrieve yesterday's historical exchange rates. Replace [API_KEY] with your actual key. The base currency defaults to USD if not specified.

```http
https://api.metalpriceapi.com/v1/yesterday
?api_key=[API_KEY]
&base=USD
&currencies=EUR,XAU,XAGCopy
```

--------------------------------

### Request Gold Rate by Carat

Source: https://metalpriceapi.com/documentation

Use this endpoint to get gold prices for different carats. Specify base currency, target currency (XAU by default), and an optional date. The response includes prices for various carats like 24k, 22k, etc.

```http
https://api.metalpriceapi.com/v1/carat
?api_key=[API_KEY]
&base=USD
&currency=XAU
&date=2021-04-23Copy
```

--------------------------------

### Get Historical Rates by Date

Source: https://metalpriceapi.com/documentation

Request historical exchange rates for a specific date. Ensure to replace [API_KEY] with your actual key. The base currency defaults to USD if not specified.

```http
https://api.metalpriceapi.com/v1/2021-03-24
?api_key=[API_KEY]
&base=USD
&currencies=EUR,XAU,XAGCopy
```

--------------------------------

### Hourly Rates API Request (Date Form)

Source: https://metalpriceapi.com/documentation

Use this format to request hourly exchange rates by specifying start and end dates. Ensure only one currency is requested per API call.

```http
https://api.metalpriceapi.com/v1/hourly
?api_key=[API_KEY]
&base=USD
&currency=XAU
&start_date=2025-11-03
&end_date=2025-11-03Copy
```

--------------------------------

### Get OHLC Data for Currency Pair

Source: https://metalpriceapi.com/documentation

Retrieve open, high, low, and close prices for a specified currency pair on a given date. The API uses a 00:00 to 23:59:59 GMT trading day.

```HTTP
https://api.metalpriceapi.com/v1/ohlc
?api_key=[API_KEY]
&base=XAU
&currency=USD
&date=2025-01-28Copy
```

```JSON
{
  "success": true,
  "base": "XAU",
  "quote": "USD",
  "timestamp": 1738108799,
  "rate": {
      "close": 2742.2233288617,
      "high": 2764.9591200794,
      "low": 2735.1078165826,
      "open": 2741.9706872366
  }
}
```

--------------------------------

### Request Currency Change Over Timeframe

Source: https://metalpriceapi.com/documentation

Use this endpoint to get the percentage change of one or more currencies relative to a base currency over a specified period. This endpoint can also use predefined date types like 'recent', 'week', 'month', or 'year'.

```http
https://api.metalpriceapi.com/v1/change
?api_key=[API_KEY]
&start_date=2021-04-22
&end_date=2021-04-23
&base=USD
&currencies=XAUCopy
```

--------------------------------

### Latest Rates Endpoint

Source: https://metalpriceapi.com/documentation

Use this endpoint to fetch the latest live rates. Append your API key to the URL.

```url
https://api.metalpriceapi.com/v1/latest?api_key=[API_KEY]Copy
```

--------------------------------

### Live Rates

Source: https://metalpriceapi.com/documentation

Fetches real-time (delayed) exchange rate data based on your subscription plan. You can specify base and target currencies, and apply mathematical operations.

```APIDOC
## GET /v1/latest

### Description
This endpoint will return real-time exchange rate data (delayed) depending on your subscription plan.

### Method
GET

### Endpoint
/v1/latest

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **base** (string) - Optional - Specify a base currency. Defaults to USD if not defined.
- **currencies** (string) - Optional - Specify a comma-separated list of currency codes to limit API responses to specified currencies. If not defined, all forex currencies and precious metals are returned.
- **unit** (string) - Optional - Specify **troy_oz**, **gram**, or **kilogram**. Defaults to troy ounce if not defined. (Paid plan only)
- **math** (string) - Optional - Specify math operators to perform on the result. Use **value** to refer to the rates. Supports **add**, **subtract**, **multiply**, and/or **divide**.

### Request Example
```
https://api.metalpriceapi.com/v1/latest?api_key=[API_KEY]&base=USD&currencies=EUR,XAU,XAG
```
```
https://api.metalpriceapi.com/v1/latest?api_key=[API_KEY]&base=USD&currencies=XAU,XAG&math=add(multiply(value,1.1),10)
```

### Response
#### Success Response (200)
- **success** (boolean) - Returns true or false depending if the API Request succeeded.
- **base** (string) - Returns base currency used for the request.
- **timestamp** (integer) - Returns the UNIX timestamp the given exchange rates were collected.
- **rates** (object) - Returns exchange rate data for the currencies requested.

#### Response Example
```json
{
  "success": true,
  "base": "USD",
  "timestamp": 1625609377,
  "rates": {
      "EUR": 0.8255334,
      "XAG": 0.03602543,
      "XAU": 0.00053853
  }
}
```
```

--------------------------------

### Check API Usage

Source: https://metalpriceapi.com/documentation

Checks your API usage and quota for the current month.

```APIDOC
## GET /usage

### Description
Check your API usage and quota for the current month.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/usage

### Query Parameters
- **api_key** (string) - Required - Your API access key.
```

--------------------------------

### Open/High/Low/Close (OHLC) Data

Source: https://metalpriceapi.com/documentation

Retrieve open, high, low, and close prices for a given currency pair. OHLC data uses a 00:00 to 23:59:59 GMT trading day.

```APIDOC
## GET /v1/ohlc

### Description
This endpoint will return open, high, low, and close prices for a given currency pair.
OHLC data uses a **00:00 to 23:59:59 GMT** trading day. The **open** price is captured at midnight GMT (00:00), and the **close** price is captured at 23:59:59 GMT. The previous day's OHLC data becomes available at **00:05 AM GMT**.

### Method
GET

### Endpoint
/v1/ohlc

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **base** (string) - Optional - Specify a base currency. Base Currency will default to USD if this parameter is not defined.
- **currency** (string) - Required - Specify a currency.
- **date** (string) - Required - Specify a date in the format `YYYY-MM-DD` to get the OHLC for specified date.
- **unit** (string) - Optional - (Paid plan) Specify **troy_oz** or **gram** or **kilogram**. If not defined, the API will return metals in troy ounce.
- **date_type** (string) - Optional - (Paid plan) Specify "yesterday", "week", "month", or "year" to retrieve the rate change for the corresponding time period. If provided, this parameter overrides "date".

### Request Example
```json
{
  "api_key": "[API_KEY]",
  "base": "XAU",
  "currency": "USD",
  "date": "2025-01-28"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Returns true or false depending if the API Request succeeded.
- **base** (string) - Returns base currency used for the request.
- **quote** (string) - Returns quote currency used for the request.
- **timestamp** (integer) - Returns the UNIX timestamp for the OHLC data.
- **rate** (object) - Contains OHLC price data.
  - **close** (number) - Returns close price for the specified date.
  - **high** (number) - Returns high price for the specified date.
  - **low** (number) - Returns low price for the specified date.
  - **open** (number) - Returns open price for the specified date.

#### Response Example
```json
{
  "success": true,
  "base": "XAU",
  "quote": "USD",
  "timestamp": 1738108799,
  "rate": {
      "close": 2742.2233288617,
      "high": 2764.9591200794,
      "low": 2735.1078165826,
      "open": 2741.9706872366
  }
}
```
```

--------------------------------

### API Key Authentication - Query Parameter

Source: https://metalpriceapi.com/documentation

Authenticate requests by appending your API key as a query parameter to the request URL.

```url
https://api.metalpriceapi.com/v1/latest?api_key=API_KEYCopy
```

--------------------------------

### Change Query

Source: https://metalpriceapi.com/documentation

Request the percentage change of one or more currencies relative to a base currency within a specified timeframe.

```APIDOC
## GET /v1/change

### Description
This endpoint is used to request the change (percentage) of one of more currencies, relative to a `base` currency with a specific time-frame (optional). The API will return `change` values of the specified `start_date` and `end_date`.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/change

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **start_date** (string) - Required - Specify the start date of your timeframe.
- **end_date** (string) - Required - Specify the end date of your timeframe.
- **base** (string) - Optional - Specify a base currency. Defaults to USD.
- **currencies** (string) - Optional - Specify a comma-separated list of currency codes to limit API responses. Returns all supported currencies if not defined.
- **date_type** (string) - Optional - Specify "recent", "yesterday", "week", "month", or "year" to retrieve the rate change for the corresponding time period. If provided, this parameter overrides "start_date" and "end_date".
  - **recent**: Calculates change from yesterday's closing rate to the current rate.
  - **yesterday**: Calculates change from start of yesterday to end of yesterday.
  - **week**: Calculates change over the last 7 days.
  - **month**: Calculates change over the last month.
  - **year**: Calculates change over the last year.

### Request Example
```json
https://api.metalpriceapi.com/v1/change?api_key=[API_KEY]&start_date=2021-04-22&end_date=2021-04-23&base=USD&currencies=XAU
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the API request succeeded.
- **base** (string) - Base currency used for the request.
- **start_date** (string) - Start date of the timeframe.
- **end_date** (string) - End date of the timeframe.
- **rates** (object) - Exchange rate data for the currencies requested.
  - **rates -> [currency_code]** (object) - Change data for a specific currency.
    - **rates -> [currency_code] -> start_rate** (number) - Exchange rate for the start date.
    - **rates -> [currency_code] -> end_rate** (number) - Exchange rate for the end date.
    - **rates -> [currency_code] -> change** (number) - Change (decimal number) of the currency rate between start and end date.
    - **rates -> [currency_code] -> change_pct** (number) - Percent change of the currency rate. Formula: `((end_rate - start_rate) / start_rate) * 100`.

#### Response Example
```json
{
  "success": true,
  "base": "USD",
  "start_date": "2021-04-20",
  "end_date": "2021-04-21",
  "rates": {
      "XAU": {
        "start_rate": 0.00059101,
        "end_rate": 0.00059256,
        "change": 0.00000155,
        "change_pct": 0.2623
      }
  }
}
```
```

--------------------------------

### Currency Conversion

Source: https://metalpriceapi.com/documentation

Convert any amount from one currency to another. This endpoint can use live or historical exchange rates.

```APIDOC
## GET /v1/convert

### Description
This endpoint is used to convert any amount from one currency to another.

### Method
GET

### Endpoint
/v1/convert

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **from** (string) - Optional - Specify currency you would like to convert from. Base Currency will default to USD if this parameter is not defined.
- **to** (string) - Required - Specify currency you would like to convert to.
- **amount** (number) - Required - The amount to convert.
- **date** (string) - Optional - Specify date to use historical midpoint value for conversion. Otherwise, it will use live exchange rate date.
- **unit** (string) - Optional - (Paid plan) Specify **troy_oz** or **gram** or **kilogram**. If not defined, the API will return metals in troy ounce.

### Request Example
```json
{
  "api_key": "[API_KEY]",
  "from": "USD",
  "to": "XAU",
  "amount": 100,
  "date": "2021-04-23"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Returns true or false depending if the API Request succeeded.
- **query** (object) - Contains details of the conversion query.
  - **from** (string) - Returns currency converted from used for the request.
  - **to** (string) - Returns currency converted to used for the request.
  - **amount** (number) - Returns amount to convert.
- **info** (object) - Contains additional information about the conversion.
  - **quote** (number) - Returns the exchange rate used for the conversion.
  - **timestamp** (integer) - Returns the UNIX timestamp the given exchange rates were collected.
- **result** (number) - Returns conversion result.

#### Response Example
```json
{
  "success": true,
  "query": {
      "from": "USD",
      "to": "XAU",
      "amount": 100
  },
  "info": {
      "quote": 0.0005628,
      "timestamp": 1619150400
  },
  "result": 0.05628031
}
```
```

--------------------------------

### Usage

Source: https://metalpriceapi.com/documentation

This endpoint is used to check your API usage and quota for the current month. Requests to this endpoint do not count towards your monthly API quota.

```APIDOC
## GET /v1/usage

### Description
This endpoint is used to check your API usage and quota for the current month. Requests to this endpoint do not count towards your monthly API quota.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/usage

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.

### Request Example
```
https://api.metalpriceapi.com/v1/usage?api_key=[API_KEY]
```

### Response
#### Success Response (200)
- **success** (boolean) - Returns true or false depending if the API Request succeeded.
- **result** (object) - Contains usage details.
  - **plan** (string) - Returns your current plan.
  - **used** (integer) - Returns the number of requests used for the current month.
  - **total** (integer) - Returns your total quota for the current month.
  - **remaining** (integer) - Returns your remaining quota for the current month.

#### Response Example
```json
{
  "success": true,
  "result": {
      "plan": "Business",
      "used": 12,
      "total": 100,
      "remaining": 88
  }
}
```
```

--------------------------------

### Convert Currency

Source: https://metalpriceapi.com/documentation

Converts an amount from one currency to another using real-time or historical rates.

```APIDOC
## GET /convert

### Description
Convert one currency to another based on real-time or historic rate data.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/convert

### Query Parameters
- **api_key** (string) - Required - Your API access key.
- **from** (string) - Required - The currency to convert from (e.g., USD).
- **to** (string) - Required - The currency to convert to (e.g., XAU).
- **amount** (number) - Required - The amount to convert (e.g., 100).
- **date** (string) - Optional - The date for historical conversion (YYYY-MM-DD).
```

--------------------------------

### Supported Symbols

Source: https://metalpriceapi.com/documentation

Retrieves a list of all currency symbols supported by the API. This request does not count towards your API quota.

```APIDOC
## GET /v1/symbols

### Description
This endpoint is used to get the list of the most up-to-date supported symbols.

### Method
GET

### Endpoint
/v1/symbols

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.

### Request Example
```
https://api.metalpriceapi.com/v1/symbols?api_key=[API_KEY]
```

### Response
#### Success Response (200)
- **success** (boolean) - Returns true or false depending if the API Request succeeded.
- **symbols** (object) - Key is supported currency, value is description of currency.

#### Response Example
```json
{
  "success": true,
  "symbols": {
      "AED": "UAE Dirham",
      "AFN": "Afghan Afghani",
      "ALL": "Albanian Lek"
  }
}
```
```

--------------------------------

### Hourly Rates

Source: https://metalpriceapi.com/documentation

Retrieves hourly exchange rate data for a specified currency over a given date range. Supports date or timestamp parameters and offers options for paid users.

```APIDOC
## GET /v1/hourly

### Description
This endpoint returns hourly exchange rate data for a given currency over a specified date range. It provides 24 data points per day, one for each hour. Only one currency is allowed per request. Free users can query up to 2 days; paid users can query up to 7 days. Future dates are not allowed.

### Method
GET

### Endpoint
/v1/hourly

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **base** (string) - Optional - Specify a base currency. Defaults to USD.
- **currency** (string) - Required - Specify a single currency code. Only one currency is allowed per request.
- **start_date** (string) - Optional - Specify the start date in `YYYY-MM-DD` format. Defaults to today. Earliest available date is `2025-06-19`. Cannot be combined with `start`/`end`.
- **end_date** (string) - Optional - Specify the end date in `YYYY-MM-DD` format. Defaults to today. Cannot be combined with `start`/`end`.
- **start** (integer) - Optional - Specify the start as a UNIX timestamp (seconds since epoch). Cannot be combined with `start_date`/`end_date`/`date_type`.
- **end** (integer) - Optional - Specify the end as a UNIX timestamp (seconds since epoch). Defaults to the current hour. Cannot be combined with `start_date`/`end_date`/`date_type`.
- **date_type** (string) - Optional - (Paid plan) Specify "today", "yesterday", or "week" as a shortcut. If provided, this parameter overrides "start_date" and "end_date".
- **unit** (string) - Optional - (Paid plan) Specify **troy_oz** or **gram** or **kilogram**. If not defined, the API will return metals in troy ounce.
- **math** (string) - Optional - (Paid plan) Specify math operators to perform on the result. Use **value** to refer to the rates. Specify one or more of the mathematical operators **add**, **subtract**, **multiply**, and/or **divide**.

### Request Example (date form)
```
https://api.metalpriceapi.com/v1/hourly?api_key=[API_KEY]&base=USD&currency=XAU&start_date=2025-11-03&end_date=2025-11-03
```

### Request Example (timestamp form)
```
https://api.metalpriceapi.com/v1/hourly?api_key=[API_KEY]&base=USD&currency=XAU&start=1762128000&end=1762146000
```

### Response
#### Success Response (200)
- **success** (boolean) - Returns true or false depending if the API Request succeeded.
- **base** (string) - Returns base currency used for the request.
- **start_date** (string) - Returns start date of the hourly query.
- **end_date** (string) - Returns end date of the hourly query.
- **rates** (array) - Array of hourly rate data.
  - **timestamp** (integer) - Returns the UNIX timestamp for the hourly data point.
  - **rates** (object) - Returns exchange rate data for the requested currency.

### Response Example
```json
{
  "success": true,
  "base": "USD",
  "start_date": "2025-11-03",
  "end_date": "2025-11-03",
  "rates": [
    {
      "timestamp": 1762128000,
      "rates": {
        "XAU": 0.0002512844,
        "USDXAU": 3979.5546400811
      }
    },
    {
      "timestamp": 1762131600,
      "rates": {
        "XAU": 0.0002519176,
        "USDXAU": 3969.5519487324
      }
    }
  ]
}
```
```

--------------------------------

### Carat Query

Source: https://metalpriceapi.com/documentation

This endpoint is used to request the gold rate by Carat. It requires an API key and allows specifying base currency, target currency, and date.

```APIDOC
## GET /v1/carat

### Description
This endpoint is used to request the gold rate by Carat.

### Method
GET

### Endpoint
https://api.metalpriceapi.com/v1/carat

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **base** (string) - Optional - Specify a base currency. Defaults to USD.
- **currency** (string) - Optional - Specify currency to get Carat. Defaults to XAU.
- **date** (string) - Optional - Specify date to get Carat. Defaults to live rates.

### Request Example
```
https://api.metalpriceapi.com/v1/carat?api_key=[API_KEY]&base=USD&currency=XAU&date=2021-04-23
```

### Response
#### Success Response (200)
- **success** (boolean) - Returns true or false depending if the API Request succeeded.
- **base** (string) - Returns base currency used for the request.
- **timestamp** (integer) - Returns the UNIX timestamp the given exchange rates were collected.
- **data** (object) - Returns carat data.

#### Response Example
```json
{
  "success": true,
  "base": "USD",
  "timestamp": 1650130340,
  "data": {
        "24k": 12.69083155,
        "23k": 12.16204691,
        "22k": 11.63326226,
        "21.6k": 11.42174839,
        "21k": 11.10447761,
        "18k": 9.51812367,
        "16k": 8.46055437,
        "14k": 7.40298507,
        "12k": 6.34541578,
        "10k": 5.28784648,
        "9k": 4.75906183,
        "8k": 4.23027718,
        "6k": 3.17270789
      }
  }
```
```

--------------------------------

### Check API Usage and Quota

Source: https://metalpriceapi.com/documentation

This endpoint allows you to check your current monthly API usage and quota. Requests to this endpoint do not count against your monthly API quota.

```http
https://api.metalpriceapi.com/v1/usage
?api_key=[API_KEY]Copy
```

--------------------------------

### Hourly Rates API Request (Timestamp Form)

Source: https://metalpriceapi.com/documentation

This format allows requesting hourly exchange rates using UNIX timestamps for precise hour-based queries. Do not mix timestamp parameters with date parameters.

```http
https://api.metalpriceapi.com/v1/hourly
?api_key=[API_KEY]
&base=USD
&currency=XAU
&start=1762128000
&end=1762146000Copy
```

--------------------------------

### Convert Currency Amount

Source: https://metalpriceapi.com/documentation

Convert a specified amount from one currency to another. You can use a specific date for historical conversion rates. The 'unit' parameter is available for paid plans.

```HTTP
https://api.metalpriceapi.com/v1/convert
?api_key=[API_KEY]
&from=USD
&to=XAU
&amount=100
&date=2021-04-23Copy
```

```JSON
{
  "success": true,
  "query": {
      "from": "USD",
      "to": "XAU",
      "amount": 100
  },
  "info": {
      "quote": 0.0005628,
      "timestamp": 1619150400
  },
  "result": 0.05628031
}
```

--------------------------------

### API Key Authentication - Request Header

Source: https://metalpriceapi.com/documentation

Authenticate requests by passing your API key in the 'X-API-KEY' request header. Ensure 'Content-Type' is set to 'application/json'.

```curl
curl https://api.metalpriceapi.com/v1/latest \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json'
```

--------------------------------

### Historical Rates

Source: https://metalpriceapi.com/documentation

Retrieve historical exchange rate data for a specific date or 'yesterday'. The previous day's rates are available daily at 00:05 AM GMT.

```APIDOC
## GET /v1/[Year-Month-Day]

### Description
This endpoint will return historical exchange rate data for a specified date.

### Method
GET

### Endpoint
`/v1/[date]`

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **base** (string) - Optional - Specify a base currency. Defaults to USD.
- **currencies** (string) - Optional - Comma-separated list of currency codes to limit results. Returns all supported currencies if not defined.
- **unit** (string) - Optional - Specify 'troy_oz', 'gram', or 'kilogram'. Defaults to 'troy_oz'. (Paid plan feature)

### Request Example
```
https://api.metalpriceapi.com/v1/2021-03-24?api_key=[API_KEY]&base=USD&currencies=EUR,XAU,XAG
```

## GET /v1/yesterday

### Description
This endpoint will return historical exchange rate data for the previous day.

### Method
GET

### Endpoint
`/v1/yesterday`

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your API Key.
- **base** (string) - Optional - Specify a base currency. Defaults to USD.
- **currencies** (string) - Optional - Comma-separated list of currency codes to limit results. Returns all supported currencies if not defined.
- **unit** (string) - Optional - Specify 'troy_oz', 'gram', or 'kilogram'. Defaults to 'troy_oz'. (Paid plan feature)

### Request Example
```
https://api.metalpriceapi.com/v1/yesterday?api_key=[API_KEY]&base=USD&currencies=EUR,XAU,XAG
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the API request succeeded.
- **base** (string) - The base currency used for the request.
- **timestamp** (integer) - The UNIX timestamp when the exchange rates were collected.
- **rates** (object) - Exchange rate data for the requested currencies.

### Response Example
```json
{
  "success": true,
  "base": "USD",
  "timestamp": 1616558399,
  "rates": {
      "EUR": 0.8255334,
      "XAG": 0.03602543,
      "XAU": 0.00053853,
      "USDEUR": 1.211338027,
      "USDXAG": 27.75816972,
      "USDXAU": 1856.906765
  }
}
```
```
Tokens:
Raw